Change record status: 
Project: 
Introduced in branch: 
8.x
Description: 

Introduces new interface:
\Drupal\Core\Utility\LinkGeneratorInterface

Default implementation:
\Drupal\Core\Utility\LinkGenerator

And new service in the DIC:
$container->get('link_generator');

And a short-cut l() method on the Drupal class and a similar one on the ControllerBase class:
$link = Drupal::l((t('Create new account'), 'user_register');

Note that calling Drupal::l() is the same as calling Drupal::linkGenerator()->generate()

Enables render elements of '#type' => 'link' to render a link based on a #route_name and #route_parameters.

In Drupal 8, we should as much as possible remove reliance on Drupal system paths and instead work with routes and their parameters. To that end, a link generator has been added that works like l() but gets the route name and route parameters passed in instead of a system path.

D7

<?php
      $items
['create_account'] = l(t('Create new account'), 'user/register', array(
       
'attributes' => array(
         
'title' => t('Create a new user account.'),
         
'class' => array('create-account-link'),
        ),
      ));
?>

D8

<?php
      $items
['create_account'] = Drupal::l(t('Create new account'), 'user_register', array(), array(
       
'attributes' => array(
         
'title' => t('Create a new user account.'),
         
'class' => array('create-account-link'),
        ),
      ));
?>

Because the path for a given route may be changed, generating from the route name and parameters is preferred and reduces code maintenance.

In addition, check access to a route is faster than checking access using a system path, so developers should immediately use the combination of route-based access and link generation where appropriate.

This change enable render elements of '#type' => 'link' to be converted:

Drupal 7;

<?php
  $items
['user'] = array(
   
'#type' => 'link',
   
'#title' => $user->getUsername(),
   
'#href' => 'user',
   
'#options' => array(
     
'attributes' => array(
       
'title' => t('My account'),
       
'class' => array('toolbar-icon', 'toolbar-icon-user'),
      ),
    ),
 );
?>

Drupal 8:

<?php
  $items
['user'] = array(
   
'#type' => 'link',
   
'#title' => $user->getUsername(),
   
'#route_name' => 'user_page'
    '#options'
=> array(
     
'attributes' => array(
       
'title' => t('My account'),
       
'class' => array('toolbar-icon', 'toolbar-icon-user'),
      ),
    ),
 );
?>

This change also introduces a helper method on \Drupal\Core\Controller\ControllerBase :

public function l($text, $route_name, array $parameters = array(), array $options = array())

If your page controller extends that class, you can use $this->l() do generate a link to a route.

Impacts: 
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done