Werken met Entity API

Bevat methodes van de algemene Entity API

• Entity::create()
• Entity::load()
• Entity::save()
• Entity::id()
• Entity::bundle()
• Entity::isNew()
• Entity::label()

Meer specifieke API’s worden behandeld in afzonderlijke hoofdstukken.

Controleren

// Zorg dat een object een entity is.
if ($entity instanceof \Drupal\Core\Entity\EntityInterface) {
}

// Zorg dat het een content entity is.
if ($entity instanceof \Drupal\Core\Entity\ContentEntityInterface) {
}
// of:
if ($entity->getEntityType()->getGroup() == 'content') {
}

// Haal het entity type of de entity type ID op.
$entity->getEntityType();
$entity->getEntityTypeId();

// Zorg dat het een node is.
if ($entity instanceof \Drupal\node\NodeInterface) {
}

Informatie ophalen van entities / Entity-methodes

Er zijn verschillende algemene methodes beschikbaar om informatie van een object op te halen, zoals ID, bundle, revisie-ID enz. Zie de documentatie van EntityInterface voor details.

// Haal het ID op.
$entity->id();

// Haal de bundle op.
$entity->bundle();

// Controleer of de entity nieuw is.
$entity->isNew();

// Haal het label van een entity op. Vervanging voor entity_label().
$entity->label();

// Haal het URL-object van een entity op.
$entity->toUrl();

// Haal intern pad of pad-alias (indien aanwezig) van een entity op.
$entity->toUrl()->toString();

// Maak een duplicaat dat als nieuwe entity kan worden opgeslagen.
$duplicate = $entity->createDuplicate();

Entity aanmaken

// Je kunt de statische create()-methode gebruiken als je de entity class kent.
$node = Node::create([
  'type' => 'article',
  'title' => 'The node title',
]);

// Gebruik de entity type manager (aanbevolen).
$node = \Drupal::entityTypeManager()->getStorage('node')->create(['type' => 'article', 'title' => 'Another node']);

// Of gebruik de procedurele wrapper (verouderd).
$node = entity_create('node', [
  'title' => 'My node',
  'body' => 'The body content. Dit werkt zo dankzij de nieuwe Entity Field
          API. Het wordt toegewezen als de waarde van het eerste field item in de
          standaardtaal.',
]);

Standaardinstellingen uit de annotatie van het field type worden alleen toegevoegd voor ontbrekende top-level keys; er wordt geen deep merge uitgevoerd.

Vermijd het gebruik van de statische methode Entity::create() in objectgeoriënteerde code. Gebruik in plaats daarvan dependency injection om de entity type manager in te voegen en een entity aan te maken met $this->entityTypeManager->getStorage($entity_type)->create(). Dit zorgt ervoor dat de code goed gescheiden is en kan worden getest door de module.

Voor herkenning in de IDE kun je ook de entity storage interface toewijzen aan een property. Bijvoorbeeld: $this->nodeStorage = $this->entityTypeManager()->getStorage('node');. Om een entity aan te maken gebruik je dan $this->nodeStorage->create().

Laden

// Gebruik de statische methode
$node = Node::load(1);

// Verouderd. Dynamisch entity type, entity_load() laadt nu één entity,
// de 7.x entity_load() is hernoemd naar entity_load_multiple().
$entity = entity_load($entity_type, $id);

// Gebruik de storage controller (aanbevolen).
$entity = \Drupal::entityTypeManager()->getStorage($entity_type)->load(1);

// Meerdere entities laden, bestaat ook als entity_load_multiple().
$entities = \Drupal::entityTypeManager()->getStorage($entity_type)->loadMultiple([1, 2, 3]);

// Entities laden op basis van hun propertywaarden.
$entities = \Drupal::entityTypeManager()->getStorage('node')->loadByProperties(['type' => 'article']);

Om een object bij te werken, laad het eerst en sla het daarna opnieuw op met de wijzigingen.

Vermijd het gebruik van de statische methode Entity::load() in objectgeoriënteerde code. Gebruik in plaats daarvan dependency injection om de entity type manager in te voegen en de entity te laden met $this->entityTypeManager->getStorage($entity_type)->load($entity_id). Dit zorgt voor gescheiden code en testbaarheid.

Entity opslaan

// Een entity opslaan.
$entity->save();

Dit werkt zowel voor nieuwe als bestaande entities; de entity zelf houdt bij of deze nieuw is of niet. Voor content entities hangt dit standaard af van het al dan niet hebben van een ID. Om een object met een ID toch als nieuwe entity op te slaan (bijvoorbeeld bij import), kun je de isNew-flag gebruiken.

// Het volgende probeert een nieuwe node met ID 5 in te voegen,
// dit zal falen als die node al bestaat.
$node->nid->value = 5;
$node->enforceIsNew(TRUE);
$node->save();

Entity verwijderen

// Een enkele entity verwijderen.
$entity = \Drupal::entityTypeManager()->getStorage('node')->load(1);
$entity->delete();

// Meerdere entities tegelijk verwijderen.
\Drupal::entityTypeManager()->getStorage($entity_type)->delete([$id1 => $entity1, $id2 => $entity2]);

Toegangscontrole

De methode access() kan worden gebruikt om te controleren wie wat mag doen met een entity. De methode ondersteunt verschillende operaties. Standaardoperaties zijn bekijken, bijwerken, verwijderen en aanmaken. Aanmaken is wat bijzonder, zie hieronder.

Toegangscontroles worden doorgestuurd naar de access controller. (TODO: Link toevoegen)

// Controleer view-toegang van een entity.
// Dit controleert standaard voor de momenteel ingelogde gebruiker.
if ($entity->access('view')) {

}

// Controleer of een bepaalde gebruiker een entity kan verwijderen.
if ($entity->access('delete', $account)) {

}

Bij het controleren van create-toegang bestaat de entity meestal nog niet. Eentje aanmaken alleen om toegang te controleren is een dure operatie. Daarom moet create-access rechtstreeks op de access controller gecontroleerd worden.

\Drupal::entityTypeManager()->getAccessControlHandler('node')->createAccess('article');

Als de entity al bestaat, werkt $entity->access('create') ook. Dit verwijst gewoon door naar de methode createAccess(), net zoals andere operaties de methode access() op de access controller doorsturen.

OPMERKING. In sommige online handleidingen wordt \Drupal::entityManager() gebruikt, maar in versie 8.x is dit verouderd en zal het worden verwijderd in versie 9.x. Gebruik dus \Drupal::entityTypeManager() in plaats van \Drupal::entityManager().