feat: return listener from attach, attachWildcardListener methods

This is necessary to keep feature parity with current versions, but can
be removed in version 4.

Author: weierophinney

src/ListenerProvider/PrioritizedListenerAttachmentInterface.php

@@ -14,7 +14,11 @@ interface PrioritizedListenerAttachmentInterface
      * @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
+     * @return callable The listener attached, to allow subscribers to track
+     *    which listeners were attached, and thus detach them. This return
+     *    value will be changed to `void` in version 4; we recommend
+     *    subscribers write their own logic for tracking what has and hasn't
+     *    been attached.
      */
     public function attach($event, callable $listener, $priority = 1);
 
@@ -41,7 +45,11 @@ public function detach(callable $listener, $event = null);
      * @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
+     * @return callable The listener attached, to allow subscribers to track
+     *    which listeners were attached, and thus detach them. This return
+     *    value will be changed to `void` in version 4; we recommend
+     *    subscribers write their own logic for tracking what has and hasn't
+     *    been attached.
      */
     public function attachWildcardListener(callable $listener, $priority = 1);
 

src/ListenerProvider/PrioritizedListenerProvider.php

@@ -97,6 +97,8 @@ public function attach($event, callable $listener, $priority = 1)
         }
 
         $this->events[$event][(int) $priority][0][] = $listener;
+
+        return $listener;
     }
 
     /**
@@ -153,6 +155,7 @@ public function detach(callable $listener, $event = null, $force = false)
     public function attachWildcardListener(callable $listener, $priority = 1)
     {
         $this->events['*'][(int) $priority][0][] = $listener;
+        return $listener;
     }
 
     /**