From 40f483a8423ed4d6a454631be9bf04d8119d827f Mon Sep 17 00:00:00 2001 From: Bob Vincent Date: Sat, 17 Sep 2011 13:06:21 -0400 Subject: [PATCH] Issue #1201024: Update drupal_realpath() documentation to discourage its use. --- includes/file.inc | 20 ++++++++++++-------- 1 files changed, 12 insertions(+), 8 deletions(-) diff --git a/includes/file.inc b/includes/file.inc index 6e2e5cb2828c9f4622b9253feed8a296b463050d..6b2ff94b684c1ec83feac9775042c464a25bacc2 100644 --- a/includes/file.inc +++ b/includes/file.inc @@ -2192,15 +2192,19 @@ function drupal_unlink($uri, $context = NULL) { } /** - * Returns the absolute path of a file or directory + * Returns the absolute local filesystem path of a stream URI. * - * PHP's realpath() does not properly support streams, so this function - * fills that gap. If a stream wrapped URI is provided, it will be passed - * to the registered wrapper for handling. If the URI does not contain a - * scheme or the wrapper implementation does not implement realpath, then - * FALSE will be returned. + * This function was originally written to ease the conversion of 6.x code + * to use 7.x stream wrappers. However, it assumes that every URI may be + * resolved to an absolute local filesystem path. This assumption fails + * when stream wrappers are used to support remote file storage. These + * implementations implement the realpath method by always returning FALSE. + * Therefore, the use of drupal_realpath() is now discouraged, and it is + * slowly being removed from core functions where possible. * - * @see http://php.net/manual/en/function.realpath.php + * Only use this function if you know that the stream wrapper in the URI + * uses the local file system, and you need to pass an absolute path to + * a function that is incompatible with stream URIs. * * Compatibility: normal paths and stream wrappers. * @see http://drupal.org/node/515192 @@ -2211,7 +2215,7 @@ function drupal_unlink($uri, $context = NULL) { * @return * The absolute pathname, or FALSE on failure. * - * @see realpath() + * @see http://php.net/manual/function.realpath.php * @ingroup php_wrappers */ function drupal_realpath($uri) { -- 1.7.5.4