From f6496571829596301d135a99111bb25817e8d594 Mon Sep 17 00:00:00 2001 From: Damian Mooyman Date: Tue, 3 Sep 2019 19:34:16 +1200 Subject: [PATCH] Clarify Director::absoluteURL behaviour Fixes #9111 --- src/Control/Director.php | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/src/Control/Director.php b/src/Control/Director.php index 525fc0eb7..c0cecc405 100644 --- a/src/Control/Director.php +++ b/src/Control/Director.php @@ -424,16 +424,18 @@ class Director implements TemplateGlobalProvider } /** - * Turns the given URL into an absolute URL. By default non-site root relative urls will be - * evaluated relative to the current base_url. + * Converts the given path or url into an absolute url. This method follows the below rules: + * - Absolute urls (e.g. http://localhost) are not modified + * - Relative urls (e.g. //localhost) have current protocol added (http://localhost) + * - Absolute paths (e.g. /base/about-us) are resolved by adding the current protocol and host (http://localhost/base/about-us) + * - Relative paths (e.g. about-us/staff) must be resolved using one of three methods, disambiguated via the $relativeParent argument: + * - BASE - Append this path to the base url (i.e. behaves as though `` tag is provided in a html document). This is the default. + * - REQUEST - Resolve this path to the current url (i.e. behaves as though no tag is provided in a html document) + * - ROOT - Treat this as though it was an absolute path, and append it to the protocol and hostname. * - * @param string $url URL To transform to absolute. - * @param string $relativeParent Method to use for evaluating relative urls. - * Either one of BASE (baseurl), ROOT (site root), or REQUEST (requested page). - * Defaults to BASE, which is the same behaviour as template url resolution. - * Ignored if the url is absolute or site root. - * - * @return string + * @param string $url The url or path to resolve to absolute url. + * @param string $relativeParent Disambiguation method to use for evaluating relative paths + * @return string The absolute url */ public static function absoluteURL($url, $relativeParent = self::BASE) {