Link.php 4.05 KB
Newer Older
1 2 3 4
<?php

namespace Drupal\Core;

5
use Drupal\Core\Render\RenderableInterface;
6 7
use Drupal\Core\Routing\LinkGeneratorTrait;

8 9 10
/**
 * Defines an object that holds information about a link.
 */
11
class Link implements RenderableInterface {
12

13 14 15
  /**
   * @deprecated in Drupal 8.0.x-dev, will be removed before Drupal 9.0.0.
   */
16 17
  use LinkGeneratorTrait;

18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
  /**
   * The text of the link.
   *
   * @var string
   */
  protected $text;

  /**
   * The URL of the link.
   *
   * @var \Drupal\Core\Url
   */
  protected $url;

  /**
   * Constructs a new Link object.
   *
   * @param string $text
   *   The text of the link.
   * @param \Drupal\Core\Url $url
   *   The url object.
   */
  public function __construct($text, Url $url) {
    $this->text = $text;
    $this->url = $url;
  }

  /**
46
   * Creates a Link object from a given route name and parameters.
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
   *
   * @param string $text
   *   The text of the link.
   * @param string $route_name
   *   The name of the route
   * @param array $route_parameters
   *   (optional) 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, it defaults to the
   *     current language for the language type 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
69
   *     respectively. TRUE enforces HTTPS and FALSE enforces HTTP.
70 71 72 73 74 75 76
   *
   * @return static
   */
  public static function createFromRoute($text, $route_name, $route_parameters = array(), $options = array()) {
    return new static($text, new Url($route_name, $route_parameters, $options));
  }

77 78 79 80 81 82 83 84 85 86 87 88 89 90
  /**
   * Creates a Link object from a given Url object.
   *
   * @param string $text
   *   The text of the link.
   * @param \Drupal\Core\Url $url
   *   The Url to create the link for.
   *
   * @return static
   */
  public static function fromTextAndUrl($text, Url $url) {
    return new static($text, $url);
  }

91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
  /**
   * Returns the text of the link.
   *
   * @return string
   */
  public function getText() {
    return $this->text;
  }

  /**
   * Sets the new text of the link.
   *
   * @param string $text
   *   The new text.
   *
   * @return $this
   */
  public function setText($text) {
    $this->text = $text;
    return $this;
  }

  /**
   * Returns the URL of the link.
   *
   * @return \Drupal\Core\Url
   */
  public function getUrl() {
    return $this->url;
  }

  /**
   * Sets the URL of this link.
   *
   * @param Url $url
   *   The URL object to set
   *
   * @return $this
   */
  public function setUrl(Url $url) {
    $this->url = $url;
    return $this;
  }

135 136
  /**
   * Generates the HTML for this Link object.
137
   *
138 139 140 141 142
   * Do not use this method to render a link in an HTML context. In an HTML
   * context, self::toRenderable() should be used so that render cache
   * information is maintained. However, there might be use cases such as tests
   * and non-HTML contexts where calling this method directly makes sense.
   *
143
   * @return \Drupal\Core\GeneratedLink
144
   *   The link HTML markup.
145
   *
146
   * @see \Drupal\Core\Link::toRenderable()
147
   */
148 149
  public function toString() {
    return $this->getLinkGenerator()->generateFromLink($this);
150 151
  }

152 153 154 155 156 157 158 159 160 161 162
  /**
   * {@inheritdoc}
   */
  public function toRenderable() {
    return [
      '#type' => 'link',
      '#url' => $this->url,
      '#title' => $this->text,
    ];
  }

163
}