Travail avec l’Entity API

Couvre les méthodes API des objets généraux

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

Des API plus spécifiques seront abordées dans des chapitres dédiés.

Vérifier

// S’assurer qu’un objet est une entité.
if ($entity instanceof \Drupal\Core\Entity\EntityInterface) {
}

// S’assurer que c’est une entité de contenu.
if ($entity instanceof \Drupal\Core\Entity\ContentEntityInterface) {
}
// ou :
if ($entity->getEntityType()->getGroup() == 'content') {
}

// Obtenir le type d’entité ou l’ID du type d’entité.
$entity->getEntityType();
$entity->getEntityTypeId();

// S’assurer que c’est un node.
if ($entity instanceof \Drupal\node\NodeInterface) {
}

Obtenir des informations via les méthodes de l’entité / Entity methods

Plusieurs méthodes communes sont disponibles pour récupérer des informations de l’objet, telles que l’identifiant, le bundle, l’ID de révision, etc. Voir la documentation EntityInterface pour plus de détails.

// Obtenir l’ID.
$entity->id();

// Obtenir le bundle.
$entity->bundle();

// Vérifier si l’entité est nouvelle.
$entity->isNew();

// Obtenir le label d’une entité. Remplacement de entity_label().
$entity->label();

// Obtenir l’objet URL d’une entité.
$entity->toUrl();

// Obtenir le chemin interne, alias s’il existe, d’une entité.
$entity->toUrl()->toString();

// Créer un duplicata qui peut être sauvegardé comme une nouvelle entité.
$duplicate = $entity->createDuplicate();

Création d’une entité

// Vous pouvez utiliser la méthode statique create() si vous connaissez la classe de l’entité.
$node = Node::create([
  'type' => 'article',
  'title' => 'Le titre du node',
]);

// Utiliser le gestionnaire de types d’entités (recommandé).
$node = \Drupal::entityTypeManager()->getStorage('node')->create(['type' => 'article', 'title' => 'Un autre node']);

// Ou utiliser le wrapper procédural (déconseillé).
$node = entity_create('node', [
  'title' => 'Mon node',
  'body' => 'Le contenu du corps. Cela fonctionne ainsi grâce à la nouvelle Entity Field API. Il sera assigné comme valeur du premier item de champ dans la langue par défaut.',
]);

Les réglages par défaut provenant de l’annotation du type de champ ne sont ajoutés que pour les clés de premier niveau manquantes ; une fusion profonde n’est pas effectuée.

Évitez d’utiliser la méthode statique Entity::create() dans un code orienté objet. Utilisez plutôt l’injection de dépendances pour injecter le gestionnaire de types d’entités et créer l’entité via $this->entityTypeManager->getStorage($entity_type)->create(). Cela garantit que le code est correctement découplé et testable par un module.

Pour une meilleure détection dans votre environnement de développement (IDE), vous pouvez aussi assigner une interface de stockage d’entités à une propriété. Par exemple, $this->nodeStorage = $this->entityTypeManager->getStorage('node'); Pour créer une entité, vous pouvez ensuite utiliser $this->nodeStorage->create().

Chargement

// Utiliser la méthode statique
$node = Node::load(1);

// Déconseillé. Chargement dynamique par type d’entité. entity_load() charge maintenant une seule entité, entity_load_multiple() correspond à l’ancienne entity_load() de 7.x.
$entity = entity_load($entity_type, $id);

// Utilisation du contrôleur de stockage (recommandé).
$entity = \Drupal::entityTypeManager()->getStorage($entity_type)->load(1);

// Charger plusieurs entités, aussi disponible via entity_load_multiple().
$entities = \Drupal::entityTypeManager()->getStorage($entity_type)->loadMultiple([1, 2, 3]);

// Charger des entités selon leurs propriétés.
$entities = \Drupal::entityTypeManager()->getStorage('node')->loadByProperties(['type' => 'article']);

Pour mettre à jour un objet, chargez-le puis sauvegardez-le avec les modifications.

Évitez d’utiliser la méthode statique Entity::load() dans un code orienté objet. Utilisez plutôt l’injection de dépendances pour injecter le gestionnaire de types d’entités et charger l’entité via $this->entityTypeManager->getStorage($entity_type)->load($entity_id). Cela garantit que le code est correctement découplé et testable par un module.

Sauvegarde d’une entité

// Pour sauvegarder une entité.
$entity->save();

Cela fonctionne pour les entités nouvelles comme existantes, l’entité elle-même suit si elle est nouvelle ou non. Par défaut, pour les entités de contenu, cela dépend de l’existence ou non d’un identifiant. Pour sauvegarder un objet avec un identifiant comme un nouvel objet (par exemple lors d’un import), vous pouvez appliquer le flag isNew.

// Le code suivant tentera d’insérer un nouveau node avec l’ID 5, cela échouera si ce node existe déjà.
$node->nid->value = 5;
$node->enforceIsNew(TRUE);
$node->save();

Suppression d’une entité

// Supprimer une seule entité.
$entity = \Drupal::entityTypeManager()->getStorage('node')->load(1);
$entity->delete();

// Supprimer plusieurs entités en même temps.
\Drupal::entityTypeManager()->getStorage($entity_type)->delete([$id1 => $entity1, $id2 => $entity2]);

Contrôle d’accès

La méthode access() peut être utilisée pour vérifier qui peut faire quoi avec une entité. Cette méthode supporte plusieurs opérations, les opérations standard étant view, update, delete et create, cette dernière étant un peu particulière, voir ci-dessous.

Les vérifications d’accès sont transmises au contrôleur d’accès. (TODO : ajouter un lien)

// Vérifier l’accès en lecture d’une entité.
// Par défaut, cela vérifie l’accès pour l’utilisateur connecté.
if ($entity->access('view')) {

}

// Vérifier si un utilisateur donné peut supprimer une entité.
if ($entity->access('delete', $account)) {

}

Lors de la vérification de l’accès à la création, l’entité n’existe généralement pas encore. Créer une entité juste pour vérifier si quelqu’un peut la créer est coûteux. Donc, l’accès à la création doit être vérifié directement via le contrôleur d’accès.

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

Si l’entité existe déjà, $entity->access('create') fonctionne également, ce qui redirige simplement vers la méthode createAccess(), tout comme les autres opérations redirigent la méthode access() vers le contrôleur d’accès.

REMARQUE. Certains guides en ligne utilisent \Drupal::entityManager(), mais dans la version 8.x cela est obsolète et sera supprimé en 9.x. Vous pouvez donc utiliser \Drupal::entityTypeManager() à la place de \Drupal::entityManager().