Site Building

Entities for Drupal 7, 8, 9, and 10

Nearly every major component that makes up a Drupal site is an entity of one type or another, e.g. users, nodes, and blocks are all types of entities. All entities can then be customized by adding fields to them. Understanding how Drupal's Entity system works is fundamental to understanding the similarities and differences between the main components that make up a Drupal site. You can alter existing entity types to make them work more efficiently for your site, and it's also possible to create your own entity types to encapsulate the behavior of specific data structures within your application.

From Overview: Relationships in Views:

In Drupal, entity is a general concept that represents a noun (person, place or thing). Out of the box, there are a number of different types of entities in Drupal, each meant to represent a specific type of data.

One type of entity is a user. A user entity contains information that is specific to people that visit our site, such as the user's email address and password. Within the concept that entities represent nouns, a user entity is a person.

Another entity type in Drupal is content (sometimes called a node) entity. Content entities contain data that is relevant for a something that is expected to be visited and consumed, such as a URL path, title, and body. Continuing with the concept that entities represent nouns, a content entity is a place. It has a URL and can be visited and it contains content that is meant to be consumed by a visitor.

Additionally, each content entity in Drupal has an owner. The owner (often referred to as the author) of a specific piece of content is a user entity. Most often the owner of some content is the user that created the content. Continuing with our analogy of a user representing a person and content representing a place, then it makes sense that a person would own a place. This concept of a user entity owning a content entity is a relationship. And that relationship is made practical in our site by the use of entity reference fields.

Drupal 8, 9, and 10
More information

In order to display values for referenced entities in views, you need to add a relationship. What is a relationship, how do they work, and what does it mean to require this relationship? What are some common use cases for adding a relationship to a view? By the end of this tutorial you should be able to:

  • Explain some common use cases for adding a relationship to a view.
  • Understand the concept of entity references and how those field values can be displayed in a view.

Example tasks

  • Understand what components of a Drupal site are entities
  • Understand the difference between configuration and content entities
  • Know when, and how to create custom entities


The Entity API is stable core API.

Drupalize.Me resources

More information

Overview of content entities and fields.

Drupal 8, 9, and 10
More information

Annotations are specially-formatted PHP docblock comments that are used for class discovery and metadata description. While it is technically possible to use annotations for other purposes, at the moment Drupal only uses them for the plugin system.

In this tutorial we'll look at:

  • What annotations are
  • The use case for annotations
  • How to figure out what you can put into an annotation

By the end of this tutorial you should understand how annotations are used in Drupal and how to write them in your own code.

More information

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.

Entities and fields are closely related and the boundaries between the two are often confused. It’s generally a good idea to learn both in order to properly use either one.

More information

Fields are the building blocks of Drupal's powerful content modeling system. The Field API allows for the development of custom field types to suit almost any data display and collection needs.

Drupal 7


Not sure where to start? Our guides provide useful learning tracks for all skill levels.

Navigate guides

External resources

  • Entity API (guide) (

    • Drupal Entity API documentation guide on
  • Entity API topic overview (

    • Technical documentation for the Entity API. Useful when you already understand the concept of entities but are unsure how to implement a feature or accomplish a specific task.
  • Example for Developers (

    • The examples project contains example modules with code that demonstrates creating both content and configuration entities.