Drupal 11 Expands Attribute-Based Hooks and Moves Away From .module Files

Drupal 11 introduces a new method for implementing hooks, replacing procedural functions in .module files with attribute-based methods defined inside object-oriented classes. The system uses PHP attributes such as #[Hook], allowing developers to register hook implementations within autowired classes located in src/Hook/. The change marks a shift away from a pattern that has been part of Drupal since its early versions and is being implemented progressively across Drupal 11 releases.

The transition began with Drupal 11.1, which introduced the #[Hook] attribute. Drupal 11.2 expanded the system by adding support for preprocess hooks and introducing an order parameter to control execution sequence. Drupal 11.3 extended compatibility to themes, completing the functional replacement of procedural hooks. These updates collectively deprecate traditional hook implementations, with removal planned for a future major version. 

Under the new approach, hooks are implemented as methods within classes that use dependency injection. Services such as messaging and user context can be injected through constructors, eliminating the need for static calls like \Drupal::service(). This change improves code readability and aligns hook implementations with the rest of Drupal’s service-based architecture.

The update also introduces a more structured way to organise code. Instead of consolidating multiple hook implementations in a single .module file, developers can group related functionality into separate classes based on concern. This allows clearer separation of responsibilities and reduces the complexity associated with large procedural files.

Testing practices are expected to improve as a result of the change. Procedural hooks often required complex setups for testing due to reliance on global state. In contrast, class-based hooks with injected dependencies can be tested using standard unit testing methods, consistent with modern PHP development workflows.

The attribute system also provides explicit control over hook execution order. Developers can define precedence using parameters such as Order::First or specify relative ordering through constructs like OrderBefore and OrderAfter. This replaces earlier mechanisms such as hook_module_implements_alter with a more structured alternative.

Procedural hooks continue to function in Drupal 11, allowing developers to maintain existing implementations. For projects requiring compatibility with earlier versions, approaches such as #[LegacyHook] can be used to bridge procedural and object-oriented systems. Migration can therefore be performed incrementally rather than as a single refactoring effort.

The introduction of attribute-based hooks represents the final step in Drupal’s long transition toward modern PHP architecture. By removing reliance on procedural .module files, the platform aligns hook implementation with established patterns used across services, plugins, and other subsystems.