Drupal Entity API

When to use

• The user needs a Drupal configuration entity to store admin-defined settings that ship as exportable config.
• The user wants to define a custom Drupal content entity type to store repeatable, fieldable data.
• The user wants to load, query, save, or delete Drupal entities through the entity type manager and storage.

When NOT to use

• Do not create and query a raw custom database table when a content entity would model the same fieldable data.
• Do not define an entity type for one flat setting; use simple configuration (config.factory) instead.

Core guidance

• Choose content entities for data, config entities for settings — Use a content entity when instances are user-created data (many rows, fieldable); use a config entity when instances are site-builder settings that must deploy through config sync.

Quick recipe

1. Create the entity class under src/Entity/ extending ContentEntityBase with a #[ContentEntityType] attribute defining id, base_table, entity_keys, and handlers. (verify: The entity type appears in drush entity:types.)
2. Implement baseFieldDefinitions() returning each field via BaseFieldDefinition::create(...), then install the entity schema. (verify: The base table and its columns exist after install.)
3. Use $storage->create([...])->save() to write and $storage->getQuery()->accessCheck(TRUE)->execute() to read. (verify: Created entities are found by the access-checked query.)

Best practices

• Define the entity type via a #[ContentEntityType] attribute (or @ContentEntityType annotation) with id, base_table, entity_keys, and handlers for list builder, form, and access
• Declare fields common to every bundle in baseFieldDefinitions() using BaseFieldDefinition::create(...); reserve configurable fields for per-bundle needs added through the UI or config
• On every entity query call ->accessCheck(TRUE) for user-facing listings and ->accessCheck(FALSE) only for deliberate system queries; never leave it unset
• Load and query entities via $entityTypeManager->getStorage('my_entity'), using an injected EntityTypeManagerInterface, not by writing SQL against the base table

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Config entity fails validation without a schema — A config entity throws schema errors or fails config export when its config/schema/*.schema.yml is missing. Fix: Add a config/schema/MODULE.schema.yml describing every property of the config entity type.
2. Entity query throws without accessCheck — An entity query without accessCheck() throws a QueryException on Drupal 10+. Fix: Call ->accessCheck(TRUE) or an explicit ->accessCheck(FALSE) on every entity query.
3. Adding a base field on an installed entity does nothing — Adding a new base field to an already-installed entity type has no effect until the schema is updated. Fix: Install the field in a hook_update_N() via \Drupal::entityDefinitionUpdateManager()->installFieldStorageDefinition(...).

Version notes

• PHP attribute entity definitions arrived in Drupal 10.2 (PHP >=8.1) — From Drupal 10.2 entity types can be declared with PHP 8 attributes (#[ContentEntityType]); earlier versions require the doctrine-style @ContentEntityType annotation.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/drupal/entity-api.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: drupal/module-development