From 37db8952227194bd13eb67c0558d33878e310f76 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..0f36710387a735069dbe799d5bb85b361de6bcfd 100644 --- a/includes/file.inc +++ b/includes/file.inc @@ -2192,15 +2192,18 @@ 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. 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. Remote stream wrappers implement the + * realpath method by always returning FALSE. The use of drupal_realpath() is + * discouraged, and 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,8 +2214,9 @@ 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 + * @todo: This function is deprecated, and should be removed wherever possible. */ function drupal_realpath($uri) { // If this URI is a stream, pass it off to the appropriate stream wrapper. -- 1.7.5.4