From 19e85c0593ad52d12fac1da96003f55ced9aa11d Mon Sep 17 00:00:00 2001 From: David Rothstein Date: Tue, 6 Aug 2013 01:35:38 -0400 Subject: Issue #1201024 by pillarsdotnet, jbrown, tim.plunkett | Damien Tournoud: drupal_realpath() should describe when it should be used. --- includes/file.inc | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/includes/file.inc b/includes/file.inc index e9a567e9c..06657cfbe 100644 --- a/includes/file.inc +++ b/includes/file.inc @@ -2199,29 +2199,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 DrupalStreamWrapperInterface::realpath() * @see http://php.net/manual/function.realpath.php -- cgit v1.2.3