feat: Creates PrioritizedListenerAttachmentInterface

This provides the methods necessary for attaching listeners. It does not
extend PrioritizedListenerProviderInterface, as we want to be able to
re-use that particular interface with shared providers, which will have
a different attachment mechanism in version 3 releases.

Author: weierophinney

TODO-PSR-14.md

@@ -15,13 +15,16 @@
   - [x] Create a `PrioritizedListenerProvider` interface extending the
       `ListenerProviderInterface` and defining a
       `getListenersForEventByPriority($event, array $identifiers = []) : array<int, callable[]>` method.
-  - [ ] Create a `PrioritizedListenerAttachmentInterface`, defining:
-    - [ ] `attach($event, callable $listener, $priority = 1)` (where `$event`
+  - [x] Create a `PrioritizedListenerAttachmentInterface`, defining:
+    - [x] `attach($event, callable $listener, $priority = 1)` (where `$event`
       can be an object or string name)
-    - [ ] `detach(callable $listener, $event = null, $force = false)` (where `$event`
+    - [x] `detach(callable $listener, $event = null, $force = false)` (where `$event`
       can be an object or string name and `$force` is boolean)
-    - [ ] `attachWildcardListener(callable $listener, $priority = 1)`
+    - [x] `attachWildcardListener(callable $listener, $priority = 1)`
       (`attach('*', $listener, $priority)` will proxy to this method)
+    - [x] `detachWildcardListener(callable $listener, $force = false)`
+      (`detach($listener, '*', $force)` will proxy to this method)
+    - [x] `clearListeners($event)`
   - [ ] Create a `PrioritizedListenerProvider` implementation of the above based
     on the internals of `EventManager`
     - [ ] attachment/detachment

src/ListenerProvider/PrioritizedListenerAttachmentInterface.php

@@ -0,0 +1,69 @@
+<?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\ListenerProvider;
+
+interface PrioritizedListenerAttachmentInterface
+{
+    /**
+     * @param  string $event The event type to which the listener will respond.
+     * @param  callable $listener The listener itself.
+     * @param  int $priority The priority at which to attach the listener. High
+     *     priorities respond earlier; negative priorities respond later.
+     * @return void
+     */
+    public function attach($event, callable $listener, $priority = 1);
+
+    /**
+     * @param  callable $listener The listener to detach.
+     * @param  null|string $event Which events to detach the listener from.
+     *     When null, all events. If '*', this will only detach the wildcard
+     *     entry for a listener, unless $force is true.
+     * @return void
+     */
+    public function detach(callable $listener, $event = null);
+
+    /**
+     * Attaches a listener as a wildcard listener (to all events).
+     *
+     * Analagous to:
+     *
+     * <code>
+     * attach('*', $listener, $priority)
+     * </code>
+     *
+     * The above will actually invoke this method instead.
+     *
+     * @param  callable $listener The listener to attach.
+     * @param  int      $priority The priority at which to attach the listener.
+     *     High priorities respond earlier; negative priorities respond later.
+     * @return void
+     */
+    public function attachWildcardListener(callable $listener, $priority = 1);
+
+    /**
+     * Detaches a wildcard listener.
+     *
+     * Analagous to:
+     *
+     * <code>
+     * detach($listener, '*', $force)
+     * </code>
+     *
+     * The above will actually invoke this method instead.
+     *
+     * @param  callable $listener The listener to detach.
+     * @return void
+     */
+    public function detachWildcardListener(callable $listener);
+
+    /**
+     * @param  string $event The event for which to remove listeners.
+     * @return void
+     */
+    public function clearListeners($event);
+}