Типы Entity

09/05/2020, by maria

Drupal 7 - Entity были общими объектами stdClass.

Drupal 8 - Entity теперь являются объектами со специфической типизацией, причем каждый тип сущности определяет класс, который будет использоваться для экземпляров данной сущности.

Требования
Классы Entity должны быть помещены в подпространство имен Entity модуля, который предоставляет тип сущности, например \Drupal\[module_name]\Entity. Это означает, что файлы PHP класса Entity можно найти в каталоге модуля src/Entity.

Докблок для класса должен содержать аннотацию EntityType, которая определяет метаданные для Entity этого типа. К ним относятся такие вещи, как метка типа сущности, контроллеры, таблицы и т. д. За документированным списком всех доступных свойств метаданных обратитесь к классу \Drupal\Core\Entity\Annotation\EntityType.

Naming

Имена типов объектов должны иметь префикс с именем модуля, если тип объекта и имя модуля не совпадают. Префикс самого класса сущностного типа не требуется, так как он находится в пространстве имен определяющего модуля, при условии, что он сам по себе достаточно осмыслен. Например, тип сущности для терминов таксономии называется taxonomy_term, а имя класса - Drupal\taxonomy\Entity\Term.

Интерфейсы

Drupal 8 рекомендует вводить функции подсказок и методы с интерфейсами вместо классов. Например, хранилище общих Entity перехватывает подсказку типа с EntityInterface, как в hook_entity_insert (EntityInterface $entity), а специфичное для узла хранилище перехватывает подсказку типа с NodeInterface, как в hook_node_insert (NodeInterface $node).

Поля / свойства Entity часто бывают очень короткими, ориентированными на хранение и не очень информативными. Кроме того, сущности контента вообще не используют определенные свойства для своих полей (включая базовые поля, такие как заголовок узла).

Поэтому рекомендуемый подход заключается в предоставлении интерфейса с документированными именами методов. При этом следует соблюдать несколько правил:

Методы обычно имеют префикс get/set/is или аналогичный: getSomething(), setSomething($value), isSomething().
Добавляйте только методы для вещей, которые другой код должен изменить. Дата последнего изменения узлов ($node->updated) не должна изменяться, поэтому существует метод $node->getChangedTime(), но нет метода $node->setChangedTime().
Используйте самоописательные имена методов, например, метод для доступа к $node->status называется $node->isPublished().

Понятность

Чтобы узнать, какие типы Entity предоставляет модуль, обратитесь к классам в подпространстве имен Entity этого модуля, которые имеют аннотацию @EntityType, которая также содержит имя в ключе аннотации id.

При попытке найти, где определен данный тип Entity, первое, что нужно искать, - это префикс типа сущности. Если модуль не соблюдает это соглашение об именах, его можно найти, выполнив поиск id = "$type". Если вместо типа сущности известен класс или интерфейс, то пространство имен указывает, откуда оно поступает.

Пример

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 {
  // ...
}

Чтобы получить полную картину сущностей в Drupal 8, мы можем рассмотреть следующую диаграмму. Это представляет классы сущностей. Для просмотра открыть в новой вкладке:

classDrupal_Entities

Дополнительные типы блоков (EBT) — новый опыт конструктора страниц❗

❗Дополнительные типы параграфов (EPT) — новый опыт работы с параграфами

Menu

Naming

Интерфейсы

Понятность

Пример