Arbeiten mit der Entity API

Behandelt die Methoden der allgemeinen Objekt-API

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

Spezifischere APIs werden in bestimmten Kapiteln behandelt.

Prüfen

// Sicherstellen, dass ein Objekt eine Entity ist.
if ($entity instanceof \Drupal\Core\Entity\EntityInterface) {
}

// Sicherstellen, dass es sich um eine Content-Entity handelt.
if ($entity instanceof \Drupal\Core\Entity\ContentEntityInterface) {
}
// oder:
if ($entity->getEntityType()->getGroup() == 'content') {
}

// Den Entity-Typ oder die Entity-Typ-ID erhalten.
$entity->getEntityType();
$entity->getEntityTypeId();

// Sicherstellen, dass es sich um einen Node handelt.
if ($entity instanceof \Drupal\node\NodeInterface) {
}

Informationen von der Entity erhalten / Entity-Methoden

Es stehen mehrere allgemeine Methoden zur Verfügung, um Informationen vom Objekt zu erhalten, wie ID, Bundle, Revisions-ID usw. Details siehe in der EntityInterface-Dokumentation.

// ID erhalten.
$entity->id();

// Bundle erhalten.
$entity->bundle();

// Prüfen, ob die Entity neu ist.
$entity->isNew();

// Label einer Entity erhalten. Ersatz für entity_label().
$entity->label();

// URL-Objekt einer Entity erhalten.
$entity->toUrl();

// Interner Pfad, Pfad-Alias (falls vorhanden) einer Entity.
$entity->toUrl()->toString();

// Duplikat erstellen, das als neue Entity gespeichert werden kann.
$duplicate = $entity->createDuplicate();

Entity erstellen

// Statische create()-Methode verwenden, wenn die Entity-Klasse bekannt ist.
$node = Node::create([
  'type' => 'article',
  'title' => 'The node title',
]);

// Entity Type Manager verwenden (empfohlen).
$node = \Drupal::entityTypeManager()->getStorage('node')->create(['type' => 'article', 'title' => 'Another node']);

// Oder das prozedurale Wrapper verwenden (veraltet).
$node = entity_create('node', [
  'title' => 'My node',
  'body' => 'Der Body-Inhalt. Das funktioniert so dank der neuen Entity Field API. Es wird als Wert des ersten Feldelements in der Standardsprache zugewiesen.',
]);

Standardwerte aus der Annotation des Feldtyps werden nur für fehlende Top-Level-Schlüssel hinzugefügt; eine tiefe Zusammenführung findet nicht statt.

Vermeiden Sie die Verwendung der statischen Methode Entity::create() im objektorientierten Code. Stattdessen sollten Sie Dependency Injection verwenden, um den Entity Type Manager einzuspritzen und die Entity mit $this->entityTypeManager->getStorage($entity_type)->create() zu erstellen. So wird sichergestellt, dass der Code richtig getrennt und vom Modul überprüfbar ist.

Zur Erkennung in IDEs können Sie die Storage-Interface einer Property zuweisen. Beispiel: $this->nodeStorage = $this->entityTypeManager->getStorage('node'); Um eine Entity zu erstellen, können Sie dann $this->nodeStorage->create() verwenden.

Laden

// Statische Methode verwenden
$node = Node::load(1);

// Veraltet. Dynamischer Entity-Typ, entity_load() lädt nun eine einzelne Entity, das 7.x entity_load() wurde in entity_load_multiple() umbenannt.
$entity = entity_load($entity_type, $id);

// Storage Controller verwenden (empfohlen).
$entity = \Drupal::entityTypeManager()->getStorage($entity_type)->load(1);

// Mehrere Entities laden, existiert auch als entity_load_multiple().
$entities = \Drupal::entityTypeManager()->getStorage($entity_type)->loadMultiple([1, 2, 3]);

// Entities anhand ihrer Eigenschaftswerte laden.
$entities = \Drupal::entityTypeManager()->getStorage('node')->loadByProperties(['type' => 'article']);

Um ein Objekt zu aktualisieren, laden Sie es und speichern es mit Änderungen erneut.

Vermeiden Sie die Verwendung der statischen Methode Entity::load() im objektorientierten Code. Stattdessen verwenden Sie Dependency Injection, um den Entity Type Manager einzuspritzen und laden die Entity mit $this->entityTypeManager->getStorage($entity_type)->load($entity_id). So wird der Code sauber getrennt und testbar.

Entity speichern

// Entity speichern.
$entity->save();

Funktioniert für neue und bestehende Entities, die Entity selbst verfolgt, ob sie neu ist. Für Content-Entities ist das standardmäßig abhängig davon, ob sie eine ID haben. Um ein Objekt mit einer ID als neu zu speichern (z.B. beim Import), kann der isNew-Flag gesetzt werden.

// Folgendes versucht einen neuen Node mit der ID 5 einzufügen, was fehlschlägt, wenn dieser Node bereits existiert.
$node->nid->value = 5;
$node->enforceIsNew(TRUE);
$node->save();

Entity löschen

// Eine einzelne Entity löschen.
$entity = \Drupal::entityTypeManager()->getStorage('node')->load(1);
$entity->delete();

// Mehrere Entities auf einmal löschen.
\Drupal::entityTypeManager()->getStorage($entity_type)->delete([$id1 => $entity1, $id2 => $entity2]);

Zugriffskontrolle

Die Methode access() kann verwendet werden, um zu prüfen, wer was mit der Entity tun darf. Die Methode unterstützt verschiedene Operationen, Standardoperationen sind view, update, delete und create – create ist etwas speziell, siehe unten.

Zugriffsprüfungen werden an den Access Controller delegiert. (TODO: Link hinzufügen)

// Prüfe die Ansicht-Berechtigung einer Entity.
// Standardmäßig wird der Zugriff für den aktuell angemeldeten Nutzer geprüft.
if ($entity->access('view')) {

}

// Prüfe, ob ein bestimmter Nutzer eine Entity löschen darf.
if ($entity->access('delete', $account)) {

}

Beim Prüfen des Erstellungszugriffs existiert die Entity meist noch nicht. Eine Entity nur zum Prüfen zu erstellen, ist ressourcenintensiv. Daher sollte die Zugriffskontrolle für create direkt am Access Controller geprüft werden.

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

Existiert die Entity bereits, funktioniert auch $entity->access('create'), welches intern einfach createAccess() aufruft, genauso wie andere Operationen access() an den Access Controller weiterleiten.

HINWEIS: In einigen Online-Tutorials wird \Drupal::entityManager() verwendet, diese Methode ist jedoch in Version 8.x veraltet und wird in Version 9.x entfernt. Verwenden Sie stattdessen \Drupal::entityTypeManager().