Entity API implementa la API de Typed Data

Mejora significativa

• Entity API ahora implementa la API de Typed Data

En esta nueva implementación, Entity API trata todo como un campo basado en la misma API, por lo que las entidades son predecibles y consistentes.

Entendiendo el modelo de datos de Drupal

Primero, antes de profundizar en la API Typed Data, debemos comprender cómo se percibía antes el modelo de datos de Drupal (Entity API). Esto es importante porque de aquí proviene la API Typed Data y Entity API es uno de los sistemas para los que fue diseñada.

Una entidad es una estructura compleja de datos compuesta por otras partes de datos, como campos con listas de elementos. Un elemento de campo también es complejo, compuesto de más fragmentos de datos, como valor de texto y formato de entrada. Sin embargo, la complejidad llega hasta el punto de que algo se puede describir como un tipo de dato primitivo, como una cadena o un número entero.

Ejemplo simplificado de Drupal 7 (ejemplo sin clave de idioma, porque Drupal 8 maneja esto de forma diferente):

Ejemplo 1

// Las entidades son complejas, contienen otras piezas de datos.
$entity;

// Los campos no son complejos, solo contienen una lista de elementos.
$entity->image;

// Los elementos son complejos, contienen otras piezas de datos. También son traducibles y accesibles (con permisos).
$entity->image[0];

// El ID del archivo es un entero primitivo.
$entity->image[0]['fid'];

// El texto alternativo es una cadena primitiva.
$entity->image[0]['alt'];

Juntándolo todo

A continuación se muestra un ejemplo simplificado de cómo Entity API implementa interfaces además de la API Typed Data. En realidad, Entity API extiende estas interfaces agregando métodos adicionales necesarios para Entity API. Sin embargo, todas las afirmaciones a continuación son verdaderas:

Ejemplo 2

// Las entidades son complejas.
$entity instanceof ComplexDataInterface;

// Las propiedades no son complejas, solo son una lista de elementos.
$entity->get('image') instanceof ListInterface;

// Los elementos son complejos.
$entity->get('image')->offsetGet(0) instanceof ComplexDataInterface;

// El objeto typed data que representa el valor alt.
$entity->get('image')->offsetGet(0)->get('alt') instanceof TypedDataInterface;

// El valor alt es una cadena primitiva.
is_string($entity->get('image')->offsetGet(0)->get('alt')->getValue());

A continuación un resumen breve de cómo Entity API extiende la API Typed Data para cubrir algunas necesidades adicionales:

Ejemplo 3

interface EntityInterface extends ComplexDataInterface, TranslatableInterface, AccessibleInterface {
 // ...
}

interface FielditemListInterface extends ListInterface {
 // ...
}

// Nota que esta extiende dos interfaces. Explicación abajo.
interface FieldItemInterface extends ComplexDataInterface, TypedDataInterface {
 // ...
}

// A continuación algunas implementaciones reales.

// Extiende una clase abstracta con lógica común.
class ImageItem extends FieldItemBase {
 // ...
}

// Extiende una clase abstracta con lógica común.
class String extends TypedData {
 // ...
}

[Los siguientes dos párrafos necesitan trabajo adicional]

Las dos cosas más notables arriba:

1. EntityInterface extiende algunas interfaces de servicio para cosas como traducción y acceso. Esto debería ser bastante obvio.
2. FieldItemInterface extiende tanto ComplexDataInterface como TypedDataInterface. Como se explicó antes, los elementos son complejos en el sentido de que contienen más fragmentos de datos (por ejemplo, valor de texto y formato para elementos de texto). Pero al mismo tiempo, un elemento es parte de datos tipados, por lo que tiene su propia definición y tipo de dato.

Así que para resumir, además del ejemplo 2, todas las afirmaciones siguientes también son verdaderas:

Ejemplo 4

$entity instanceof EntityInterface;

$entity->get('image') instanceof FieldItemListInterface;

$entity->get('image')->offsetGet(0) instanceof FieldItemInterface;

$entity->get('image')->offsetGet(0)->get('alt') instanceof String;

is_string($entity->get('image')->offsetGet(0)->get('alt')->getValue());

Uso de la API

[Esta sección necesita algunos ejemplos adicionales]

Entity API define algunos métodos mágicos, como __get(), para proporcionar un acceso rápido y sencillo a los valores de campo. Así, usar la API es muy simple y la sintaxis recuerda a la era pre-Drupal 8.

Extraer el valor válido del texto alternativo de la imagen se hace así:

Ejemplo 5

// La forma más detallada.
$string = $entity->get('image')->offsetGet(0)->get('alt')->getValue();

// Con magia añadida por Entity API.
$string = $entity->image[0]->alt;

// Con más magia añadida por Entity API, para obtener el primer elemento
// de la lista por defecto.
$string = $entity->image->alt;

El ejemplo anterior solo añade una sintaxis agradable a la antigua API. Los ejemplos siguientes muestran dónde reside el verdadero valor de esta API: la validación de datos:

Ejemplo 6

// Devuelve un array con claves nombradas para todos los campos y sus
// definiciones. Por ejemplo el campo ‘image’.
$property_definitions = $entity->getFieldDefinitions();

// Devuelve un array con claves nombradas para todas las propiedades y sus
// definiciones. Por ejemplo las propiedades ‘file_id’ y ‘alt’.
$property_definitions = $entity->image
  ->getFieldDefinition()
  ->getFieldStorageDefinition()
  ->getPropertyDefinitions();

// Devuelve solo la definición para la propiedad ‘alt’.
$string_definition = $entity->image
  ->getFieldDefinition()
  ->getFieldStorageDefinition()
  ->getPropertyDefinition('alt');

Basándonos en las definiciones anteriores ahora podemos hacer cosas inteligentes, como serialización u otros arrays de datos. También podemos proveer estos datos a través de APIs semánticamente enriquecidas como un endpoint JSON-LD para que otros sistemas puedan entender la base de nuestros datos.

Vea https://drupal.org/node/2078241 para más información sobre cómo definir y usar definiciones de campos de tipo entidad.