diff -u b/core/lib/Drupal/Core/Url.php b/core/lib/Drupal/Core/Url.php --- b/core/lib/Drupal/Core/Url.php +++ b/core/lib/Drupal/Core/Url.php @@ -41,13 +41,46 @@ use DependencySerializationTrait; /** - * Scheme for base-relative, unrouted URIs. + * Scheme for URIs to resolve as references relative to Drupal's installation. * - * This scheme should only be used for unrouted URIs, like base:robots.txt - * or base:core/update.php. To create such a base-relative URI from a path, - * use Url::fromBaseRelativePath(). To create a host-relative URI instead - * (for example, for http://example.com/index.html when Drupal is installed - * in http://example.com/drupal/), use Url::fromHostRelativePath(). + * https://tools.ietf.org/html/rfc3986#section-5.2 specifies the standard for + * resolving URI references relative to a base URI. + * + * This scheme is to allow such references to be internally represented and + * managed in Drupal as full URIs themselves, and resolved to the + * corresponding URLs at runtime. When performing this resolution, the base + * URI is Drupal's installation URL. + * + * For example, if Drupal is installed in http://example.com/drupal/, then: + * - Url::fromUri(Url::SCHEME_BASE . ':README.txt')->toString() would return + * '/drupal/README.txt'. + * - Url::fromUri(Url::SCHEME_BASE . ':/index.html')->toString() would return + * '/index.html'. + * + * This is the identical resolution as what a browser would perform if Drupal + * output a @link http://www.w3.org/wiki/HTML/Elements/base @endlink + * element and the above URLs were written within links as: + * - (browser resolves as '/drupal/README.txt') + * - (browser resolves as '/index.html') + * + * The examples above can also be generated from the wrapper methods + * fromBaseRelativePath() and fromHostRelativePath(), as follows: + * - Url::fromBaseRelativePath('README.txt') is equivalent to + * Url::fromUri(Url::SCHEME_BASE . ':README.txt'). + * - Url::fromHostRelativePath('index.html') is equivalent to + * Url::fromUri(Url::SCHEME_BASE . ':/index.html'). + * + * Note that this scheme is intended for linking to non-Drupal-routed pages. + * For example, to static files or to pages served by other software on the + * website. As such, the resolution of this scheme does not apply any path + * processors, such as language prefixing and alias lookup, or access + * checking (->access() returns TRUE for URIs in this scheme). Therefore, + * using this scheme for Drupal-routed pages is incompatible with + * multilingual sites, with search engine optimization, and with hiding links + * to pages that the user can't access, unless you take care of all that + * yourself. For these reasons, it is recommended to not use this scheme for + * pages served by Drupal. The other schemes and their wrapper methods + * can be used for that. * * @see static::fromBaseRelativePath() * @see static::fromHostRelativePath() @@ -253,11 +286,12 @@ * * This method should only be used for paths within the base directory of the * site installation that do not have a Drupal route. These may be files like - * robots.txt, core scripts like core/update.php, or they may be another + * robots.txt, core scripts like core/install.php, or they may be another * application placed within the Drupal site installation. * - * Do not use this method for URLs that do have a Drupal route (such as pages - * generated by Drupal) because this will circumvent the routing system. + * Do not use this method for URLs that have a Drupal route (that is, most + * pages generated by Drupal). See the documentation of static::SCHEME_BASE + * for details. * * @param string $path * The base-relative path, for example 'robots.txt'. @@ -265,9 +299,10 @@ * (optional) An array of options. See static::fromUri() for details. * * @return \Drupal\Core\Url - * A new Url object for an unrouted, base-relative URL not internal to - * Drupal, but within the site installation directory. + * A new Url object for an unrouted URL within the site installation + * directory. * + * @see static::SCHEME_BASE * @see static::fromHostRelativePath() * @see static::fromUri() * @see static::fromRoute() @@ -282,8 +317,9 @@ * This method should only be used for paths within the same host as the * site installation. * - * Do not use this method for URLs that do have a Drupal route (that is, most - * pages generated by Drupal) because this will circumvent the routing system. + * Do not use this method for URLs that have a Drupal route (that is, most + * pages generated by Drupal). See the documentation of static::SCHEME_BASE + * for details. * * @param string $path * The host-relative path. For example, if Drupal is installed in the @@ -296,6 +332,7 @@ * A new Url object for an unrouted, host-relative URL not internal to * Drupal, but relative to the site host. * + * @see static::SCHEME_BASE * @see static::fromBaseRelativePath() * @see static::fromUri() * @see static::fromRoute()