Entity API implementeert de Typed Data API

Aanzienlijke verbetering

• Entity API implementeert nu de Typed Data API

In deze nieuwe implementatie van de Entity API is alles een veld, gebaseerd op dezelfde API, waardoor entiteiten voorspelbaar en consistent zijn.

Het Drupal datamodel begrijpen

Voordat we in de Typed Data API zelf duiken, moeten we eerst begrijpen hoe het Drupal-datamodel (Entity API) eerder werd gezien. Dit is belangrijk, omdat hier de Typed Data API vandaan komt en de Entity API een van de systemen is waarvoor deze is ontwikkeld.

Een entiteit is een complex gegeven dat bestaat uit andere gegevens, zoals velden met een lijst van items. Een velditem is ook complex – het bestaat uit meer datastukken, zoals een tekstwaarde en een invoerformaat. Maar de complexiteit gaat zo ver dat iets kan worden beschreven als een primitief datatype, zoals een string of een integer.

Vereenvoudigd voorbeeld uit Drupal 7 (voorbeeld zonder taalsleutel, omdat Drupal 8 dit anders afhandelt):

Voorbeeld 1

// Entities zijn complex, ze bevatten andere gegevens.
$entity;

// Velden zijn niet complex, ze bevatten alleen een lijst met items.
$entity->image;

// Items zijn complex, ze bevatten andere gegevens. Ze zijn ook vertaalbaar en toegankelijk (heeft rechten).
$entity->image[0];

// Het bestands-ID is een primitief geheel getal.
$entity->image[0]['fid'];

// De alternatieve tekst is een primitieve string.
$entity->image[0]['alt'];

Alles samenbrengen

Hieronder staat een vereenvoudigd voorbeeld van hoe de Entity API interfaces implementeert die verschillen van de Typed Data API. In werkelijkheid breidt de Entity API deze interfaces uit met extra methoden die nodig zijn voor de Entity API. Toch zijn alle onderstaande beweringen waar:

Voorbeeld 2

// Entities zijn complex.
$entity instanceof ComplexDataInterface;

// Properties zijn niet complex, ze zijn slechts een lijst van items.
$entity->get('image') instanceof ListInterface;

// Items zijn complex.
$entity->get('image')->offsetGet(0) instanceof ComplexDataInterface;

// Het typed data object dat de alt-waarde vertegenwoordigt.
$entity->get('image')->offsetGet(0)->get('alt') instanceof TypedDataInterface;

// De alt-waarde is een primitieve string.
is_string($entity->get('image')->offsetGet(0)->get('alt')->getValue());

Hieronder een kort overzicht van hoe de Entity API de Typed Data API uitbreidt om enkele extra behoeften te ondersteunen:

Voorbeeld 3

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

interface FielditemListInterface extends ListInterface {
 // ...
}

// Merk op dat dit twee interfaces uitbreidt. Uitleg hieronder.
interface FieldItemInterface extends ComplexDataInterface, TypedDataInterface {
 // ...
}

// Hieronder volgen enkele daadwerkelijke implementaties.

// Breidt een abstracte klasse uit met gemeenschappelijke logica.
class ImageItem extends FieldItemBase {
 // ...
}

// Breidt een abstracte klasse uit met gemeenschappelijke logica.
class String extends TypedData {
 // ...
}

[De volgende twee paragrafen vereisen extra werk]

De twee meest opvallende dingen hierboven:

1. EntityInterface breidt enkele service-interfaces uit voor zaken zoals vertaling en toegangsrechten. Dit is vrij duidelijk.
2. FieldItemInterface breidt zowel ComplexDataInterface als TypedDataInterface uit. Zoals eerder uitgelegd zijn items complex in de zin dat ze meer datastukken bevatten (bijvoorbeeld tekstwaarde en formaat voor tekstelementen). Maar tegelijkertijd is het item zelf ook een onderdeel van typed data, dus heeft het zijn eigen definitie en datatype.

Dus, om samen te vatten, naast voorbeeld 2, zijn alle onderstaande beweringen ook waar:

Voorbeeld 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());

Gebruik van de API

[Deze sectie heeft nog enkele extra voorbeelden nodig]

De Entity API definieert enkele magische methoden, zoals __get(), om snelle en eenvoudige toegang te bieden tot veldwaarden. Het gebruik van de API is dus heel eenvoudig, en de syntaxis doet denken aan de tijd vóór Drupal 8.

Het ophalen van de werkelijke waarde van de alternatieve tekst van een afbeelding wordt gedaan zoals hieronder getoond:

Voorbeeld 5

// De meest uitgebreide manier.
$string = $entity->get('image')->offsetGet(0)->get('alt')->getValue();

// Met de magie toegevoegd door de Entity API.
$string = $entity->image[0]->alt;

// Met nog meer magie toegevoegd door de Entity API, om standaard het eerste item
// in de lijst op te halen.
$string = $entity->image->alt;

Bovenstaand voorbeeld voegt alleen een mooie syntaxis toe aan de oude API. De onderstaande voorbeelden tonen waar de echte waarde van deze API naar voren komt – validatie van gegevens:

Voorbeeld 6

// Geeft een array terug met benoemde sleutels voor alle velden en hun
// definities. Bijvoorbeeld het 'image'-veld.
$property_definitions = $entity->getFieldDefinitions();

// Geeft een array terug met naam-sleutels voor alle properties en hun
// definities. Bijvoorbeeld de 'file_id' en 'alt' properties.
$property_definitions = $entity->image
  ->getFieldDefinition()
  ->getFieldStorageDefinition()
  ->getPropertyDefinitions();

// Geeft alleen de definitie terug voor de 'alt' property.
$string_definition = $entity->image
  ->getFieldDefinition()
  ->getFieldStorageDefinition()
  ->getPropertyDefinition('alt');

Op basis van bovenstaande definities kunnen we nu slimme dingen doen, zoals serialisatie of andere datamatrices. We kunnen deze gegevens ook aanbieden via semantisch rijke API’s, zoals een JSON-LD eindpunt, zodat andere systemen de basis van onze gegevens kunnen begrijpen.

Zie https://drupal.org/node/2078241 voor meer informatie over hoe velddefinities voor entiteitstypen te definiëren en te gebruiken.