Tipos de Entidad

• Drupal 7: las entidades eran objetos generales stdClass.
• Drupal 8: las entidades ahora son objetos con tipificación específica, donde cada tipo de entidad define una clase que se usará para las instancias de esa entidad.

Requisitos
Las clases de Entidad deben estar ubicadas en el subespacio de nombres Entity del módulo que provee el tipo de entidad, por ejemplo \Drupal\[nombre_del_módulo]\Entity. Esto significa que los archivos PHP de las clases Entity se encuentran en el directorio src/Entity dentro del módulo.

El docblock para la clase debe contener la anotación EntityType, que define los metadatos para la entidad de ese tipo. Estos incluyen cosas como la etiqueta del tipo de entidad, controladores, tablas, etc. Para una lista documentada de todas las propiedades de metadatos disponibles, consulte la clase \Drupal\Core\Entity\Annotation\EntityType.

Nombrado

Los nombres de los tipos de objeto deben tener un prefijo con el nombre del módulo, si el tipo de objeto y el nombre del módulo no coinciden. No es necesario prefijar el nombre de la clase del tipo de entidad, ya que está en el espacio de nombres del módulo que lo define, siempre que este nombre sea suficientemente descriptivo por sí mismo. Por ejemplo, el tipo de entidad para términos de taxonomía se llama taxonomy_term, y el nombre de la clase es Drupal\taxonomy\Entity\Term.

Interfaces

Drupal 8 recomienda usar hints y métodos con interfaces en lugar de clases concretas. Por ejemplo, el almacenamiento genérico de entidades intercepta el hint de tipo con EntityInterface, como en hook_entity_insert (EntityInterface $entity), mientras que el almacenamiento específico para nodos intercepta el hint de tipo con NodeInterface, como en hook_node_insert (NodeInterface $node).

Los campos/propiedades de una Entidad suelen ser muy cortos, orientados a almacenamiento y no muy descriptivos. Además, las entidades de contenido generalmente no usan propiedades específicas para sus campos (incluyendo campos base como el título del nodo).

Por lo tanto, el enfoque recomendado es proporcionar una interfaz con métodos documentados. Algunas reglas a seguir:

• Los métodos usualmente tienen prefijos get/set/is o similares: getAlgo(), setAlgo($valor), isAlgo().
• Solo agregue métodos para cosas que otro código necesite modificar. Por ejemplo, la fecha de última modificación de nodos ($node->updated) no debe modificarse, por lo que hay un método $node->getChangedTime(), pero no $node->setChangedTime().
• Use nombres de métodos autoexplicativos; por ejemplo, el método para acceder al estado $node->status es $node->isPublished().

Claridad

Para saber qué tipos de entidad provee un módulo, revise las clases en el subespacio de nombres Entity de ese módulo que tengan la anotación @EntityType, que también contiene el nombre en la clave id de la anotación.

Para encontrar dónde está definido un tipo de entidad dado, lo primero que debe buscar es el prefijo del tipo de entidad. Si el módulo no sigue esta convención de nombres, puede buscar por id = "$type". Si se conoce la clase o interfaz en lugar del tipo de entidad, el espacio de nombres indica de dónde proviene.

Ejemplo

core/modules/node/src/Entity/Node.php:

namespace Drupal\node\Entity;

use Drupal\Core\Entity\ContentEntityBase;
use Drupal\Core\Entity\EntityChangedTrait;
use Drupal\Core\Entity\EntityStorageInterface;
use Drupal\Core\Entity\EntityTypeInterface;
use Drupal\Core\Field\BaseFieldDefinition;
use Drupal\Core\Session\AccountInterface;
use Drupal\node\NodeInterface;
use Drupal\user\UserInterface;

/**
 * Defines the node entity class.
 *
 * @ContentEntityType(
 *   id = "node",
 *   label = @Translation("Content"),
 *   bundle_label = @Translation("Content type"),
 *   handlers = {
 *     "storage" = "Drupal\node\NodeStorage",
 *     "storage_schema" = "Drupal\node\NodeStorageSchema",
 *     "view_builder" = "Drupal\node\NodeViewBuilder",
 *     "access" = "Drupal\node\NodeAccessControlHandler",
 *     "views_data" = "Drupal\node\NodeViewsData",
 *     "form" = {
 *       "default" = "Drupal\node\NodeForm",
 *       "delete" = "Drupal\node\Form\NodeDeleteForm",
 *       "edit" = "Drupal\node\NodeForm"
 *     },
 *     "route_provider" = {
 *       "html" = "Drupal\node\Entity\NodeRouteProvider",
 *     },
 *     "list_builder" = "Drupal\node\NodeListBuilder",
 *     "translation" = "Drupal\node\NodeTranslationHandler"
 *   },
 *   base_table = "node",
 *   data_table = "node_field_data",
 *   revision_table = "node_revision",
 *   revision_data_table = "node_field_revision",
 *   translatable = TRUE,
 *   list_cache_contexts = { "user.node_grants:view" },
 *   entity_keys = {
 *     "id" = "nid",
 *     "revision" = "vid",
 *     "bundle" = "type",
 *     "label" = "title",
 *     "langcode" = "langcode",
 *     "uuid" = "uuid",
 *     "status" = "status",
 *     "uid" = "uid",
 *   },
 *   bundle_entity_type = "node_type",
 *   field_ui_base_route = "entity.node_type.edit_form",
 *   common_reference_target = TRUE,
 *   permission_granularity = "bundle",
 *   links = {
 *     "canonical" = "/node/{node}",
 *     "delete-form" = "/node/{node}/delete",
 *     "edit-form" = "/node/{node}/edit",
 *     "version-history" = "/node/{node}/revisions",
 *     "revision" = "/node/{node}/revisions/{node_revision}/view",
 *   }
 * )
 */
class Node extends ContentEntityBase implements NodeInterface {
  // ...
}

Para obtener una visión completa de las entidades en Drupal 8, podemos considerar el siguiente diagrama. Este representa las clases de entidad. Para verlo, ábralo en una nueva pestaña: