Much like previous versions of Drupal, version 8 of the CMS revolves around the concept of Entities. These are objects that have an ID, Language, Type, and Storage. Some optional properties are URLs, Bundles, and labels. They can be viewed, loaded, created, saved, and deleted, as well as have access permissions set for them. Most things in Drupal are entities, such as Users, Nodes, or Blocks. Many of the core services provide functionality for interacting with entities, and a great deal of caching functionality serves to make entities perform better.
Most entities exposed to the user will also be fieldable, which means any amount of fields can be attached, transversed, and modified either by code or in the admin GUI.
While all entities in Drupal inherit basic functionality from the core entity class, they tend to fall into two different categories: configuration entities and content entities. Configuration entities provide storage for variables that inform the structure and functionality of Drupal sites - how the site serves content. These are things like Languages, Filters, Database Logs and the like. Content entities provide storage for what the site serves, as dictated by what entity they are and how configuration entities modify their behavior.
While no means a comprehensive list, these are many of the core configuration entities that are important to the functioning of a Drupal site.
Dates & Times
Display Modes - Display modes will be covered in depth later, but suffice to say there are View and Edit (Form) modes for most entities.
Content Configurations - Almost all Content Entities have a Configuration Entities to go alongside them to configure how they function.
Field Configurations - When fields get attached to an entity, they'll have a Configuration Entity as well.
System - This is the general configuration for the site.
When You Need a Custom Entity
If most content on a site is just a collection of fields, why would you need any other entity than Content entities (nodes)? The answer is that not all entities need to be user-editable, revisionable, and translatable - core things like Users or new features such as tickets in an Events system and global configuration in a custom admin menu.
Here’s a handy checklist to use:
Fields are not editable by the user and instead are manipulated by custom code
Revisions are not needed
Translation is not needed
- Custom functions control the creation, editing, and saving of the data
Building a Custom Entity
Custom entities in Drupal 8 are a bit clearer than in Drupal 7 since they always contain two things in a single file:
A class annotation that extends any of the classes that extend \Drupal\Component\Annotation\AnnotationInterface.
A class that extends the base \Drupal\Core\Entity\EntityInterface
This means that the class documentation has an @EntityTypeOrSomeSuch annotation declaring configuration about the custom entity, and implements the functions described in the Drupal EntityInterface PHP Interface file. Entities reside in the my_module\Entity namespace - the directory equivalent of my_module/src/Entity/.
Here’s an example entity class for creating Global Admin Configs stored as field values:
This entity exists as a content entity with fields and full sets of storage, but relies on a newly created hook, hook_admin_config_BUNDLE, to create the field storage, config, form, and view displays. This custom entity would be useful in a case where we’d want to programmatically provide fields for bundle content implementations, like in the case of a custom admin menu with custom fields for storing globals such as images and text.