Introducción a la Entity API en Drupal 8

Sistema de Entidades en Drupal 8

Las entidades son clases tipadas con métodos

Antecedentes

El sistema de entidades fue introducido al final del ciclo de desarrollo de Drupal 7 con estándares básicos para cargar entidades. El módulo entity.module amplió aún más la API añadiendo soporte para guardar y eliminar entidades y muchas otras mejoras.

La mayoría de estas mejoras ahora están incluidas en Drupal 8. La validación de entidades ahora se realiza en su propia API (que puede validar una entidad guardada vía REST, no solo desde un formulario, por ejemplo).

Dos variantes

Los tipos de entidad en el núcleo tienen dos variantes.

Objeto de configuración
Usa el Sistema de Configuración. Soporta traducciones y puede proveer configuraciones predeterminadas para instalaciones. Los objetos de configuración se almacenan en una tabla común de la base de datos de configuración en forma de cadenas.

Entidad de contenido
Consiste en campos base y configurables, puede tener revisiones y soportar traducciones. Los objetos de contenido se almacenan en tablas personalizadas en la base de datos en forma de filas. El nombre de la tabla coincide con el identificador del objeto y las columnas se definen mediante el método baseFieldDefinitions del objeto.

Bundles (Paquetes)

Los bundles son variantes de un tipo de entidad. Por ejemplo, para el tipo de entidad nodo, los bundles son diferentes tipos de nodos, como "Artículo" y "Página".

Por lo general, un bundle es representado por un objeto de configuración, aunque existen otros modelos en módulos contribuidos. Por ejemplo, para nodos, el tipo de nodo "article" es un objeto de configuración. La configuración almacena las diferencias entre tipos de entidades de contenido, como ajustes y campos. Cuando creas un nuevo tipo de entidad con bundles, crearás tanto la entidad de contenido que manejará los detalles y operaciones del contenido, como el objeto de configuración que manejará las diferencias entre tipos de entidad de contenido.

Anotaciones

Al crear un nuevo tipo de entidad, deberás usar el sistema de anotaciones incorporado en el núcleo. Las anotaciones se ven como comentarios docblock sobre la clase, pero son analizadas y almacenadas en caché por Drupal. En muchos sentidos, las anotaciones reemplazan algunos de los estilos más antiguos usados en Drupal 7.

Analizador de anotaciones

Las anotaciones son leídas y procesadas en tiempo de ejecución por el motor de anotaciones. Drupal 8 utiliza el analizador de anotaciones de Doctrine, que lo convierte en un objeto usable por PHP.

Sintaxis. La sintaxis de anotación está envuelta en @ClassName(), consiste principalmente en pares clave/valor y puede contener arreglos usando llaves. Las claves de primer nivel no deben ir entre comillas, mientras que las claves dentro de arreglos sí. Cada par clave/valor debe ir en una línea separada y terminar con una coma. Algunas funciones especiales pueden aplicarse a valores, especialmente @Translation().

Ejemplo incorrecto de sintaxis de anotación:

/**
 * @ContentEntityType(
 *   id = "my_entity_type_id",
 *   label = @Translation("My entity type label"),
 *   example_pair = "this_examples_value",
 *   example_array = {
 *     "array_key" = "array_value",
 *     "some_other_key" = "some_other_value",
 *   },
 * )
 */

Anotaciones generales de primer nivel

Handlers (Controladores)

Los handlers se definen en la anotación del objeto como un arreglo. Soportan la entidad, delegando ciertas partes de su ejecución a otras clases PHP. Estas clases "manejan" partes asignadas del comportamiento de la entidad.

Storage - maneja la carga, guardado y eliminación del objeto. Por defecto, las entidades de contenido usan Drupal\Core\Entity\Sql\SqlContentEntityStorage, mientras que las entidades de configuración usan Drupal\Core\Config\Entity\ConfigEntityStorage. Puedes definir un controlador de almacenamiento para extender los métodos estándar de almacenamiento de tu entidad. Por ejemplo, para añadir métodos adicionales para recolectar identificadores de revisiones o contar traducciones.
Ejemplo: "storage" = "Drupal\node\NodeStorage",

Form - en la anotación de handlers de cualquier entidad hay varios controladores de formulario que manejan los formularios de añadir, editar y eliminar la entidad en otras clases PHP.
Ejemplo:

"form" = {
  "add" = "Drupal\block\BlockForm",
  "edit" = "Drupal\block\BlockForm",
  "delete" = "Drupal\block\Form\BlockDeleteForm",
}

También puedes definir un formulario "default" para manejar los formularios "add" y "edit" en lugar de definirlos por separado. Nota que el formulario "delete" casi siempre es manejado por una clase separada porque generalmente es un "formulario de confirmación" que solo pregunta si el usuario está seguro de querer eliminar el objeto.

View builder - este controlador proporciona la clase que maneja la salida de la entidad para la visualización al usuario final. Por ejemplo, al visitar un nodo en Drupal 8, la salida de la entidad la maneja la clase NodeViewBuilder.
Ejemplo: "view_builder" = "Drupal\node\NodeViewBuilder",

List builder - la clase list builder maneja la lista de objetos para propósitos administrativos. Define el contenido de encabezados, filas y operaciones en la página de administración de entidades. Por ejemplo, al visitar /admin/content, el contenido de la tabla está provisto por la clase NodeListBuilder.
Ejemplo: "list_builder" = "Drupal\node\NodeListBuilder",

Route provider - handler opcional que, si está implementado, genera rutas para administrar tu objeto. Esto puede reemplazar la necesidad de definir rutas entity en routing.yml. Nota que route_provider trabaja junto con los enlaces definidos para tu entidad (ver sección Links). La anotación route_provider es un arreglo.
Ejemplo:

"route_provider" = {
  "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider",
}

Access - El handler de acceso se usa para verificar dinámicamente permisos de la entidad. Mapea a una clase que implementa EntityAccessControlHandlerInterface. El núcleo provee la implementación EntityAccessControlHandler, pero para control total querrás extender esta clase.
Ejemplo: "access" = "NodeAccessControlHandler",

Views data - handler que permite a la entidad extender el módulo Views con datos personalizados. Por ejemplo, para añadir baseFieldDefinitions como campos de Views, unir tablas de entidades relacionadas, o modificar datos relacionados con vistas.
Ejemplo: "views_data" = "Drupal\node\NodeViewsData",

Storage schema - handler para modificar configuraciones de almacenamiento de base de datos. Por ejemplo, añadir índices adicionales.
Ejemplo: "storage_schema" = "Drupal\node\NodeStorageSchema",

Translation - handler para modificar cómo los formularios de tu entidad interactúan con las traducciones.
Ejemplo: "translation" = "Drupal\node\NodeTranslationHandler",

Ejemplo completo de handlers:
El núcleo provee handlers que puedes usar "out-of-the-box", pero a menudo querrás extenderlos para mayor control y personalización. Ejemplo de anotación completa con clases base:

handlers = {
  "view_builder" = "Drupal\Core\Entity\EntityViewBuilder",
  "list_builder" = "Drupal\Core\Entity\EntityListBuilder",
  "access" = "Drupal\Core\Entity\EntityAccessControlHandler",
  "views_data" = "Drupal\views\EntityViewsData",
  "storage" = "Drupal\Core\Entity\Sql\SqlContentEntityStorage",
  "storage_schema" = "Drupal\Core\Entity\Sql\SqlContentEntityStorageSchema",
  "translation" = "Drupal\content_translation\ContentTranslationHandler",
  "form" = {
    "default" = "Drupal\Core\Entity\ContentEntityForm",
    "add" = "Drupal\Core\Entity\ContentEntityForm",
    "edit" = "Drupal\Core\Entity\ContentEntityForm",
    "delete" = "Drupal\Core\Entity\ContentEntityDeleteForm",
  },
  "route_provider" = {
    "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider",
  },
},

Links (Enlaces)

Los enlaces se definen en la anotación del objeto con sintaxis de arreglo. Tienen un conjunto fijo de claves cuyos valores son URI donde se puede administrar el tipo de entidad o instancias de este. Pueden aplicarse tanto para entidades de contenido como de configuración.

Ejemplo:

id = "node",
handlers = {
  "route_provider" = {
    "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider"
  }
},
links = {
  "canonical" = "/node/{node}",
  "add-page" = "/node/add",
  "add-form" = "/node/add/{node_type}",
  "edit-form" = "/node/{node}/edit",
  "delete-form" = "/node/{node}/delete",
  "collection" = "/admin/content",
},

Nota que esto no es tomado literalmente del módulo Node, solo un ejemplo.

Crear estos enlaces no genera automáticamente las rutas para esos URI. Para que estén disponibles, tu módulo debe implementar un archivo routing.yml o usar el handler route_provider en la anotación.

Links y Route Provider

Los enlaces anteriores junto con route_provider hacen que las siguientes rutas nombradas estén disponibles en Drupal.

Uso de enlaces
Estos enlaces pueden obtenerse con el método toUrl() del objeto:

$view_url_object = $entity->toUrl();  // Por defecto 'canonical'
$edit_url_string = $entity->toUrl('edit-form')->toString();

Enlaces:

• Entity API - Documentación generada.
• Crear una entidad de contenido personalizada - Objeto personalizado muy simple.
• Crear un tipo de entidad de contenido en Drupal 8 - Ejemplo avanzado con handlers, permisos, rutas y enlaces.
• Crear un tipo de entidad de configuración en Drupal 8 - Ejemplo avanzado con handlers, rutas y esquema.
• [Externo] Entity Type Walkthrough - documentación para tipos de entidad generales en práctica.