feature #30691 [Contracts][EventDispatcher] add EventDispatcherInterface to symfony/contracts and use it where possible (nicolas-grekas)

This PR was merged into the 4.3-dev branch.

Discussion
----------

[Contracts][EventDispatcher] add EventDispatcherInterface to symfony/contracts and use it where possible

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

This PR adds a new `EventDispatcherInterface` in `Contracts`. This interface contains only one method: `dispatch($event, $eventName)`. That covers almost all use cases of the event dispatcher in components (some use add/removeListeners/Subscribers but they are a minority.)

While doing so, it allows dispatching any objects as events - not only instances of `Event`.

This allows decoupling e.g. `Messenger` from the `EventDispatcher` component.
Next steps could be about planning to remove the base `Event` class from some concrete event classes and/or moving `EventSubscriberInterface` to `symfony/contracts`. It would allow decoupling e.g. `Workflow` from the component - but that's too far away for now, let's think about it in 5.1.

Commits
-------

3c3db2f14a [Contracts][EventDispatcher] add EventDispatcherInterface to symfony/contracts and use it where possible

Author: fabpot

CHANGELOG.md

@@ -5,6 +5,7 @@ CHANGELOG
 -----
 
  * added `HttpClient` namespace with contracts for implementing flexible HTTP clients
+ * added `EventDispatcher\EventDispatcherInterface`
 
 1.0.0
 -----

EventDispatcher/EventDispatcherInterface.php

@@ -0,0 +1,58 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Contracts\EventDispatcher;
+
+use Psr\EventDispatcher\EventDispatcherInterface as PsrEventDispatcherInterface;
+
+if (interface_exists(PsrEventDispatcherInterface::class)) {
+    /**
+     * Allows providing hooks on domain-specific lifecycles by dispatching events.
+     */
+    interface EventDispatcherInterface extends PsrEventDispatcherInterface
+    {
+        /**
+         * Dispatches an event to all registered listeners.
+         *
+         * For BC with Symfony 4, the $eventName argument is not declared explicitly on the
+         * signature of the method. Implementations that are not bound by this BC contraint
+         * MUST declare it explicitly, as allowed by PHP.
+         *
+         * @param object      $event     The event to pass to the event handlers/listeners
+         * @param string|null $eventName The name of the event to dispatch. If not supplied,
+         *                               the class of $event should be used instead.
+         *
+         * @return object The passed $event MUST be returned
+         */
+        public function dispatch($event/*, string $eventName = null*/);
+    }
+} else {
+    /**
+     * Allows providing hooks on domain-specific lifecycles by dispatching events.
+     */
+    interface EventDispatcherInterface
+    {
+        /**
+         * Dispatches an event to all registered listeners.
+         *
+         * For BC with Symfony 4, the $eventName argument is not declared explicitly on the
+         * signature of the method. Implementations that are not bound by this BC contraint
+         * MUST declare it explicitly, as allowed by PHP.
+         *
+         * @param object      $event     The event to pass to the event handlers/listeners
+         * @param string|null $eventName The name of the event to dispatch. If not supplied,
+         *                               the class of $event should be used instead.
+         *
+         * @return object The passed $event MUST be returned
+         */
+        public function dispatch($event/*, string $eventName = null*/);
+    }
+}

composer.json

@@ -27,6 +27,7 @@
         "psr/cache": "When using the Cache contracts",
         "psr/container": "When using the Service contracts",
         "symfony/cache-contracts-implementation": "",
+        "symfony/event-dispatcher-implementation": "",
         "symfony/http-client-contracts-implementation": "",
         "symfony/service-contracts-implementation": "",
         "symfony/translation-contracts-implementation": ""