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

Entities now define their own URI templates using standard forms. They do so using the Entity annotation.

At minimum, all entities should define their "canonical" link. This is the URI template for the path that will uniquely identify a given entity. For example:

<?php
/**
* Defines the node entity class.
*
* @EntityType(
*   id = "node",
*   // ... Various other properties
*   links = {
*     "canonical" = "/node/{node}",
*     "edit-form" = "/node/{node}/edit",
*     "version-history" = "/node/{node}/revisions"
*   }
* )
*/
class Node extends Entity implements NodeInterface { }
?>

That means that any node can be accessed at the path /node/{id of the node} as its canonical, unique URI.

Entities may define other links as well. At present only IANA-defined link relationships are allowed. What links are appropriate depends on the entity type. For example, any entity that has a user-accessible edit form should define the "edit-form" relationship, while any entity that supports revisioning should define the "version-history" relationship.

To get a link to an entity, always use the uri() method of the entity object. By default uri() will return the canonical link, formatted with the appropriate placeholder, in a form that the generator understands. That is:

<?php
// The node with ID 12.
$node;
$url_info = $node->uri();
$url = $generator->generateFromPath($url_info['path'], $urlinfo_['options']);
// $url will be "/node/12"
?>

To access a different relationship, simply specify that as a parameter to uri(). Eg:

<?php
$node
->uri('version-history');
?>

A complete list of defined relationships can be retrieved from the uriRelationships() method. That allows for code such as:

<?php
foreach ($node->uriRelationships as $rel) {
 
$url_info = $node->uri($rel);
 
$links[$rel] = $generator->generateFromPath($url_info['path'], $url_info['options']);
}
?>

Other systems may leverage link relationships in other ways automatically. Therefore, defining reasonable relationships is strongly encouraged for all entities. Support for non-standard link relationships may be added in the future.

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