Issue #2343661 by larowlan, tim.plunkett | xjm: Rename l() to _l() and url()...

Issue #2343661 by larowlan, tim.plunkett | xjm: Rename l() to _l() and url() to _url(), and document replacements.

core/includes/batch.inc

@@ -157,7 +157,7 @@ function _batch_progress_page() {
   $batch['url_options']['query']['id'] = $batch['id'];
   $batch['url_options']['query']['op'] = $new_op;
 
-  $url = url($batch['url'], $batch['url_options']);
+  $url = _url($batch['url'], $batch['url_options']);
 
   $build = array(
     '#theme' => 'progress_bar',
@@ -486,7 +486,7 @@ function _batch_finished() {
     }
     elseif ($callback === NULL) {
       // Default to RedirectResponse objects when nothing specified.
-      $url = url($_batch['source_url'], array(
+      $url = _url($_batch['source_url'], array(
         'absolute' => TRUE,
         'query' => array('op' => 'finish', 'id' => $_batch['id']),
       ));

core/includes/common.inc

@@ -638,9 +638,24 @@ function _format_date_callback(array $matches = NULL, $new_langcode = NULL) {
  * When creating links in modules, consider whether l() could be a better
  * alternative than url().
  *
- * @see \Drupal\Core\Routing\UrlGeneratorInterface::generateFromPath().
+ * @see \Drupal\Core\Url::fromUri()
+ * @see \Drupal\Core\Url::fromRoute()
+ * @see \Drupal\Core\Url::toString()
+ *
+ * @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.0.
+ *   Use \Drupal\Core\Url::fromRoute() for internal paths served by Drupal
+ *   controllers or \Drupal\Core\Url::fromUri() for external paths or
+ *   non-controller or sub-domain URIs such as core/install.php. Note that
+ *   \Drupal\Core\Url::fromUri() expects a valid URI including the scheme. URIs
+ *   from the same sub-domain that are not handled by Drupal controllers should
+ *   be prepended with base://. For example:
+ * @code
+ * $installer_url = \Drupal\Core\Url::fromUri('base://core/install.php')->toString();
+ * $external_url = \Drupal\Core\Url::fromUri('http://example.com', ['query' => ['foo' => 'bar']])->toString();
+ * $internal_url = \Drupal\Core\Url::fromRoute('system.admin')->toString();
+ * @endcode
  */
-function url($path = NULL, array $options = array()) {
+function _url($path = NULL, array $options = array()) {
   return \Drupal::urlGenerator()->generateFromPath($path, $options);
 }
 
@@ -730,10 +745,27 @@ function drupal_http_header_attributes(array $attributes = array()) {
  * @return string
  *   An HTML string containing a link to the given path.
  *
- * @see url()
+ * @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
+ *   \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
+ *   core/install.php use \Drupal\Core\Url::fromUri(). Note that
+ *   \Drupal\Core\Url::fromUri() expects a valid URI including the scheme. URIs
+ *   from the same sub-domain that are not handled by Drupal controllers should
+ *   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);
+ * $external_url = \Drupal\Core\Url::fromUri('http://example.com', ['query' => ['foo' => 'bar']])->toString();
+ * $external_link = \Drupal::linkGenerator()->generate($external_url);
+ * $internal_url = \Drupal\Core\Url::fromRoute('system.admin')->toString();
+ * $internal_link = \Drupal::linkGenerator()->generate($internal_url);
+ * @endcode
  */
-function l($text, $path, array $options = array()) {
+function _l($text, $path, array $options = array()) {
   // Start building a structured representation of our link to be altered later.
   $variables = array(
     'text' => is_array($text) ? drupal_render($text) : $text,
@@ -788,7 +820,7 @@ function l($text, $path, array $options = array()) {
 
   // The result of url() is a plain-text URL. Because we are using it here
   // in an HTML argument context, we need to encode it properly.
-  $url = String::checkPlain(url($variables['path'], $variables['options']));
+  $url = String::checkPlain(_url($variables['path'], $variables['options']));
 
   // Sanitize the link text if necessary.
   $text = $variables['options']['html'] ? $variables['text'] : String::checkPlain($variables['text']);
@@ -1509,7 +1541,7 @@ function _drupal_add_js($data = NULL, $options = NULL) {
           $scriptPath = $GLOBALS['script_path'];
           $pathPrefix = '';
           $current_query = \Drupal::service('request_stack')->getCurrentRequest()->query->all();
-          url('', array('script' => &$scriptPath, 'prefix' => &$pathPrefix));
+          _url('', array('script' => &$scriptPath, 'prefix' => &$pathPrefix));
           $current_path = current_path();
           $current_path_is_admin = FALSE;
           // The function path_is_admin() is not available on update.php pages.

core/includes/form.inc

@@ -949,7 +949,7 @@ function batch_process($redirect = NULL, $url = 'batch', $redirect_callback = NU
     if ($batch['progressive']) {
       // Now that we have a batch id, we can generate the redirection link in
       // the generic error message.
-      $batch['error_message'] = t('Please continue to <a href="@error_url">the error page</a>', array('@error_url' => url($url, array('query' => array('id' => $batch['id'], 'op' => 'finished')))));
+      $batch['error_message'] = t('Please continue to <a href="@error_url">the error page</a>', array('@error_url' => _url($url, array('query' => array('id' => $batch['id'], 'op' => 'finished')))));
 
       // Clear the way for the redirection to the batch processing page, by
       // saving and unsetting the 'destination', if there is any.
@@ -977,7 +977,7 @@ function batch_process($redirect = NULL, $url = 'batch', $redirect_callback = NU
       }
       else {
         $options['absolute'] = TRUE;
-        return new RedirectResponse(url($batch['url'], $options));
+        return new RedirectResponse(_url($batch['url'], $options));
       }
     }
     else {

core/includes/pager.inc

@@ -219,7 +219,7 @@ function template_preprocess_pager(&$variables) {
     $options = array(
       'query' => pager_query_add_page($parameters, $element, 0),
     );
-    $items['first']['href'] = url($current_path, $options);
+    $items['first']['href'] = _url($current_path, $options);
     if (isset($tags[0])) {
       $items['first']['text'] = $tags[0];
     }
@@ -228,7 +228,7 @@ function template_preprocess_pager(&$variables) {
     $options = array(
       'query' => pager_query_add_page($parameters, $element, $pager_page_array[$element] - 1),
     );
-    $items['previous']['href'] = url($current_path, $options);
+    $items['previous']['href'] = _url($current_path, $options);
     if (isset($tags[1])) {
       $items['previous']['text'] = $tags[1];
     }
@@ -244,7 +244,7 @@ function template_preprocess_pager(&$variables) {
       $options = array(
         'query' => pager_query_add_page($parameters, $element, $i - 1),
       );
-      $items['pages'][$i]['href'] = url($current_path, $options);
+      $items['pages'][$i]['href'] = _url($current_path, $options);
       if ($i == $pager_current) {
         $variables['current'] = $i;
       }
@@ -261,7 +261,7 @@ function template_preprocess_pager(&$variables) {
     $options = array(
       'query' => pager_query_add_page($parameters, $element, $pager_page_array[$element] + 1),
     );
-    $items['next']['href'] = url($current_path, $options);
+    $items['next']['href'] = _url($current_path, $options);
     if (isset($tags[3])) {
       $items['next']['text'] = $tags[3];
     }
@@ -270,7 +270,7 @@ function template_preprocess_pager(&$variables) {
     $options = array(
       'query' => pager_query_add_page($parameters, $element, $pager_max - 1),
     );
-    $items['last']['href'] = url($current_path, $options);
+    $items['last']['href'] = _url($current_path, $options);
     if (isset($tags[4])) {
       $items['last']['text'] = $tags[4];
     }

core/includes/tablesort.inc

@@ -61,7 +61,7 @@ function tablesort_header(&$cell_content, array &$cell_attributes, array $header
       $ts['sort'] = 'asc';
       $image = '';
     }
-    $cell_content = l($cell_content . $image, current_path(), array(
+    $cell_content = _l($cell_content . $image, current_path(), array(
       'attributes' => array('title' => $title),
       'query' => array_merge($ts['query'], array(
         'sort' => $ts['sort'],

core/lib/Drupal/Component/Utility/UrlHelper.php

@@ -134,7 +134,7 @@ public static function filterQueryParameters(array $query, array $exclude = arra
    *   - fragment: The fragment component from $url, if it exists.
    *
    * @see \Drupal\Core\Utility\LinkGenerator
-   * @see url()
+   * @see _url()
    * @see http://tools.ietf.org/html/rfc3986
    *
    * @ingroup php_wrappers
@@ -288,7 +288,7 @@ public static function setAllowedProtocols(array $protocols = array()) {
    * to being output to an HTML attribute value. It is often called as part of
    * check_url() or Drupal\Component\Utility\Xss::filter(), but those functions
    * return an HTML-encoded string, so this function can be called independently
-   * when the output needs to be a plain-text string for passing to t(), l(),
+   * when the output needs to be a plain-text string for passing to t(), _l(),
    * Drupal\Core\Template\Attribute, or another function that will call
    * \Drupal\Component\Utility\String::checkPlain() separately.
    *

core/lib/Drupal/Core/Ajax/RedirectCommand.php

@@ -28,7 +28,7 @@ class RedirectCommand implements CommandInterface {
    *
    * @param string $url
    *   The URL that will be loaded into window.location. This should be a full
-   *   URL, one that has already been run through the url() function.
+   *   URL, one that has already been run through the _url() function.
    */
   public function __construct($url) {
     $this->url = $url;

core/lib/Drupal/Core/Asset/CssOptimizer.php

@@ -119,7 +119,7 @@ public function loadFile($file, $optimize = NULL, $reset_basepath = TRUE) {
    * Loads stylesheets recursively and returns contents with corrected paths.
    *
    * This function is used for recursive loading of stylesheets and
-   * returns the stylesheet content with all url() paths corrected.
+   * returns the stylesheet content with all _url() paths corrected.
    *
    * @param array $matches
    *   An array of matches by a preg_replace_callback() call that scans for
@@ -138,10 +138,10 @@ protected function loadNestedFile($matches) {
     // Determine the file's directory.
     $directory = dirname($filename);
     // If the file is in the current directory, make sure '.' doesn't appear in
-    // the url() path.
+    // the _url() path.
     $directory = $directory == '.' ? '' : $directory .'/';
 
-    // Alter all internal url() paths. Leave external paths alone. We don't need
+    // Alter all internal _url() paths. Leave external paths alone. We don't need
     // to normalize absolute paths here (i.e. remove folder/... segments)
     // because that will be done later.
     return preg_replace('/url\(\s*([\'"]?)(?![a-z]+:|\/+)([^\'")]+)([\'"]?)\s*\)/i', 'url(\1' . $directory . '\2\3)', $file);
@@ -215,7 +215,7 @@ protected function processCss($contents, $optimize = FALSE) {
    *
    * @param array $matches
    *   An array of matches by a preg_replace_callback() call that scans for
-   *   url() references in CSS files, except for external or absolute ones.
+   *   _url() references in CSS files, except for external or absolute ones.
    *
    * Note: the only reason this method is public is so color.module can call it;
    * it is not on the AssetOptimizerInterface, so future refactorings can make

core/lib/Drupal/Core/Entity/Entity.php

@@ -192,7 +192,7 @@ public function urlInfo($rel = 'canonical', array $options = []) {
       }
     }
 
-    // Pass the entity data to url() so that alter functions do not need to
+    // Pass the entity data to _url() so that alter functions do not need to
     // look up this entity again.
     $uri
       ->setOption('entity_type', $this->getEntityTypeId())

core/lib/Drupal/Core/Menu/LocalTaskManager.php

@@ -250,7 +250,7 @@ public function getLocalTasksForRoute($route_name) {
           foreach ($children[$parent] as $plugin_id => $task_info) {
             $plugin = $this->createInstance($plugin_id);
             $this->instances[$route_name][$level][$plugin_id] = $plugin;
-            // Normally, l() compares the href of every link with the current
+            // Normally, _l() compares the href of every link with the current
             // path and sets the active class accordingly. But the parents of
             // the current local task may be on a different route in which
             // case we have to set the class manually by flagging it active.

core/lib/Drupal/Core/Menu/MenuTreeStorage.php

@@ -1278,7 +1278,7 @@ protected static function schemaDefinition() {
           'not null' => FALSE,
         ),
         'options' => array(
-          'description' => 'A serialized array of options to be passed to the url() or l() function, such as a query string or HTML attributes.',
+          'description' => 'A serialized array of options to be passed to the _url() or _l() function, such as a query string or HTML attributes.',
           'type' => 'blob',
           'size' => 'big',
           'not null' => FALSE,

core/lib/Drupal/Core/Page/DefaultHtmlFragmentRenderer.php

@@ -110,7 +110,7 @@ public function preparePage(HtmlPage $page, &$page_array) {
     foreach (drupal_get_feeds() as $feed) {
       // Force the URL to be absolute, for consistency with other <link> tags
       // output by Drupal.
-      $link = new FeedLinkElement($feed['title'], url($feed['url'], array('absolute' => TRUE)));
+      $link = new FeedLinkElement($feed['title'], _url($feed['url'], array('absolute' => TRUE)));
       $page->addLinkElement($link);
     }
 

core/lib/Drupal/Core/Path/AliasWhitelist.php

@@ -88,7 +88,7 @@ protected function loadMenuPathRoots() {
    */
   public function get($offset) {
     $this->lazyLoadCache();
-    // url() may be called with paths that are not represented by menu router
+    // _url() may be called with paths that are not represented by menu router
     // items such as paths that will be rewritten by hook_url_outbound_alter().
     // Therefore internally TRUE is used to indicate whitelisted paths. FALSE is
     // used to indicate paths that have already been checked but are not

core/lib/Drupal/Core/Render/Element/Link.php

@@ -34,21 +34,21 @@ public function getInfo() {
    * Doing so during pre_render gives modules a chance to alter the link parts.
    *
    * @param array $element
-   *   A structured array whose keys form the arguments to l():
-   *   - #title: The link text to pass as argument to l().
+   *   A structured array whose keys form the arguments to _l():
+   *   - #title: The link text to pass as argument to _l().
    *   - One of the following
    *     - #route_name and (optionally) a #route_parameters array; The route
    *       name and route parameters which will be passed into the link
    *       generator.
-   *     - #href: The system path or URL to pass as argument to l().
-   *   - #options: (optional) An array of options to pass to l() or the link
+   *     - #href: The system path or URL to pass as argument to _l().
+   *   - #options: (optional) An array of options to pass to _l() or the link
    *     generator.
    *
    * @return array
    *   The passed-in element containing a rendered link in '#markup'.
    */
   public static function preRenderLink($element) {
-    // By default, link options to pass to l() are normally set in #options.
+    // By default, link options to pass to _l() are normally set in #options.
     $element += array('#options' => array());
     // However, within the scope of renderable elements, #attributes is a valid
     // way to specify attributes, too. Take them into account, but do not override
@@ -89,7 +89,7 @@ public static function preRenderLink($element) {
     }
     else {
       // @todo Convert to \Drupal::l(): https://www.drupal.org/node/2347045.
-      $element['#markup'] = l($element['#title'], $element['#href'], $element['#options']);
+      $element['#markup'] = _l($element['#title'], $element['#href'], $element['#options']);
     }
     return $element;
   }

core/lib/Drupal/Core/Render/Element/RenderElement.php

@@ -248,7 +248,7 @@ public static function preRenderAjaxForm($element) {
       }
 
       // Change path to URL.
-      $settings['url'] = isset($settings['path']) ? url($settings['path'], $settings['options']) : NULL;
+      $settings['url'] = isset($settings['path']) ? _url($settings['path'], $settings['options']) : NULL;
       unset($settings['path'], $settings['options']);
 
       // Add special data to $settings['submit'] so that when this element
@@ -286,7 +286,7 @@ public static function preRenderAjaxForm($element) {
       }
       // Change progress path to a full URL.
       if (isset($settings['progress']['path'])) {
-        $settings['progress']['url'] = url($settings['progress']['path']);
+        $settings['progress']['url'] = _url($settings['progress']['path']);
         unset($settings['progress']['path']);
       }
 

core/lib/Drupal/Core/Routing/UrlGenerator.php

@@ -238,7 +238,7 @@ public function generateFromPath($path = NULL, $options = array()) {
       // \Drupal\Component\Utility\UrlHelper::stripDangerousProtocols() if $path
       // contains a ':' before any / ? or #. Note: we could use
       // \Drupal\Component\Utility\UrlHelper::isExternal($path) here, but that
-      // would require another function call, and performance inside url() is
+      // would require another function call, and performance inside _url() is
       // critical.
       $colonpos = strpos($path, ':');
       $options['external'] = ($colonpos !== FALSE && !preg_match('![/?#]!', substr($path, 0, $colonpos)) && UrlHelper::stripDangerousProtocols($path) == $path);

core/lib/Drupal/Core/Routing/UrlGeneratorInterface.php

@@ -67,10 +67,10 @@ interface UrlGeneratorInterface extends VersatileGeneratorInterface {
    *   - 'script': Added to the URL between the base path and the path prefix.
    *     Defaults to empty string when clean URLs are in effect, and to
    *     'index.php/' when they are not.
-   *   - 'entity_type': The entity type of the object that called url(). Only
-   *     set if url() is invoked by Drupal\Core\Entity\Entity::uri().
+   *   - 'entity_type': The entity type of the object that called _url(). Only
+   *     set if _url() is invoked by Drupal\Core\Entity\Entity::uri().
    *   - 'entity': The entity object (such as a node) for which the URL is being
-   *     generated. Only set if url() is invoked by Drupal\Core\Entity\Entity::uri().
+   *     generated. Only set if _url() is invoked by Drupal\Core\Entity\Entity::uri().
    *
    * @return
    *   A string containing a URL to the given path.

core/lib/Drupal/Core/Template/TwigExtension.php

@@ -214,7 +214,7 @@ public function getLink($text, $url) {
     }
     else {
       // @todo Convert once https://www.drupal.org/node/2306901 is in
-      return l($text, $url);
+      return _l($text, $url);
     }
   }
 

core/modules/aggregator/src/Tests/FeedParserTest.php

@@ -80,7 +80,7 @@ function testHtmlEntitiesSample() {
    */
   function testRedirectFeed() {
     // Simulate a typo in the URL to force a curl exception.
-    $invalid_url = url('aggregator/redirect', array('absolute' => TRUE));
+    $invalid_url = _url('aggregator/redirect', array('absolute' => TRUE));
     $feed = entity_create('aggregator_feed', array('url' => $invalid_url, 'title' => $this->randomMachineName()));
     $feed->save();
     $feed->refreshItems();

core/modules/aggregator/src/Tests/Views/IntegrationTest.php

@@ -107,7 +107,7 @@ public function testAggregatorItemView() {
     // Ensure that the rendering of the linked title works as expected.
     foreach ($view->result as $row) {
       $iid = $view->field['iid']->getValue($row);
-      $expected_link = l($items[$iid]->getTitle(), $items[$iid]->getLink(), array('absolute' => TRUE));
+      $expected_link = _l($items[$iid]->getTitle(), $items[$iid]->getLink(), array('absolute' => TRUE));
       $this->assertEqual($view->field['title']->advancedRender($row), $expected_link, 'Ensure the right link is generated');
 
       $expected_author = aggregator_filter_xss($items[$iid]->getAuthor());