<?php

/**
 * @file
 * Contains \Drupal\service_container\LinkGenerator.
 */

namespace Drupal\service_container;

use Drupal\service_container\Legacy\Drupal7;

/**
 * Generates a link out from a given path, title and options.
 *
 * Wraps l().
 *
 * @codeCoverageIgnore
 */
class LinkGenerator {

  /**
   * The Drupal7 service.
   *
   * @var \Drupal\service_container\Legacy\Drupal7
   */
  protected $drupal7;

  /**
   * Constructs a new LinkGenerator instance.
   *
   * @param \Drupal\service_container\Legacy\Drupal7 $drupal7
   *   The Drupal7 service.
   */
  public function __construct(Drupal7 $drupal7) {
    $this->drupal7 = $drupal7;
  }

  /**
   * 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:
   * @code
   * t('Visit the <a href="@url">settings</a> page', array('@url' => url('admin')));
   * @endcode
   * This keeps the context of the link title ('settings' in the example) for
   * translators.
   *
   * @param string $text
   *   The translated link text for the anchor tag.
   * @param 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.
   * @param 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 in a call to drupal_attributes($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 string
   *   An HTML string containing a link to the given path.
   *
   * @see url()
   */
  public function l($text, $path, array $options = array()) {
    return $this->drupal7->l($text, $path, $options);
  }

}
