Creating Custom Entity Types
How to decide on a custom entity and design its storage, forms, permissions, and Views integration.
A custom entity is justified when a domain object needs its own identity, lifecycle, access rules, storage, and query behavior. It is not merely a way to group fields.
Choose content or configuration
Content entities hold operational records and fieldable data. Configuration entities describe deployable site behavior. Pick the model based on lifecycle and ownership, not which annotation example is shorter.
Define handlers deliberately
Entity type metadata wires storage, access, list builders, forms, routes, and Views data. Start with the minimum set, but design keys, indexes, and ownership before production data exists.
Plan updates from day one
Entity schema changes require update paths. Test installation and updates separately, define permissions around operations, and ensure Views queries respect access where required.
Key Takeaways
- Create an entity only for a real domain lifecycle.
- Design access and storage before UI.
- Provide update paths for schema evolution.