feat: update EventManager to use listener providers

- Adds `Zend\EventManager\EventDispatcherInterface` as a forwards
  compatibility shim for PSR-14.
- Adds `Zend\EventManager\SharedEventManager\SharedEventManagerDecorator`,
  which decorates generic `SharedEventManagerInterface` instances as
  listener providers.
- Modifies `PrioritizedAggregateListenerProvider` to accept an optional
  `ListenerProviderInterface $default` argument. This allows
  non-prioritized `SharedEventManagerInterface` instances (such as the
  `SharedEventManagerDecorator` in the previous item) to be fallback
  providers.
- Modifies `Zend\EventManager\EventManager` as follows:
  - It now implements `EventDispatcherInterface`
  - It now composes a `$provider` property, and an optional
    `$prioritizedProvider` property. If you instantiate it per previous
    versions, it creates a `PrioritizedListenerProvider` instance and
    assigns it to the `$prioritizedProvider` property. It then checks to
    see if a shared manager was provided, and the type provided, to
    either assign the `$prioritizedProvider` as the `$provider`, or a
    `PrioritizedAggregateListenerProvider` that composes both the
    `$prioritizedProvider` and shared manager instances.
  - It adds a static named constructor, `createUsingListenerProvider()`,
    which accepts a single `ListenerProviderInterface` instance. This
    value is assigned to `$provider`, and, if it is a
    `PrioritizedListenerAttachmentInterface` instance, to the
    `$prioritizedProvider` property as well.
  - Each of the listener attachment methods (attach, detach,
    clearListeners, *WildcardListeners) now proxy to the composed
    `$prioritizedProvider`, if any. If there is none, theses methods
    now raise an exception.
  - The `getListenersForEvent()` method now proxies to the underling
    `$provider` property.
  - The `triggerListeners()` method now consumes the value of
    `getListenersForEvent()`.
  - It adds the method `dispatch($event)`, which proxies to
    `triggerListeners()`, and returns the `$event` it was passed. The
    method raises an exception of `$event` is a non-object.
  - Each of `trigger()`, `triggerUntil`, `triggerEvent`,
    `triggerEventUntil`, `getIdentifiers`, `setIdentifiers`,
    `addIdenitifers`, `getSharedManager`, `attach`, `detach`,
    `attachWildcardListener`, `detachWildcardListener`,
    `clearListeners`, and `getListenersForEvent` have been marked
    deprecated.
- Updates `EventListenerIntrospectionTrait` to work with the new
  internals of the `EventManager`.
- Updates `EventManagerTest`:
  - updates `getListenersForEvent()` to work with the new `EventManager`
    internals
  - Removes `testAttachShouldAddEventIfItDoesNotExist` as it was
    irrelevant even before the changes.
  - Removes the `testTriggeringAnEventWithAnEmptyNameRaisesAnException`
    test, as this is no longer true; you can use any object as an event
    now.
  - Modifies a few tests where they were accessing internal structures
    that have changed, while keeping the same assertions in place.
- Adds `EventManagerWithProviderTest` to demonstrate usage when creating
  an `EventManager` via its `createUsingListenerProvider()` method.
- Updates `EventListenerIntrospectionTraitTest` to work with the new
  internals of the `EventManager`.

Author: weierophinney

TODO-PSR-14.md

@@ -59,22 +59,34 @@
       - [x] with an event, can be attached to `LazyListenerSubscriber`
     - [x] Constructor aggregates `LazyListener` _instances_ only
       - [x] raises exception when `getEvent()` returns null
-- [ ] Event Dispatcher implementation
-  - [ ] Implement `PrioritizedListenerAttachmentInterface` (if BC)
-  - [ ] Create a `PrioritizedListenerProvider` instance in the `EventManger`
-    constructor, and have the various `attach()`, `detach()`, etc. methods
-    proxy to it.
-  - [ ] When triggering listeners, create a `PrioritizedAggregateListenerProvider` 
+- [x] Adapter for SharedEventManagerInterface
+  Since we type-hint on SharedEventManagerInterface, we need to adapt generic
+  implementations to work as ListenerProviders.
+  - [x] Class that adapts SharedEventManagerInterface instances to ListenerProviders
+- [x] Event Dispatcher implementation
+  - [x] Implement `PrioritizedListenerAttachmentInterface` (if BC)
+  - [x] Implement `ListenerProviderInterface` (if BC)
+  - [x] Create a `PrioritizedListenerProvider` instance in the `EventManger`
+    constructor
+    - [x] Decorate it in a `PrioritizedAggregateListenerProvider`
+    - [x] Have the various `attach()`, `detach()`, etc. methods proxy to it.
+    - [x] Adapt any provided `SharedEventManagerInterface` instance, and add it
+        to the `PrioritizedAggregateListenerProvider`
+  - [x] Create a named constructor that accepts a listener provider and which
+    then uses it internally.
+    - [x] If the instance is a `PrioritizedListenerAttachmentInterface`
+      instance, allow the attach/detach/clear methods to proxy to it.
+  - [x] When triggering listeners, create a `PrioritizedAggregateListenerProvider` 
     with the composed `PrioritizedListenerProvider` and `SharedListenerProvider` /
     `PrioritizedIdentifierListenerProvider` implementations, in that order.
-  - [ ] Replace logic of `triggerListeners()` to just call
+  - [x] Replace logic of `triggerListeners()` to just call
     `getListenersForEvent()` on the provider. It can continue to aggregate the
     responses in a `ResponseCollection`
-  - [ ] `triggerListeners()` no longer needs to type-hint its first argument
-  - [ ] Create a `dispatch()` method
-    - [ ] Method will act like `triggerEvent()`, except
-    - [ ] it will return the event itself
-    - [ ] it will need to validate that it received an object before calling
+  - [x] `triggerListeners()` no longer needs to type-hint its first argument
+  - [x] Create a `dispatch()` method
+    - [x] Method will act like `triggerEvent()`, except
+    - [x] it will return the event itself
+    - [x] it will need to validate that it received an object before calling
       `triggerListeners`
 - [ ] Additional utilities
   - [ ] `EventDispatchingInterface` with a `getEventDispatcher()` method

src/EventDispatcherInterface.php

@@ -0,0 +1,28 @@
+<?php
+/**
+ * @see       https://github.com/zendframework/zend-eventmanager for the canonical source repository
+ * @copyright Copyright (c) 2019 Zend Technologies USA Inc. (https://www.zend.com)
+ * @license   https://github.com/zendframework/zend-eventmanager/blob/master/LICENSE.md New BSD License
+ */
+
+namespace Zend\EventManager;
+
+/**
+ * Forwards-compatibility shim for PSR-14.
+ *
+ * @deprecated Will be removed with version 4, at which time users can instead
+ *     implement or typehint against the PSR-14 Psr\EventDispatcher\EventDispatcherInterface.
+ */
+interface EventDispatcherInterface
+{
+    /**
+     * Provide all relevant listeners with an event to process.
+     *
+     * @param object $event
+     *   The object to process.
+     *
+     * @return object
+     *   The Event that was passed, now modified by listeners.
+     */
+    public function dispatch($event);
+}