diff --git a/core/includes/common.inc b/core/includes/common.inc index 81c61b3a98fad972a0307e582213ea395ce0dee1..1581de6f96a0a4feb0f61513cb56bfb3a3fdd09a 100644 --- a/core/includes/common.inc +++ b/core/includes/common.inc @@ -748,7 +748,7 @@ function drupal_http_header_attributes(array $attributes = array()) { * @see _url() * @see system_page_build() * @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.0. - * Use \Drupal::linkGenerator()->generate($url) where $url is an instance of + * Use \Drupal::l($text, $url) where $url is an instance of * \Drupal\Core\Url. To build a \Drupal\Core\Url object for internal paths * served by Drupal controllers use \Drupal\Core\Url::fromRoute(). For * external paths or non-controller or sub-domain URIs such as @@ -758,11 +758,11 @@ function drupal_http_header_attributes(array $attributes = array()) { * be prepended with base://. For example: * @code * $installer_url = \Drupal\Core\Url::fromUri('base://core/install.php')->toString(); - * $installer_link = \Drupal::linkGenerator()->generate($installer_url); + * $installer_link = \Drupal::l($text, $installer_url); * $external_url = \Drupal\Core\Url::fromUri('http://example.com', ['query' => ['foo' => 'bar']])->toString(); - * $external_link = \Drupal::linkGenerator()->generate($external_url); + * $external_link = \Drupal::l($text, $external_url); * $internal_url = \Drupal\Core\Url::fromRoute('system.admin')->toString(); - * $internal_link = \Drupal::linkGenerator()->generate($internal_url); + * $internal_link = \Drupal::l($text, $internal_url); * @endcode */ function _l($text, $path, array $options = array()) { diff --git a/core/lib/Drupal.php b/core/lib/Drupal.php index b355847d32f2d7b32644c7381fa7971304e3f5af..363cf129cdb91d5010fa16b2aea04a8f5ed7d383 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 06e600de7e171ce3a15edb25421ebfaf45ffe152..e80e193e4bc87705cbea9b91fa2c3ba369360c12 100644 --- a/core/lib/Drupal/Core/Routing/UrlGeneratorInterface.php +++ b/core/lib/Drupal/Core/Routing/UrlGeneratorInterface.php @@ -77,8 +77,15 @@ interface UrlGeneratorInterface extends VersatileGeneratorInterface { * * @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());