Change record status: 
Project: 
Introduced in branch: 
11.3,x
Introduced in version: 
11.3.0
Description: 

The web is full of links. When creating content in Drupal, content creators often want to link to other entities in Drupal. Inside of Drupal's assistive text editor (CKEditor 4 previously, now 5) this has historically been a laborious manual process, with brittle results (risk of typos, copy/paste errors, link rot, and more).

To facilitate creating content that consistently links to entities of all types (Node, but also File and Media, and even MenuLinkContent), a new optional entity handler is introduced: the link_target handler:

 *     "link_target" = {
 *       "view" = "\Drupal\menu_link_content\Entity\MenuLinkContentLinkTarget",
 *     },

(for an entity type that is not downloadable)

 *   handlers = {
 *     "storage" = "Drupal\media\MediaStorage",
…
 *     "link_target" = {
 *       "view" = "\Drupal\media\Entity\MediaLinkTargetStandaloneWhenAvailable",
 *       "download" = "\Drupal\media\Entity\MediaLinkTarget",
 *     },

(for an entity type that is downloadable)

Such handlers must implement \Drupal\Core\Entity\EntityLinkTargetInterface, which has a single method:

  /**
   * Gets the generated URL object for a linked entity's link target.
   *
   * @param \Drupal\Core\Entity\EntityInterface $entity
   *   A linked entity.
   *
   * @return \Drupal\Core\GeneratedUrl
   *   The generated URL plus cacheability metadata.
   */
  public function getLinkTarget(EntityInterface $entity): GeneratedUrl;

This allows links to a File entity (or to a Media entity using the File source plugin) to automatically be resolved to the underlying file, links to Media using the OEmbed source plugin to automatically be resolved to the originally embedded URL, and so on.

For example, FileLinkTarget:

  public function getLinkTarget(EntityInterface $entity): GeneratedUrl {
    assert($entity instanceof FileInterface);
    $url = $entity->createFileUrl(TRUE);
    // The $url is a string, which provides no cacheability metadata.
    assert(is_string($url));
    return (new GeneratedUrl())
      ->setGeneratedUrl($url)
      // No path & route processing means permanent cacheability.
      ->setCacheMaxAge(Cache::PERMANENT);
  }

or MenuLinkContentLinkTarget:

  public function getLinkTarget(EntityInterface $entity): GeneratedUrl {
    assert($entity instanceof MenuLinkContentInterface);
    return $entity->getUrlObject()->toString(TRUE);
  }

See the Change Record for the new Entity Links filter plugin for where this is used.

Impacts: 
Site builders, administrators, editors
Module developers