Lavorare con l’Entity API

Copre i metodi API generali delle entità.

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

API più specifici saranno trattati nei capitoli dedicati.

Verifica

// Assicurarsi che un oggetto sia un’entità.
if ($entity instanceof \Drupal\Core\Entity\EntityInterface) {
}

// Assicurarsi che sia una content entity.
if ($entity instanceof \Drupal\Core\Entity\ContentEntityInterface) {
}
// oppure:
if ($entity->getEntityType()->getGroup() == 'content') {
}

// Ottenere il tipo di entità o il suo ID.
$entity->getEntityType();
$entity->getEntityTypeId();

// Assicurarsi che sia un nodo.
if ($entity instanceof \Drupal\node\NodeInterface) {
}

Ottenere informazioni da un’entità / Metodi delle entità

Sono disponibili diversi metodi comuni per ottenere informazioni da un oggetto, come l’ID, il bundle, l’ID della revisione e così via. Vedi la documentazione di EntityInterface per i dettagli.

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

// Ottenere il bundle.
$entity->bundle();

// Verificare se l’entità è nuova.
$entity->isNew();

// Ottenere l’etichetta di un’entità. Sostituisce entity_label().
$entity->label();

// Ottenere l’oggetto URL di un’entità.
$entity->toUrl();

// Ottenere il percorso interno, alias incluso se esiste, di un’entità.
$entity->toUrl()->toString();

// Creare un duplicato che può essere salvato come nuova entità.
$duplicate = $entity->createDuplicate();

Creazione di un’entità

// Puoi usare il metodo statico create() se conosci la classe dell’entità.
$node = Node::create([
  'type' => 'article',
  'title' => 'The node title',
]);

// Usa l’entity type manager (consigliato).
$node = \Drupal::entityTypeManager()->getStorage('node')->create(['type' => 'article', 'title' => 'Another node']);

// Oppure usa il wrapper procedurale (deprecato).
$node = entity_create('node', [
  'title' => 'My node',
  'body' => 'The body content. Questo funziona grazie alla nuova Entity Field
          API. Verrà assegnato come valore del primo elemento del campo nella
          lingua predefinita.',
]);

Le impostazioni predefinite dall’annotazione del tipo di campo vengono aggiunte solo per le chiavi mancanti di primo livello; non viene eseguita una fusione profonda.

Evita di usare il metodo statico Entity::create() nel codice orientato agli oggetti. Usa invece l’iniezione delle dipendenze per iniettare l’entity type manager e crea l’entità tramite $this->entityTypeManager->getStorage($entity_type)->create(). Questo garantisce che il codice sia correttamente separato e testabile.

Per il rilevamento in IDE, puoi anche assegnare lo storage dell’entità a una proprietà. Ad esempio: $this->nodeStorage = $this->entityTypeManager->getStorage('node'); Per creare un’entità puoi usare $this->nodeStorage->create().

Caricamento

// Usa il metodo statico.
$node = Node::load(1);

// Deprecato. entity_load() ora carica una singola entità; la versione 7.x è stata rinominata in entity_load_multiple().
$entity = entity_load($entity_type, $id);

// Usando lo storage controller (consigliato).
$entity = \Drupal::entityTypeManager()->getStorage($entity_type)->load(1);

// Caricare più entità, esiste anche come entity_load_multiple().
$entities = \Drupal::entityTypeManager()->getStorage($entity_type)->loadMultiple([1, 2, 3]);

// Caricare entità in base ai loro valori di proprietà.
$entities = \Drupal::entityTypeManager()->getStorage('node')->loadByProperties(['type' => 'article']);

Per aggiornare un oggetto, caricalo e poi salvalo con le modifiche.

Evita di usare il metodo statico Entity::load() nel codice orientato agli oggetti. Usa invece l’iniezione delle dipendenze per iniettare l’entity type manager e caricare l’entità con $this->entityTypeManager->getStorage($entity_type)->load($entity_id). Questo garantisce che il codice sia separato e testabile.

Salvataggio di un’entità

// Per salvare un’entità.
$entity->save();

Funziona sia per nuove che per entità esistenti, l’entità stessa tiene traccia se è nuova o meno. Per impostazione predefinita, per le content entity questo dipende dal fatto che abbiano un ID. Per salvare un oggetto con un ID come nuova entità (ad esempio importando dati), si può usare il flag isNew.

// Il seguente tenterà di inserire un nuovo nodo con ID 5, fallirà se esiste già.
$node->nid->value = 5;
$node->enforceIsNew(TRUE);
$node->save();

Eliminazione di un’entità

// Eliminare una singola entità.
$entity = \Drupal::entityTypeManager()->getStorage('node')->load(1);
$entity->delete();

// Eliminare più entità contemporaneamente.
\Drupal::entityTypeManager()->getStorage($entity_type)->delete([$id1 => $entity1, $id2 => $entity2]);

Controllo accessi

Il metodo access() può essere usato per controllare chi può fare cosa con un’entità. Supporta varie operazioni: visualizzare, aggiornare, eliminare e creare. La creazione è un caso particolare (vedi sotto).

I controlli di accesso sono passati all’access controller. (TODO: Aggiungere link)

// Controllare l’accesso in visualizzazione di un’entità.
// Per impostazione predefinita controlla l’utente attualmente loggato.
if ($entity->access('view')) {

}

// Controllare se un dato utente può eliminare un’entità.
if ($entity->access('delete', $account)) {

}

Quando si verifica l’accesso in creazione, di solito non esiste ancora un’entità. Crearne una solo per controllare l’accesso sarebbe costoso. Perciò l’accesso in creazione deve essere verificato direttamente sull’access controller.

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

Se l’entità esiste già, $entity->access('create') funziona comunque, reindirizzando al metodo createAccess(), così come le altre operazioni reindirizzano al metodo access() sull’access controller.

NOTA. In alcune guide online si usa \Drupal::entityManager(), ma in 8.x è deprecato e sarà rimosso in 9.x. Usa quindi \Drupal::entityTypeManager() invece di \Drupal::entityManager().