summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorNathaniel Catchpole2013-07-27 15:41:48 +0100
committerNathaniel Catchpole2013-07-27 15:41:48 +0100
commita956eb44e7ff2f304527b0bb413c04ea17073460 (patch)
tree12adc36c142196a361c047eb64c08bc13898ce0f
parent58afd192b8d9655da4bbca2059393b0a838176f1 (diff)
Issue #1201024 by pillarsdotnet, jbrown, tim.plunket: drupal_realpath() should describe when it should be used.
-rw-r--r--core/includes/file.inc24
1 files changed, 8 insertions, 16 deletions
diff --git a/core/includes/file.inc b/core/includes/file.inc
index e1b9d97..5c4a75a 100644
--- a/core/includes/file.inc
+++ b/core/includes/file.inc
@@ -1333,29 +1333,21 @@ function drupal_unlink($uri, $context = NULL) {
}
/**
- * Returns the absolute local filesystem path of a stream URI.
+ * Resolves the absolute filepath of a local URI or filepath.
*
- * 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.
+ * The use of drupal_realpath() is discouraged, because it does not work for
+ * remote URIs. Except in rare cases, URIs should not be manually resolved.
*
* 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 stream wrapper URI or a filesystem path, possibly including one or more
- * symbolic links.
- *
- * @return
- * The absolute local filesystem path (with no symbolic links), or FALSE on
- * failure.
+ * @param string $uri
+ * A stream wrapper URI or a filepath, possibly including one or more symbolic
+ * links.
*
- * @todo This function is deprecated, and should be removed wherever possible.
+ * @return string|false
+ * The absolute local filepath (with no symbolic links), or FALSE on failure.
*
* @see Drupal\Core\StreamWrapper\StreamWrapperInterface::realpath()
* @see http://php.net/manual/function.realpath.php