Document events that can be subscribed to in an EventSubscriber

Created on 15 August 2024, 8 months ago
Updated 19 August 2024, 8 months ago

Documentation location/URL

https://api.drupal.org/api/drupal

Problem/Motivation

The Drupal API section of drupal.org is not being kept up to date with the needs of developing in modern Drupal. There is no way to search or list events that are dispatched by core that can be listened for in an EventSubscriber. Events should be searchable in some way, similar to the way that hooks can be found by typing "hook_" into the autocomplete search field at https://api.drupal.org/api/drupal.

This is necessary because of the direction Drupal core is heading by removing hooks and replacing them with events. I understand that they are harder to document, but we cannot get rid of hooks, provide no equivalent documentation and reasonably expect new developers to be able to learn Drupal. New developers will not know the equivalent hook version of the undocumented event in order to reverse engineer how to do something in the latest version of Drupal where the hook has been removed.

Take hook_file_validate for example. It has been removed from Drupal 11 and replaced with an event. The only way you would know the name of the event is to search for "hook_file_validate" within the Drupal 10 API: https://api.drupal.org/api/drupal/core%21modules%21file%21file.api.php/f...

You would then see the deprecation notice and a link to this: https://www.drupal.org/node/3363700

Where there is two sentences on the deprecation of the hook.

I don't see how this is sustainable. Developers should not have to sift through the documentation for previous versions of Drupal to find documentation for the current version.

Proposed resolution

Allow developers to search for events at https://api.drupal.org/api/drupal.

Remaining tasks

Feature request
Status

Active

Version

2.0

Component

Parser

Created by

🇺🇸United States maskedjellybean Portland, OR

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

  • Issue created by @maskedjellybean
  • 🇺🇸United States maskedjellybean Portland, OR
  • 🇮🇹Italy apaderno Brescia, 🇮🇹

    The source for the page on https://api.drupal.org/api/drupal is the core.api.php file in the Drupal core repository.

    Being able to search for events on api.drupal.org is a feature request for the API module.

  • 🇹🇷Turkey Kartagis Istanbul

    Maybe something like this?

  • 🇮🇹Italy apaderno Brescia, 🇮🇹

    The list of all the possible type of events used by Drupal core are listed on Events. The single entries say which event class is received from an event listener method.

  • 🇺🇸United States maskedjellybean Portland, OR

    Thanks for moving this to the correct project.

    Searching for "Subscriber" is not what I'm looking for. That will give you existing event subscribers, not events that can be subscribed to. You could find events that can be subscribed to that way, but it would be very time consuming. Plus it's theoretically possible for core to provide an event that is not subscribed to by core, meaning you wouldn't find it this way.

    I have seen https://api.drupal.org/api/drupal/core%21core.api.php/group/events/11.x , but it's not accurate. For example \Drupal\file\Validation\FileValidationEvent is not listed. Is this list automatically generated or manually maintained?

  • 🇮🇹Italy apaderno Brescia, 🇮🇹

    The list is automatically generated and it lists everything that contains @Event in a documentation comment. It is @Event that is manually added (since documentation comments are written by human beings).

    core/lib/Drupal/Core/Session/AccountEvents.php

      /**
       * Name of the event fired when the current user is set.
       *
       * This event allows modules to perform an action whenever the current user is
       * set. The event listener receives an \Drupal\Core\Session\AccountSetEvent
       * instance.
       *
       * @Event
       *
       * @see \Drupal\Core\Session\AccountSetEvent
       * @see \Drupal\Core\Session\AccountProxyInterface::setAccount()
       *
       * @var string
       */
      const SET_USER = 'account.set';
    
    

    core/modules/block_content/src/BlockContentEvents.php

      /**
       * Name of the event when getting the dependency of a non-reusable block.
       *
       * This event allows modules to provide a dependency for non-reusable block
       * access if
       * \Drupal\block_content\Access\DependentAccessInterface::getAccessDependency()
       * did not return a dependency during access checking.
       *
       * @Event
       *
       * @see \Drupal\block_content\Event\BlockContentGetDependencyEvent
       * @see \Drupal\block_content\BlockContentAccessControlHandler::checkAccess()
       *
       * @var string
       */
      const BLOCK_CONTENT_GET_DEPENDENCY = 'block_content.get_dependency';
    
  • 🇮🇹Italy apaderno Brescia, 🇮🇹

    Actually, there are more projects involved.

    The API module parses the documentation comments and provides lists of pages containing a documentation tag, for example @Event in this case.
    The documentation comments are in the source of another project, such as Drupal core, in the case of pages listed under https://api.drupal.org/api/drupal.

Production build 0.71.5 2024