As of Drupal 11.1.0, core has support for defining custom entity types (both content and configuration) using PHP attributes instead of annotations. And now, all our Entity API tutorials have been updated to reflect this change.
We previously performed extensive updates that rewrote all our tutorials that made use of annotations for Drupal plugins. See Keeping up with Drupal’s Evolving Plugin API: Updating Tutorials for PHP Attributes for more about those changes. But at that time, core did not yet support the use of PHP attributes for content or configuration entity type definitions. It does now, though!
What changed
At a high level, the metadata for custom content and configuration types is declared using PHP attributes instead of annotations. In your code, you’ll now author a #[ContentEntityType] or a #[ConfigEntityType] attribute, instead of a @ContentEntityType or @ConfigEntityType annotation, to provide details like the entity type’s id and label, and to configure handlers[], access control, and routing.
Seven tutorials in our Entity API course were rewritten and polished, and there’s a brand-new properties reference that dives deep into all the available #[ContentEntityType] attributes’ properties, what they do, and when to use them. In our research, we found that figuring this out still required quite a bit of code spelunking, so we wanted to surface as much of the information we found as we can. This new tutorial includes usage snippets that you can copy/paste, walking you through default values, types, and common pitfalls for identification keys, handlers, routing metadata, forms, Views integration, cache contexts, and nested arrays, such as links[] and handlers[].
We also took this opportunity to refresh the Entity API Implementation Basics tutorial based on feedback from members that said it was missing some critical information and was confusing. It now explains why you’d created a custom entity type in the first place, the differences between configuration and content entities, and the previous base-field code sample has been trimmed to its essentials to keep the focus on concepts. We also introduced bundle classes (and have another tutorial about these in the works), and updated the prerequisite of PHP attributes so the terminology stays consistent.
Should I use PHP attributes or annotations?
While annotations are still supported via a backwards compatibility layer, if you’re starting a new project, you should now use PHP attributes. We expect support for annotations will be dropped sometime in the future. Though not until Drupal 12, if not later.
The caveat to this is if you need your module to be compatible with versions of Drupal core before 11.1.0. In which case, you’ll still need to use annotations to define your custom entity types. Luckily, all the key/value pairs are still the same; it’s really just the syntax that’s different. So things like the new ContentEntityType Attribute: Properties Reference will still be useful.
Enjoy the updates, and please let us know if you have any questions about the move from annotations to PHP attributes.
