Problem/Motivation

#3471763: API-docs support for OO hooks implementations in classes
#3479141: Implement FormAlter attribute
Probably a third issue here to update rules to allow no comments if the attribute is for hooks.

Once the two above land we can remove the redundant Implements Hook since it's in the attribute.

Steps to reproduce

N/A

Proposed resolution

Remove them

Remaining tasks

Remove them

User interface changes

N/A

Introduced terminology

N/A

API changes

N/A

Data model changes

N/A

Release notes snippet

N/A

Comments

nicxvan created an issue. See original summary.

berdir’s picture

I would assume that api module can't properly pick up #Hook methods, whether or not they have the Implements docblock, so I'd assume that's not really a blocker, it's already broken without that change.

What I think is a blocker of this is a coding standards issue to change the requirement around this. We need to change this bit: https://www.drupal.org/docs/develop/standards/php/api-documentation-and-....

That means we need an issue in this project: https://www.drupal.org/project/coding_standards. See #2140961: Allow constructor methods to omit docblocks for the example that changed the requirements around constructor params.

ghost of drupal past’s picture

> I would assume that api module can't properly pick up #Hook methods

A proof of concept for that already exists in #3471763: API-docs support for OO hooks implementations in classes but we decided it's better to properly support attributes and then special case from there. Attribute support branch is up at #3449634: Attributes are not rendered when showing the source code we need a test, I will write one when I get to it, help is always welcome.

I'd like to get #Hook api support out by the time D11.1 lands. We will see whether time permits.

berdir’s picture

That was maybe a bit unclear, let me expand: "I assume that API module currently out of the box would not find class methods as hook implementations, whether or not there is a 'Implements hook_foo()' docblock and therefore having or not having those docblocks is not relevant or api.module. It needs adjustments to find those and these adjustments will not look at the comment string anymore.".

kristiaanvandeneynde’s picture

Nic pointed me to this issue and I just wanna slap a big fat +1 on dropping the comment.

An example from my conversion in Group:

  /**
   * Implements hook_help().
   */
  #[Hook('help')]
  public function help(string $route_name, RouteMatchInterface $route_match): string {
    return match ($route_name) {
      '...' => '<p>' . '...' . '</p>',
      default => ''
    };
  }

I mean, I think it's clear enough judging from the attribute and method name what we're dealing with.

Having said all of that, I agree that making the docs support attributes is probably the best way forward as more systems can benefit from that now that we're moving so much stuff over to attributes (e.g. entity type definitions).

eric_a’s picture

Title: [PP-2] Remove Implements comments once the api can pickup hook implementations from classes. » Remove Implements comments once the api can pickup hook implementations from classes.

Unfortunately removing that from the docblock would make it harder to search code for hooks that have placeholders in the name.

We now have for example:

  /**
   * Implements hook_ENTITY_TYPE_presave().
   */
  #[Hook('view_presave')]
  /**
   * Implements hook_ENTITY_TYPE_presave() for blocks.
   */
  #[Hook('block_presave')]
nicxvan’s picture

Good point @eric_a!

That only affects dynamic hooks though.

I wonder if we should work on the policy to allow excluding comments on hook implementations, or do we want to add comments that actually explain what the hook implementation is doing. I have always felt like we should be explaining the point of them.

angel_devoeted’s picture

Keeping comments for dynamic hooks makes sense for discoverability.
For static hooks, however, removing the redundant “Implements hook_*” comments would help keep the code cleaner.
Perhaps we could limit removals to non-dynamic hooks only.

nicxvan’s picture

@angel_devoeted that is certainly an option as well.

I've had a couple of suggestions to create a specific non runtime attribute for finding these implementations (e.g. #[Implements] or #[DynamicHook])

I have the following reservations about that approach:

1 people already are inconsistent about adding the comments
2 do we only want it for dynamic or all, cause just dynamic is two ways to grep for hooks
3 people already do the comments wrong for dynamic e.g. people will do [DynamicHook('custom_entity_name_presave')] which defeats the purpose
4 This is an extra attribute that is looped over during collection even though it's not used
5 this will create two ways to search depending on if it's dynamic or not

I think number 4 is the biggest reason not to do it this way.

The truth is you can search for dynamic hooks even using the #[Hook] attribute with some regex, maybe we just need to build that and document it for a couple of common hooks so people can easily search.

For example for hook_form_FORM_ID_alter
grep -Er "#\[Hook\('form_[A-Za-z0-9_]+_alter'" core/modules/

Version: 11.x-dev » main

Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

Read more in the announcement.