Hook ordering across OOP, procedural and with extra types i.e replace hook_module_implements_alter

Problem/Motivation

The ordering of listeners defined by new Hook attributes does not have a modern solution.

We wqnt to replace hook_module_implements_alter in it's current form to handle all current ordering scenarios.

• set a hook first
• set a hook last
• order a hook before another module
• order a hook after another module
• remove another module's hook
• reorder another module's hook
• reorder a hook relative to alter hooks with extra types

#3485659: Remove HookOrder HookOrder was temporarily removed because it does not quite work with extras.
#3484754: Ordering of hooks needs some attention Resolves the BC break (this issue is the followup to address point 3)
#3479141: Implement FormAlter and Alter attribute is related since it is the most common form (lol) of an alter with extra types.

Steps to reproduce

Try to order an OOP implementation of a hook. Observe there's only a very clumsy legacy mechanism.

Proposed resolution

https://git.drupalcode.org/project/drupal/-/merge_requests/11437

• Orders procedural before OOP
• Does as much ordering before adding to the container as possible
• Preserves run time ordering.
• Groups alters together

There are CRs to address each piece of hook_module_implements_alter functionality needed to handle hook ordering.

Ordering own implementation

See this CR for more complete examples: https://www.drupal.org/node/3493962
Add order parameter to the #[Hook] attribute.
The order parameter accepts the following simple ordering options.
Order::First
Order::Last
The order parameter also accepts the following complex ordering options which also accept parameters.
OrderBefore()
OrderAfter()
These can accept the following parameters:
modules: an array of modules to order before or after.
classesAndMethods: an array of arrays of classes and methods to order before or after.

Here is how it works for CKEditor5.

  #[Hook('form_filter_format_form_alter',
    order: new OrderAfter(
      modules: ['editor', 'media']
    )
  )]

OrderAfter specifies this hook should run after the parameters passed.
modules: ['editor', 'media'], specifies this ordering cares about the editor and media modules.

Removal

See this CR for more details: https://www.drupal.org/node/3496786
Add #[RemoveHook()] attribute.
The #[RemoveHook()] attribute accepts details about the implementation to remove.

#[RemoveHook('help', class: LayoutBuilderHooks::class, method: 'help')]

This will remove the layout builder hook_help implementation.

Ordering other implementations

See this CR for more details: https://www.drupal.org/node/3497308
Add #[ReOrderHook()] attribute.
The #[ReOrderHook()] attribute accepts details about the implementation to reorder.

class WorkspacesHooks {
  #[ReOrderHook('entity_presave',
    class: ContentModerationHooks::class,
    method: 'entityPresave',
    order: new OrderBefore(['workspaces'])
  )]
  public function entityPresave()

This allows the workspaces module to move the entity_presave implementation in content_moderation before the implementation in workspaces.

Deprecation

See this CR for more details: https://www.drupal.org/node/3496788
Deprecate hook_module_implements_alter implementations without: #[LegacyModuleImplementsAlter]

Remaining tasks

Review

Here is a summary of who I have seen reviews from and the current status. Please comment if you reviewed or if I have misinterpreted your reviews.
These reviews were for the current api, but the implementation has changed.

Authors

• nicxvan (nlighteneddesign)
• ghostofdrupalpast
• donquixote

Reviewers
The underlying approach has changed since this list was generated, but the dx and deprecation have remained the same.

• catch - High level review, frequent spot reviews in slack for questions, sign-off for including deprecation - believe all comments addressed
• larowlan - Deep review of the code, deprecation method sign-off, all comments addressed
• berdir - Architectural review, not implementation, some reservations about extraTypes on ordering, but last comment was in agreement it is needed, all comments addressed
• amateescu - Review of the Workspaces conversion, unsure if review extended beyond that
• donquixote - Deep review of the code, many comments addressed, a number were explored and not necessary. Pivoted approach.
• godotislate - Very early review, approach changed significantly since

User interface changes

N/A

Introduced terminology

Order
OrderAfter
OrderBefore
RemoveHook
ReOrderHook

API changes

A new enum and two new classes assist with ordering, these replace hook_module_implements_alter:

• Order
• OrderAfter
• OrderBefore

Two new attributes to assist with modifying other hook implementations.
#[RemoveHook()]
#[ReOrderHook()]

Do not delete hook_module_implements_alter until you drop support for Drupal VERSION instead add the #[LegacyModuleImplementsAlter] attribute to hook_module_implements_alter once the module has set up the correct ordering attributes.

Data model changes

N/A

Release notes snippet

N/A