Tipi di entità

• Drupal 7 - le entità erano oggetti generici stdClass.
• Drupal 8 - le entità ora sono oggetti con tipizzazione specifica, e ogni tipo di entità definisce la classe che sarà utilizzata per le istanze di quella entità.

Requisiti
Le classi delle entità devono essere collocate nello spazio dei nomi Entity del modulo che fornisce il tipo di entità, ad esempio \Drupal\[module_name]\Entity. Questo significa che i file PHP della classe dell’entità si trovano nella cartella src/Entity del modulo.

Il docblock per la classe deve contenere l’annotazione EntityType, che definisce i metadati per le entità di quel tipo. Questi includono elementi come l’etichetta del tipo di entità, i controller, le tabelle, ecc. Per un elenco documentato di tutte le proprietà di metadati disponibili, vedi la classe \Drupal\Core\Entity\Annotation\EntityType.

Naming

I nomi dei tipi di entità devono avere il prefisso con il nome del modulo, se il tipo di entità e il nome del modulo non coincidono. Il prefisso non è richiesto per la classe stessa, dato che essa si trova nello spazio dei nomi del modulo che la definisce, a condizione che sia già di per sé sufficientemente descrittiva. Ad esempio, il tipo di entità per i termini di tassonomia si chiama taxonomy_term, e il nome della classe è Drupal\taxonomy\Entity\Term.

Interfacce

Drupal 8 raccomanda di usare type hinting e metodi con interfacce invece che con classi. Ad esempio, lo storage generale delle entità utilizza il type hint EntityInterface, come in hook_entity_insert(EntityInterface $entity), mentre lo storage specifico per i nodi usa NodeInterface, come in hook_node_insert(NodeInterface $node).

I campi / le proprietà delle entità spesso hanno nomi molto brevi, orientati all’archiviazione e poco informativi. Inoltre, le entità di contenuto non usano proprietà dedicate per i loro campi (inclusi i campi di base, come il titolo del nodo).

Pertanto, l’approccio raccomandato è fornire un’interfaccia con nomi di metodi documentati. Occorre seguire alcune regole:

• I metodi in genere hanno prefissi get/set/is o simili: getSomething(), setSomething($value), isSomething().
• Aggiungere solo metodi per le cose che altro codice deve modificare. Ad esempio, la data dell’ultima modifica dei nodi ($node->updated) non dovrebbe essere modificata, quindi esiste il metodo $node->getChangedTime(), ma non un $node->setChangedTime().
• Usare nomi auto-esplicativi per i metodi, ad esempio il metodo per accedere a $node->status si chiama $node->isPublished().

Comprensibilità

Per sapere quali tipi di entità fornisce un modulo, consulta le classi nello spazio dei nomi Entity di quel modulo, che hanno l’annotazione @EntityType, contenente anche l’id nel relativo attributo.

Quando cerchi di capire dove è definito un tipo di entità, la prima cosa da controllare è il prefisso del tipo. Se il modulo non rispetta questa convenzione, puoi cercare id = "$type". Se invece conosci la classe o l’interfaccia, lo spazio dei nomi indica da dove proviene.

Esempio

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;

/**
 * Defines the node entity class.
 *
 * @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 {
  // ...
}

Per avere una visione completa delle entità in Drupal 8, possiamo considerare il seguente diagramma. Esso rappresenta le classi delle entità. Per visualizzarlo apri in una nuova scheda: