Event subscribers: A new hook system.
=======================================

:Published at: March 2, 2020
:Author: Erlend ter Maat
:Tags: Drupal, Drupal hook system

----

Last time I wrote `about Drupal's services </blog/2020/02/24/drupal-service-system.html>`_ mechnanism. Today I show what this
technology has to offer for working OO in letting modules talk with each other: the hook system.

I was a little disappointed when I first saw Drupal 8. So many things were improved, but why did I still see this
method-name-guessing mechanism of hooks? I did not follow. Until today. I guess this legacy code keeps following us a
while. There is good news on this subject too. You are not forced to stick to this legacy method. I'm pleased to
introduce to you it's younger brother!

hook_menu_alter... (A Confession)
---------------------------------

I was disappointed. That's true. Actually I was disappointed because 'they' removed hook_menu_alter. Without asking me
first! How could this happen? It happened to be one of the first hooks the Drupal code developers phased out.

From now on the things you did at hook_menu_alter are solved in this fashion::

  # custom_module.services.yml
  services:
    custom_module.routing
      class: Drupal\custom_module\Routing\CustomRouteSubscriber
      tags:
        - { name: 'event_subscriber' }


.. code-block:: php

    <?php

    namespace Drupal\custom_module\Routing;

    use Drupal\Core\Routing\RouteSubscriberBase;
    use Symfony\Component\Routing\RouteCollection;

    class CustomRouteSubscriber extends RouteSubscriberBase {

      protected function alterRoutes(RouteCollection $routeCollection) {
        // Change route parameters in the collection object...
      }

    }

Why is this better?
-------------------

It looks ugly... I am used to drupal 3, 4, 5, 6, 7 style hooks. Maybe.

Module name clashes?
^^^^^^^^^^^^^^^^^^^^

I often heard the complaint that the hook system forced one to create unique module names. But even though this is
true; you should still give modules unique names. So this method is not better because now you can create another
module with the same name.

Guessing the method name is not a method you should depend on - in itself. I value giving proper names to methods. A name
should say something about what the method does. A method should do one thing as a means of writing maintainable code.
And that one thing is briefly expressed in the method name. To let an outside system determine the name of the method
forces me to give a name that probably does say anything about my purpose for the method. The new hook method allows
developers to make the hook known to the origin of the hook by configuration, and gives more freedom to express
what the customization is about in the names of classes and member variables and methods.

Explicit is better then implicit
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

I remember that I could get a little confused as I wrote custom drush commmands. I still can't recall what the method
name must be given a drush command key. Python has a saying "Explicit is better then implicit". I think that's true. The
more specific you can be, the more predictable the output of your code will be. To specify the 'hook' in a yaml file
makes your code more predictable.

It's class based
^^^^^^^^^^^^^^^^

The method based hook system persuaded developers to keep all code in one method. As a result the drupal hook
implementation tended to look like spagheticode in a short time. It became hard to read and maintain. It brought
developers to ideas of using switches and nested if statements.

Now you can dedicate one class to do one part of the customization. And if the customization gets to big, it's easy
to write 2 or more private methods that support your customization, all in the same file or module. It results in
clean, maintainable code. This hook system allows you to write hooks in an object oriented fashion.

Order of execution
------------------

In some cases one would want to have a hook executed before or after all other hooks. A common solution for this is
to change the order in which the modules are loaded by the drupal module system. I see a possibility to solve this in
the yaml file. For example::

  services:
    custom_module.routing
      class: Drupal\custom_module\Routing\CustomRouteSubscriber
      tags:
        - { name: 'event_subscriber' }
      weight: 100000000

However, in this solution I still have to guess a number high or low enough to have my hook be the last or
first in execution order.

The order of execution is still something you don't have a hand in as 3rd or 4th party module developer. I suggest
another pattern to support this demand. If it applies to your custom hook that other developers may want edit the
data in a specific place relative to other modules I suggest two patterns on how to implement this. It may be a
state machine, where you provice parameters at the hook that indicate the context in which the hook is called. Or you
provide a drag and drop GUI to have site administrators choose the order of execution. An example on the GUI for this
can be found in the `Examples for Developers modules <https://www.drupal.org/project/examples>`_ at the
'tabledrag_example' module.

Conclusion
----------

Event subscriber services do solve an important 'problem' of the former hook system in terms of OO and (therefore)
readability, maintainability.

For further reading I refer to the drupal documentation, where hou can find an example on how you can create your own hooks
in this fashion is found on drupal.org in the article "`Subscribe to and dispatch events <https://www.drupal.org/docs/8/creating-custom-modules/subscribe-to-and-dispatch-events>`_".

Next time...
------------

The most common way to access services is by means of `depencency injection </blog/2020/03/09/drupal-dependency-injection.html>`_.
Next blog post I will show how powerfull that is, and how this power can be used properly.