Drupal's Entity API offers a handy framework for defining, managing, and interacting with data objects (entities) in a consistent and extensible manner across the system.
In this course you’ll learn the foundational concepts and terminology of the Entity API, including the differences between configuration and content entities, and how to create, read, update, and delete entity data. We’ll cover practical examples of creating custom entities, implementing validation logic, and using hooks to interact with entity lifecycle operations. You will also learn how to use the EntityQuery service to find and manipulate subsets of data, and how to implement access control for entities. Additionally, the course will delve into the use of annotations and handlers, and how to leverage the Entity API for better performance and extensibility in your Drupal modules.
Entity API Overview
FreeWhen learning Drupal development, it won't be long before you encounter the word "entity" and the Entity API. But what are entities in Drupal? How can you use them to build your site? When should you use the Entity API?
This tutorial will explain Drupal's Entity system from a high level. We'll look at:
- The main problems the Entity system solves
- Key terms you should know
- Key concepts we'll explore as we dive into Drupal's Entity API
By the end of this tutorial, you should be able to explain the problems that the Entity API solves, and when you should use it in your own code.
Entities are the core data structures that provide the building blocks for nearly everything on a Drupal site. Whether an entity provides configuration or content, it plays a key role in how Drupal stores and manages data. Entities provide a consistent, developer-friendly, and Drupal-aware abstraction to data stored in the database.
In this tutorial, we will:
- Explore how different entity types relate.
- Compare configuration and content entities to understand the purpose and implementation of both.
- Review how (at a high level) an entity type is defined.
By the end of this tutorial, you'll understand the relationship between configuration and content entities and be able to identify the parts of code that define a custom entity type.
The Drupal Entity API makes it easy to define new custom content entity types. And in most cases, whenever you want to store custom content in Drupal, you should use the Entity API instead of making CRUD queries directly to the database. This ensures your code is more consistent and allows you to take advantage of all the features of the Entity API, like access control, Views module integration, and automatic JSON:API support. As well as making it easier for others to extend your custom content by ensuring all the proper hooks and lifecycle events get invoked when new content items get created, updated, and deleted.
In this tutorial, we'll:
- Walk through the process of creating a custom content entity
By the end of this tutorial, you'll be able to create your own custom content entity contained in a module.
This reference document contains a detailed list of available properties for the #[ContentEntityType] attribute in Drupal 11. The current documentation in the Drupal 11 code base lists, but doesn't always describe, each of these properties. Or, in many cases, the property is an associative array where the nested key/value pairs are important, but what they should be isn't well documented. So we've created this helpful reference. Most of the properties listed here will also apply to #[ConfigEntityType] attributes. These properties define the metadata and behavior of custom entity types.
In this tutorial, we'll:
- Look at an example of how to use
#[ContentEntityType]attributes. - Provide a comprehensive list of available properties and a description of each.
- Show detailed examples of using nested array properties like
handlers[].
By the end of this tutorial, you should be able to understand how and when to use any of the properties of a #[ContentEntityType] attribute in order to modify the behavior of a custom entity type.
Code generators are great productivity boosters that allow generating scaffolds for common development tasks in Drupal. One of the most common use cases for generators is scaffolding the code required for a custom entity type. Custom entities require many files and complicated annotations in order to function properly. There is a lot of boilerplate code that is more-or-less the same for every entity type. Creating all the files is repetitive, time-consuming, and prone to human error. Generators can help automate this task and make creating your own custom entity types quicker.
In this tutorial we'll:
- Learn how to generate the code for a custom entity with Drush
- Learn about the options that generators provide for custom entities
By the end of this tutorial you should know how to generate custom entities with Drush.
Entity CRUD (Create, Read, Update, and Delete) operations are handled via the EntityTypeManager service.
In this tutorial we'll:
- Learn how to use the
EntityTypeManagerservice to perform basic CRUD operations with examples you can copy/paste - Access both property and field values of an entity
- Update entities by setting new field values and then saving the object
By the end of this tutorial, you'll be able to understand Entity CRUD operations and be well on your way to becoming comfortable with accessing and manipulating entity values in code.
Often when building a site in Drupal you'll find yourself wanting to display a list of nodes, or find entities created by a particular author, or locate some content based on a particular set of criteria. Rather than querying the database directly, Drupal provides a helper class, EntityQuery, to make things a bit easier. The EntityQuery class will probably look very familiar to you if you're familiar with the Database API, or the EntityFieldQuery class in Drupal 7.
In this tutorial we'll:
- Go through several examples of using
EntityQueryto find subsets of content. - Demonstrate how to iterate over the results of an
EntityQueryquery.
By the end of this tutorial, you should understand how to use entity queries to create custom sets of data from entities.
Drupal's Entity system provides several hooks that allow custom code to interact with various parts of the entity life cycle.
In this tutorial we'll:
- Examine the available hooks
- Learn how to make use of them to act on several different types of operations on individual entities
By the end if this tutorial you should have a better understanding of the hooks available to developers who want to respond to entity lifecycle operations and how to use them to customize the way specific entity types work.
On occasion, you may need to modify the behavior of entity types defined by another module. Thankfully, Drupal includes several alter hooks that can be used to override the behavior of another entity.
In this tutorial, we will:
- Walk through the common Entity API hooks
- Look at example implementations of each
- And discuss the use cases for each
By the end of this tutorial, you will have a better understanding of how to override the default behavior of an entity type provided by Drupal core (or another contributed module) within your custom code.
Bundle classes are a feature of the Drupal Entity API that let you attach PHP classes to individual bundles (for example, content types) so you can keep site-specific business logic close to the data it acts on. Bundle classes are a powerful way to encapsulate site-specific business logic and bridge user-configured fields and PHP logic based on those fields. In this tutorial, you will build a reusable bundle base class that adds a generic share behavior for all node types on a site and then extend it for a specific node type.
In this tutorial, we will:
- Explore a real-world problem that bundle classes can help you solve.
- Create a bundle base class for common share features shared across multiple node types.
- Implement a node-type-specific class that extends the base class with behavior tailored to the underlying content type.
By the end of this tutorial, you'll be able to use bundle classes to encapsulate per-bundle logic, assume the presence of UI-configured fields when appropriate, and register those classes so Drupal uses them at runtime.
Drupal includes the Symfony Validator component, and provides an Entity Validation API to assist in validating the values of fields on an entity. By using the Entity Validation API you can ensure that you're validation logic is applied to Entity CRUD operations regardless of how they are triggered. Whether editing an Entity via a Form API form, or creating a new Entity via the REST API, the same validation code will be used.
Using the Entity Validation API in order to validate the value of a field on an entity requires:
- Defining (or choosing) a constraint plugin
- Defining (or choosing) a validation plugin
- Adding the constraint to the field definition
In this tutorial, we'll look at how this Validation API works and how it can be used in custom code to ensure our entities have properly constructed values. We'll look at how this validation works in Drupal core and how we can add our own additional constraints. We'll also see how to work with the error messages returned from the validator when our entity doesn't pass validation.
One of Drupal's strengths is its fine-grained permission and access system. The Entity API enables this by providing interfaces that let us define access control rules.
In this tutorial we'll:
- Look at how access control is handled, using Drupal core as an example.
- Demonstrate how to implement access control in a custom module.
- Learn about the hooks that allow developers to modify access control for entities provided by another module.
By the end of this tutorial you should have a better understanding of the entity access control system and how to work with it.
The Typed Data API in Drupal helps add additional functionality to PHP's built-in data types, making working with data in Drupal much more predictable. It allows code to make intelligent guesses about the type of data that a field on an entity contains. For example, differentiating between a string of text and a string of text that represents a URL.
In this tutorial, we'll:
- Look at the 3 main types of typed data in Drupal: primitives, complex data, and lists.
- See how different data types and definitions are defined, and show how to define your own data type.
- Look at the interfaces provided by each data type to see some of the benefits of adding this abstraction layer.
By the end of this tutorial, you should have a better understanding of what the Typed Data API is, where you'll most likely encounter it, and how to use it in your code.
