diff --git a/core/lib/Drupal.php b/core/lib/Drupal.php index b355847..363cf12 100644 --- a/core/lib/Drupal.php +++ b/core/lib/Drupal.php @@ -460,47 +460,18 @@ public static function urlGenerator() { } /** - * Generates a URL or path for a specific route based on the given parameters. - * - * Parameters that reference placeholders in the route pattern will be - * substituted for them in the pattern. Extra params are added as query - * strings to the URL. - * - * @param string $route_name - * The name of the route - * @param array $route_parameters - * An associative array of parameter names and values. - * @param array $options - * (optional) An associative array of additional options, with the following - * elements: - * - 'query': An array of query key/value-pairs (without any URL-encoding) - * to append to the URL. Merged with the parameters array. - * - 'fragment': A fragment identifier (named anchor) to append to the URL. - * Do not include the leading '#' character. - * - 'absolute': Defaults to FALSE. Whether to force the output to be an - * absolute link (beginning with http:). Useful for links that will be - * displayed outside the site, such as in an RSS feed. - * - 'language': An optional language object used to look up the alias - * for the URL. If $options['language'] is omitted, the language will be - * obtained from - * \Drupal::languageManager()->getCurrentLanguage(LanguageInterface::TYPE_URL). - * - 'https': Whether this URL should point to a secure location. If not - * defined, the current scheme is used, so the user stays on HTTP or HTTPS - * respectively. if mixed mode sessions are permitted, TRUE enforces HTTPS - * and FALSE enforces HTTP. - * - * @return string - * The generated URL for the given route. - * - * @throws \Symfony\Component\Routing\Exception\RouteNotFoundException - * Thrown when the named route doesn't exist. - * @throws \Symfony\Component\Routing\Exception\MissingMandatoryParametersException - * Thrown when some parameters are missing that are mandatory for the route. - * @throws \Symfony\Component\Routing\Exception\InvalidParameterException - * Thrown when a parameter value for a placeholder is not correct because it - * does not match the requirement. - * - * @see \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute() + * Generates a URL string for a specific route based on the given parameters. + * + * This method is a convenience wrapper for generating URL strings for URLs + * that have Drupal routes (that is, most pages generated by Drupal) using + * the \Drupal\Core\Url object. See \Drupal\Core\Url::fromRoute() for + * detailed documentation. For non-routed local URIs relative to + * the base path (like robots.txt) use Url::fromUri()->toString() with the + * base:// scheme. + * + * @see \Drupal\Core\Url + * @see \Drupal\Core\Url::fromRoute() + * @see \Drupal\Core\Url::fromUri() */ public static function url($route_name, $route_parameters = array(), $options = array()) { return static::$container->get('url_generator')->generateFromRoute($route_name, $route_parameters, $options); @@ -516,58 +487,14 @@ public static function linkGenerator() { } /** - * Renders a link to a route given a route name and its parameters. - * - * This function correctly handles aliased paths and sanitizing text, so all - * internal links output by modules should be generated by this function if - * possible. - * - * However, for links enclosed in translatable text you should use t() and - * embed the HTML anchor tag directly in the translated string. For example: - * @code - * t('Visit the content types page', array('@url' => \Drupal::url('node.overview_types'))); - * @endcode - * This keeps the context of the link title ('settings' in the example) for - * translators. - * - * @param string|array $text - * The link text for the anchor tag as a translated string or render array. - * @param \Drupal\Core\Url $url - * The URL object used for the link. Amongst its options, the following may - * be set to affect the generated link: - * - 'query': An array of query key/value-pairs (without any URL-encoding) to - * append to the URL. - * - absolute: Whether to force the output to be an absolute link (beginning - * with http:). Useful for links that will be displayed outside the site, - * such as in an RSS feed. Defaults to FALSE. - * - attributes: An associative array of HTML attributes to apply to the - * anchor tag. If element 'class' is included, it must be an array; 'title' - * must be a string; other elements are more flexible, as they just need - * to work as an argument for the constructor of the class - * Drupal\Core\Template\Attribute($options['attributes']). - * - html: Whether $text is HTML or just plain-text. For - * example, to make an image tag into a link, this must be set to TRUE, or - * you will see the escaped HTML image tag. $text is not sanitized if - * 'html' is TRUE. The calling function must ensure that $text is already - * safe. Defaults to FALSE. - * - language: An optional language object. If the path being linked to is - * internal to the site, $options['language'] is used to determine whether - * the link is "active", or pointing to the current page (the language as - * well as the path must match). - * - * @return string - * An HTML string containing a link to the given route and parameters. - * - * @throws \Symfony\Component\Routing\Exception\RouteNotFoundException - * Thrown when the named route doesn't exist. - * @throws \Symfony\Component\Routing\Exception\MissingMandatoryParametersException - * Thrown when some parameters are missing that are mandatory for the route. - * @throws \Symfony\Component\Routing\Exception\InvalidParameterException - * Thrown when a parameter value for a placeholder is not correct because it - * does not match the requirement. - * - * @see \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute() + * Renders a link with a given link text and Url object. + * + * This method is a convenience wrapper for the link generator service's + * generate() method. For detailed documentation, see + * \Drupal\Core\Routing\LinkGeneratorInterface::generate(). + * * @see \Drupal\Core\Utility\LinkGeneratorInterface::generate() + * @see \Drupal\Core\Url */ public static function l($text, Url $url) { return static::$container->get('link_generator')->generate($text, $url); diff --git a/core/lib/Drupal/Core/Routing/UrlGeneratorInterface.php b/core/lib/Drupal/Core/Routing/UrlGeneratorInterface.php index 06e600d..e80e193 100644 --- a/core/lib/Drupal/Core/Routing/UrlGeneratorInterface.php +++ b/core/lib/Drupal/Core/Routing/UrlGeneratorInterface.php @@ -77,8 +77,15 @@ * * @throws \Drupal\Core\Routing\GeneratorNotInitializedException. * - * @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0. - * System paths should not be used - use route names and parameters. + * @deprecated in Drupal 8.0.x-dev and will be removed before Drupal 8.0.0. + * To generate URLs for Drupal routes (that is, most pages generated by + * Drupal), see UrlGeneratorInterface::generateFromRoute() instead. For + * non-routed local URIs relative to the base path (like robots.txt) see + * \Drupal\Core\Utility\UnroutedUrlAssembler. + * + * @see static::generateFromRoute() + * @see \Drupal\Core\Utility\UnroutedUrlAssembler + * @see \Drupal\Core\Url */ public function generateFromPath($path = NULL, $options = array()); diff --git a/core/lib/Drupal/Core/Url.php b/core/lib/Drupal/Core/Url.php index a6f0220..0c28b7b 100644 --- a/core/lib/Drupal/Core/Url.php +++ b/core/lib/Drupal/Core/Url.php @@ -88,10 +88,6 @@ class Url { /** * Constructs a new Url object. * - * In most cases, use Url::fromRoute() or Url::fromUri() rather than - * constructing Url objects directly in order to avoid ambiguity and make your - * code more self-documenting. - * * @param string $route_name * The name of the route * @param array $route_parameters