summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDries Buytaert2011-09-25 09:45:20 (GMT)
committer Dries Buytaert2011-09-25 09:45:20 (GMT)
commit56e1becb0ecaf05abf92cacb0cf02b5992a2501c (patch)
tree60ce5c187050c32363af7fd7ef47c029b7679c0c
parent9e73bfcc6f5f085cdf981520beab2ddb79060f36 (diff)
- Patch #1201024 by pillarsdotnet: drupal_realpath() should describe when it should be used.
-rw-r--r--includes/file.inc31
1 files changed, 18 insertions, 13 deletions
diff --git a/includes/file.inc b/includes/file.inc
index 69e2a62..40e8349 100644
--- a/includes/file.inc
+++ b/includes/file.inc
@@ -2192,27 +2192,32 @@ 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, and this assumption fails when stream
+ * wrappers are used to support remote file storage. Remote stream wrappers
+ * may 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
- *
- * Compatibility: normal paths and stream wrappers.
- * @see http://drupal.org/node/515192
+ * 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.
*
* @param $uri
- * A string containing the URI to verify.
+ * A stream wrapper URI or a filesystem path, possibly including one or more
+ * symbolic links.
*
* @return
- * The absolute pathname, or FALSE on failure.
+ * The absolute local filesystem path (with no symbolic links), or FALSE on
+ * failure.
*
- * @see realpath()
+ * @see DrupalStreamWrapperInterface::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.