Entity API implementira Typed Data API

Značajno poboljšanje

• Entity API sada implementira API Typed Data

U ovoj novoj implementaciji Entity API-ja, sve predstavlja polje bazirano na istom API-ju, tako da su entiteti predvidljivi i konzistentni.

Razumevanje Drupal modela podataka

Pre nego što se udubimo u sam Typed Data API, potrebno je razumeti kako je ranije shvatan model podataka Drupala (Entity API). Ovo je važno jer je odatle potekao Typed Data API, a Entity API je jedan od sistema za koje je dizajniran.

Entitet je složen podatak, sastavljen od drugih podataka kao što su polja koja sadrže listu elemenata. Element polja je takođe složen - sastoji se od više delova podataka, kao što su tekstualna vrednost i format unosa. Međutim, složenost ide dotle da nešto može biti opisano kao primitivni tip podataka, kao što su string ili ceo broj.

Pojednostavljeni primer iz Drupala 7 (bez jezičke oznake jer Drupal 8 to drugačije obrađuje):

Primer 1

// Entiteti su složeni, sadrže druge delove podataka.
$entity;

// Polja nisu složena, sadrže samo listu elemenata.
$entity->image;

// Elementi su složeni, sadrže druge delove podataka. Takođe su prevodivi i pristupačni (sa dozvolama).
$entity->image[0];

// ID fajla je primitivni ceo broj.
$entity->image[0]['fid'];

// Alternativni tekst je primitivni string.
$entity->image[0]['alt'];

Sve povezujemo

Ispod je pojednostavljeni primer kako Entity API implementira interfejse naspram Typed Data API-ja. U stvari, Entity API proširuje te interfejse dodajući metode koje su potrebne Entity API-ju. Ipak, svi navedeni uslovi su istiniti:

Primer 2

// Entiteti su složeni.
$entity instanceof ComplexDataInterface;

// Svojstva nisu složena, samo su lista elemenata.
$entity->get('image') instanceof ListInterface;

// Elementi su složeni.
$entity->get('image')->offsetGet(0) instanceof ComplexDataInterface;

// Tipizovani podatak koji predstavlja alt vrednost.
$entity->get('image')->offsetGet(0)->get('alt') instanceof TypedDataInterface;

// Alt vrednost je primitivni string.
is_string($entity->get('image')->offsetGet(0)->get('alt')->getValue());

Ispod je kratak pregled kako Entity API proširuje Typed Data API da bi zadovoljio dodatne potrebe:

Primer 3

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

interface FielditemListInterface extends ListInterface {
 // ...
}

// Napomena da ovo proširuje dva interfejsa. Objašnjenje ispod.
interface FieldItemInterface extends ComplexDataInterface, TypedDataInterface {
 // ...
}

// Slede neke konkretne implementacije.

// Proširuje apstraktnu klasu sa zajedničkom logikom.
class ImageItem extends FieldItemBase {
 // ...
}

// Proširuje apstraktnu klasu sa zajedničkom logikom.
class String extends TypedData {
 // ...
}

[Sledeća dva pasusa zahtevaju dodatni rad]

Dve najvažnije stvari gore:

1. EntityInterface proširuje pomoćne interfejse za prevod i pristup. To je prilično jasno.
2. FieldItemInterface proširuje i ComplexDataInterface i TypedDataInterface. Kao što je ranije objašnjeno, elementi su složeni jer sadrže više fragmenata podataka (npr. tekstualnu vrednost i format za tekstualne elemente). Istovremeno, element je deo tipizovanih podataka, tako da ima sopstvenu definiciju i tip podatka.

Zaključno, pored primera 2, sledeći uslovi su takođe tačni:

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

Korišćenje API-ja

[Potrebno je dodati još nekoliko primera u ovom odeljku]

Entity API definiše magične metode poput __get() za brz i lak pristup vrednostima polja. Dakle, korišćenje API-ja je vrlo jednostavno i sintaksa podseća na period pre Drupala 8.

Pristup stvarnoj vrednosti alternativnog teksta slike može se izvršiti na sledeći način:

Primer 5

// Najdetaljniji način.
$string = $entity->get('image')->offsetGet(0)->get('alt')->getValue();

// Sa magijom koju dodaje Entity API.
$string = $entity->image[0]->alt;

// Još više magije Entity API-ja, za dohvat prvog elementa liste po defaultu.
$string = $entity->image->alt;

Gore navedeni primer samo dodaje lepšu sintaksu starom API-ju. Sledeći primeri pokazuju gde stvarna vrednost ovog API-ja dolazi do izražaja - validacija podataka:

Primer 6

// Vraća niz sa imenovanim ključevima za sva polja i njihove definicije. Na primer polje 'image'.
$property_definitions = $entity->getFieldDefinitions();

// Vraća niz sa imenovanim ključevima za sva svojstva i njihove definicije. Na primer 'file_id' i 'alt'.
$property_definitions = $entity->image
  ->getFieldDefinition()
  ->getFieldStorageDefinition()
  ->getPropertyDefinitions();

// Vraća samo definiciju za svojstvo 'alt'.
$string_definition = $entity->image
  ->getFieldDefinition()
  ->getFieldStorageDefinition()
  ->getPropertyDefinition('alt');

Na osnovu ovih definicija možemo sada raditi pametne stvari, kao što je serijalizacija ili konvertovanje u druge nizove podataka. Takođe možemo izlagati te podatke preko semantički bogatih API-ja, poput JSON-LD krajnje tačke, kako bi drugi sistemi mogli da razumeju osnove naših podataka.

Pogledajte https://drupal.org/node/2078241 za više informacija o definisanju i korišćenju definicija polja tipa entiteta.