Entity Api

<!-- generated: do not edit — source: knowledge/atoms/drupal/entity-api/ --> <!-- schema: atomVersion=3 skillVersion=2 graphVersion=1 --> <!-- compile: @php-skills/compiler v1.0.0 (deterministic build) -->

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

Anti-pattern	Why it fails	Do instead
Using a content entity for deployable settings	Content entities are data in the database and are not exported by config sync, so the settings never travel between environments.	Model deployable settings as a config entity or simple configuration so config sync carries them.
Instantiating entities with new instead of storage	Directly instantiated entities miss default values, ids, and storage wiring, so saving them corrupts data.	Create entities via $storage->create([...]) and persist with ->save().
Writing SQL against the entity base table	Raw SQL bypasses hooks, access control, translation, and cache invalidation, producing stale caches and security holes.	Use the entity query and storage APIs through the injected entity type manager instead.

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

<!-- graph-fragment: graph/fragments/drupal/entity-api.yaml -->