function l

Formats an internal or external URL link as an HTML anchor tag.

This function correctly handles aliased paths and adds an 'active' class attribute to links that point to the current page (for theming), 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:

t('Visit the <a href="@url">settings</a> page', array(
  '@url' => url('admin'),
));

This keeps the context of the link title ('settings' in the example) for translators.

Parameters

string|array $text: The link text for the anchor tag as a translated string or render array.

string $path: The internal path or external URL being linked to, such as "node/34" or "http://example.com/foo". After the url() function is called to construct the URL from $path and $options, the resulting URL is passed through check_plain() before it is inserted into the HTML anchor tag, to ensure well-formed HTML. See url() for more information and notes.

array $options: An associative array of additional options. Defaults to an empty array. It may contain the following elements.

• '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' (default FALSE): 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.
• '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). This element is also used by url().
• Additional $options elements used by the url() function.

Return value

string An HTML string containing a link to the given path.

See also

url()

theme_link()

File

drupal/core/includes/common.inc, line 1481

Common functions that many Drupal modules will need to reference.

Code

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,
    'path' => $path,
    'options' => $options,
  );

  // Merge in default options.
  $variables['options'] += array(
    'attributes' => array(),
    'query' => array(),
    'html' => FALSE,
    'language' => NULL,
  );

  // Because l() is called very often we statically cache values that require an
  // extra function call.
  static $drupal_static_fast;
  if (!isset($drupal_static_fast['active'])) {
    $drupal_static_fast['active'] =& drupal_static(__FUNCTION__);
  }
  $active =& $drupal_static_fast['active'];
  if (!isset($active)) {
    $active = array(
      'path' => current_path(),
      'front_page' => drupal_is_front_page(),
      'language' => language(Language::TYPE_URL)->langcode,
      'query' => Drupal::service('request')->query
        ->all(),
    );
  }

  // Determine whether this link is "active', meaning that it links to the
  // current page. It is important that we stop checking "active" conditions if
  // we know the link is not active. This helps ensure that l() remains fast.
  // An active link's path is equal to the current path.
  $variables['url_is_active'] = ($path == $active['path'] || $path == '<front>' && $active['front_page']) && (empty($variables['options']['language']) || $variables['options']['language']->langcode == $active['language']) && $variables['options']['query'] == $active['query'];

  // Add the "active" class if appropriate.
  if ($variables['url_is_active']) {
    $variables['options']['attributes']['class'][] = 'active';
  }

  // Remove all HTML and PHP tags from a tooltip, calling expensive strip_tags()
  // only when a quick strpos() gives suspicion tags are present.
  if (isset($variables['options']['attributes']['title']) && strpos($variables['options']['attributes']['title'], '<') !== FALSE) {
    $variables['options']['attributes']['title'] = strip_tags($variables['options']['attributes']['title']);
  }

  // Allow other modules to modify the structure of the link.
  Drupal::moduleHandler()
    ->alter('link', $variables);

  // Move attributes out of options. url() doesn't need them.
  $attributes = new Attribute($variables['options']['attributes']);
  unset($variables['options']['attributes']);

  // 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 = check_plain(url($variables['path'], $variables['options']));

  // Sanitize the link text if necessary.
  $text = $variables['options']['html'] ? $variables['text'] : check_plain($variables['text']);
  return '<a href="' . $url . '"' . $attributes . '>' . $text . '</a>';
}