Custom Configuration Entities are a core architectural concept in Drupal that allow developers to model structured configuration as first class objects. They sit at the intersection of the Configuration Management Initiative (CMI) and the Entity API.
Starting with Drupal 8, Drupal introduced configuration entities to represent complex configuration that requires identifiers, labels, dependencies, and lifecycle management. Examples include Views, content types, image styles, and roles.
This article is part of Level 1 – Core Architecture in the 187-article series. The goal is to understand configuration entities as an architectural pattern, not just how to generate one.
Why Configuration Entities Belong in Core Architecture
Configuration entities define how a site is structured, not what content it stores.
Drupal core uses configuration entities to:
- Represent structured configuration
- Enable CRUD operations on configuration
- Track configuration dependencies
- Support deterministic deployments
- Integrate configuration with the Entity API
Without configuration entities, many core systems would rely on fragile flat configuration.
Configuration Entities vs Content Entities
Drupal has two major entity types.
Content Entities
- Store user generated data
- Stored in database tables
- Revisionable and translatable
- Example: nodes, users, taxonomy terms
Configuration Entities
- Store site structure and behavior
- Stored as YAML via CMI
- Not revisioned by default
- Example: views, image styles, roles
This separation is fundamental to Drupal architecture.
Configuration Entities vs Simple Configuration
Drupal also supports simple configuration.
Simple Configuration
- Key value based
- Single YAML file
- No IDs or labels
- Example: system.site
Configuration Entities
- Have IDs and labels
- Support multiple instances
- Support dependency tracking
- Support CRUD
If configuration needs structure and lifecycle, it should be a configuration entity.
Anatomy of a Configuration Entity
A configuration entity consists of:
- An entity type definition
- A PHP class
- Configuration schema
- Optional UI forms
Each part plays a role in integration with core systems.
Defining a Custom Configuration Entity
Configuration entities are defined using annotations.
/**
* @ConfigEntityType(
* id = "example_type",
* label = @Translation("Example Type"),
* handlers = {
* "list_builder" = "Drupal\\my_module\\ExampleListBuilder",
* "form" = {
* "add" = "Drupal\\my_module\\Form\\ExampleAddForm",
* "edit" = "Drupal\\my_module\\Form\\ExampleEditForm",
* "delete" = "Drupal\\my_module\\Form\\ExampleDeleteForm"
* }
* },
* config_prefix = "example_type",
* admin_permission = "administer example type",
* entity_keys = {
* "id" = "id",
* "label" = "label"
* },
* links = {
* "collection" = "/admin/structure/example-type",
* "add-form" = "/admin/structure/example-type/add",
* "edit-form" = "/admin/structure/example-type/{example_type}",
* "delete-form" = "/admin/structure/example-type/{example_type}/delete"
* }
* )
*/
class ExampleType extends ConfigEntityBase {
}
This annotation defines how Drupal discovers and manages the entity.
Key Annotation Properties
Important properties include:
- id: Machine name of the entity type
- label: Human readable label
- config_prefix: Prefix for YAML files
- admin_permission: Required permission
- entity_keys: ID and label mapping
- handlers: UI and storage handlers
Misconfigured annotations lead to broken discovery.
Configuration Storage
Each configuration entity instance is stored as a YAML file.
Example:
- my_module.example_type.example_one.yml
This file participates fully in CMI exports and imports.
Configuration Schema
Schema defines the structure of configuration data.
my_module.example_type.*:
type: config_entity
label: 'Example Type'
mapping:
id:
type: string
label:
type: label
Schema is required for:
- Validation
- Translations
- UI consistency
Dependency Tracking
Configuration entities declare dependencies automatically.
Dependencies include:
- Module dependencies
- Theme dependencies
- Other configuration entities
Dependencies ensure safe configuration imports.
CRUD Operations
Configuration entities support full CRUD via the Entity API.
Example:
$storage = \Drupal::entityTypeManager()->getStorage('example_type');
$entity = $storage->load('example_one');
Operations are reflected in exported configuration.
UI Integration
Configuration entities integrate with:
- Administrative listings
- Add and edit forms
- Permissions system
- Routing system
This enables full UI management without custom controllers.
Configuration Entities and Caching
Configuration entities are cached aggressively.
Important points:
- Loaded from cache when possible
- Cache invalidated on config import
- Safe to use in services
They are not request specific.
Common Mistakes
- Using content entities for configuration
- Using simple config for structured data
- Missing schema definitions
- Hard coding configuration values
- Storing secrets in config entities
Choosing the wrong type causes long term maintenance issues.
Drupal 10 and 11 Best Practices
- Use configuration entities for site structure
- Always define schema
- Keep entities small and focused
- Reuse core patterns
- Treat config entities as code
How Custom Configuration Entities Fit with Other Core Systems
They integrate with:
- CMI
- Entity API
- Permissions system
- Routing system
- Plugin system
Many plugin definitions are backed by configuration entities.
Acquia Exam Notes and Cheat Sheet
Key points to remember:
- Config entities are stored as YAML
- They are part of CMI
- They use the Entity API
- They are not content
- They track dependencies
Common exam traps:
- Confusing config entities with content entities
- Forgetting schema definitions
- Assuming config entities are revisionable
- Editing YAML directly in production
Quick decision guide:
- Site structure with multiple instances: config entity
- Simple settings: simple config
- User data: content entity
If the question mentions Views, image styles, or roles, the answer is configuration entities.
Summary
Custom configuration entities are a core architectural building block that allows Drupal to model structured configuration as entities. They combine the strengths of CMI and the Entity API to provide scalable, deployable, and maintainable site architecture. Understanding them is essential for Drupal 10 and 11 development and for Acquia certification success.
This article prepares you for advanced topics such as config entity storage internals, schema validation, and config driven plugin systems.