Entity-Typen

• Drupal 7 – Entities waren allgemeine stdClass-Objekte.
• Drupal 8 – Entities sind jetzt typisierte Objekte, wobei jeder Entitätstyp eine Klasse definiert, die für Instanzen dieser Entität verwendet wird.

Anforderungen
Entity-Klassen müssen im Namensraum Entity des Moduls platziert werden, das den Entitätstyp bereitstellt, z.B. \Drupal\[module_name]\Entity. Das bedeutet, dass die PHP-Klassendateien der Entität im Modulverzeichnis unter src/Entity zu finden sind.

Der Docblock für die Klasse muss eine EntityType-Annotation enthalten, die Metadaten für diese Entität definiert. Dazu gehören Dinge wie der Label des Entitätstyps, Controller, Tabellen usw. Eine dokumentierte Liste aller verfügbaren Metadaten-Eigenschaften findet man in der Klasse \Drupal\Core\Entity\Annotation\EntityType.

Namengebung

Entitätstypnamen sollten mit dem Modulnamen als Präfix versehen werden, falls sich Typname und Modulname unterscheiden. Das Präfix der eigentlichen Entitätsklasse ist nicht erforderlich, da sie sich im Namensraum des definierenden Moduls befindet, vorausgesetzt der Name ist eindeutig genug. Zum Beispiel heißt der Entitätstyp für Taxonomie-Begriffe taxonomy_term, und die Klassenname ist Drupal\taxonomy\Entity\Term.

Interfaces

Drupal 8 empfiehlt, Typ-Hinweise und Methoden über Interfaces statt Klassen zu deklarieren. Zum Beispiel nimmt das gemeinsame Entity-Storage eine Typ-Hinweis auf EntityInterface entgegen, z.B. in hook_entity_insert(EntityInterface $entity), während das Knotenspezifische Storage eine Typ-Hinweis auf NodeInterface verwendet, z.B. in hook_node_insert(NodeInterface $node).

Entity-Felder/-Eigenschaften sind oft kurz, speicherorientiert und wenig aussagekräftig. Außerdem nutzen Content Entities üblicherweise keine spezifischen Eigenschaften für ihre Felder (inklusive Basisfelder wie Node-Titel).

Der empfohlene Ansatz ist daher, ein Interface mit dokumentierten Methodennamen anzubieten. Dabei gelten einige Regeln:

• Methoden beginnen typischerweise mit get/set/is oder ähnlich: getSomething(), setSomething($value), isSomething().
• Fügen Sie nur Methoden hinzu, die anderer Code ändern muss. Das Änderungsdatum eines Nodes ($node->updated) soll z.B. nicht verändert werden, daher gibt es $node->getChangedTime(), aber kein $node->setChangedTime().
• Verwenden Sie selbsterklärende Methodennamen, z.B. heißt die Methode zum Zugriff auf $node->status $node->isPublished().

Verständlichkeit

Um herauszufinden, welche Entitätstypen ein Modul anbietet, suchen Sie in dessen Entity-Namensraum nach Klassen mit der Annotation @EntityType, die außerdem einen Namen im Annotation-Key id enthalten.

Wenn Sie herausfinden wollen, wo ein bestimmter Entitätstyp definiert ist, suchen Sie zuerst nach dem Entitätstyp-Präfix. Falls das Modul das Namensschema nicht einhält, suchen Sie nach id = "$type". Ist der Klassen- oder Interface-Name bekannt, zeigt der Namespace den Herkunftsort an.

Beispiel

core/modules/node/src/Entity/Node.php:

namespace Drupal\node\Entity;

use Drupal\Core\Entity\ContentEntityBase;
use Drupal\Core\Entity\EntityChangedTrait;
use Drupal\Core\Entity\EntityStorageInterface;
use Drupal\Core\Entity\EntityTypeInterface;
use Drupal\Core\Field\BaseFieldDefinition;
use Drupal\Core\Session\AccountInterface;
use Drupal\node\NodeInterface;
use Drupal\user\UserInterface;

/**
 * Definiert die Node-Entity-Klasse.
 *
 * @ContentEntityType(
 *   id = "node",
 *   label = @Translation("Content"),
 *   bundle_label = @Translation("Content type"),
 *   handlers = {
 *     "storage" = "Drupal\node\NodeStorage",
 *     "storage_schema" = "Drupal\node\NodeStorageSchema",
 *     "view_builder" = "Drupal\node\NodeViewBuilder",
 *     "access" = "Drupal\node\NodeAccessControlHandler",
 *     "views_data" = "Drupal\node\NodeViewsData",
 *     "form" = {
 *       "default" = "Drupal\node\NodeForm",
 *       "delete" = "Drupal\node\Form\NodeDeleteForm",
 *       "edit" = "Drupal\node\NodeForm"
 *     },
 *     "route_provider" = {
 *       "html" = "Drupal\node\Entity\NodeRouteProvider",
 *     },
 *     "list_builder" = "Drupal\node\NodeListBuilder",
 *     "translation" = "Drupal\node\NodeTranslationHandler"
 *   },
 *   base_table = "node",
 *   data_table = "node_field_data",
 *   revision_table = "node_revision",
 *   revision_data_table = "node_field_revision",
 *   translatable = TRUE,
 *   list_cache_contexts = { "user.node_grants:view" },
 *   entity_keys = {
 *     "id" = "nid",
 *     "revision" = "vid",
 *     "bundle" = "type",
 *     "label" = "title",
 *     "langcode" = "langcode",
 *     "uuid" = "uuid",
 *     "status" = "status",
 *     "uid" = "uid",
 *   },
 *   bundle_entity_type = "node_type",
 *   field_ui_base_route = "entity.node_type.edit_form",
 *   common_reference_target = TRUE,
 *   permission_granularity = "bundle",
 *   links = {
 *     "canonical" = "/node/{node}",
 *     "delete-form" = "/node/{node}/delete",
 *     "edit-form" = "/node/{node}/edit",
 *     "version-history" = "/node/{node}/revisions",
 *     "revision" = "/node/{node}/revisions/{node_revision}/view",
 *   }
 * )
 */
class Node extends ContentEntityBase implements NodeInterface {
  // ...
}

Um ein vollständiges Bild der Entities in Drupal 8 zu erhalten, können wir uns folgendes Diagramm anschauen. Es stellt Entitätsklassen dar. Um es in einem neuen Tab zu öffnen: