feat: deprecate features that will be removed in version 4

weierophinney · weierophinney · commit 1e8c2059574d · 2019-04-09T17:06:22.000-05:00
- `EventInterface`
- `EventManagerInterface`
- `EventManagerAwareInterface`
- `EventManagerAwareTrait`
- `EventsCapableInterface` (points people to `EventDispatchingInterface`)
- `SharedEventManager`
- `SharedEventManagerInterface`
- `SharedEventsCapableInterface`
- `ListenerAggregateInterface` (points people to the `PrioritizedListenerAttachmentInterface`)
- `ListenerAggregateTrait` (points people to `ListenerSubscriberTrait`)
- `AbstractListenerAggregate` (points people to `AbstractListenerSubscriber` and/or `ListenerSubscriberTrait`)
- `ResponseCollection` (tells people to aggregate state/results in the event itself)
- `LazyListener` (points people to `ListenerProvider\LazyListener`)
- `LazyEventListener` (points people to `ListenerProvider\LazyListener`)
- `LazyListenerAggregate` (points people to `ListenerProvider\LazyListenerSubscriber`)
- `FilterChain` and `Filter` subnamespace (this should be done in a separate component)
diff --git a/TODO-PSR-14.md b/TODO-PSR-14.md
@@ -91,22 +91,22 @@
 - [x] Additional utilities
   - [x] `EventDispatchingInterface` with a `getEventDispatcher()` method
 - [ ] Deprecations
-  - [ ] `EventInterface`
-  - [ ] `EventManagerInterface`
-  - [ ] `EventManagerAwareInterface`
-  - [ ] `EventManagerAwareTrait`
-  - [ ] `EventsCapableInterface` (point people to `EventDispatchingInterface`)
-  - [ ] `SharedEventManager`
-  - [ ] `SharedEventManagerInterface`
-  - [ ] `SharedEventsCapableInterface`
-  - [ ] `ListenerAggregateInterface` (point people to the `PrioritizedListenerAttachmentInterface`)
-  - [ ] `ListenerAggregateTrait` (point people to `ListenerSubscriberTrait`)
-  - [ ] `AbstractListenerAggregate` (point people to `AbstractListenerSubscriber` and/or `ListenerSubscriberTrait`)
-  - [ ] `ResponseCollection` (tell people to aggregate state/results in the event itself)
-  - [ ] `LazyListener` (point people to `ListenerProvider\LazyListener`)
-  - [ ] `LazyEventListener` (point people to `ListenerProvider\LazyListener`)
-  - [ ] `LazyListenerAggregate` (point people to `ListenerProvider\LazyListenerSubscriber`)
-  - [ ] `FilterChain` and `Filter` subnamespace (this should be done in a separate component)
+  - [x] `EventInterface`
+  - [x] `EventManagerInterface`
+  - [x] `EventManagerAwareInterface`
+  - [x] `EventManagerAwareTrait`
+  - [x] `EventsCapableInterface` (point people to `EventDispatchingInterface`)
+  - [x] `SharedEventManager`
+  - [x] `SharedEventManagerInterface`
+  - [x] `SharedEventsCapableInterface`
+  - [x] `ListenerAggregateInterface` (point people to the `PrioritizedListenerAttachmentInterface`)
+  - [x] `ListenerAggregateTrait` (point people to `ListenerSubscriberTrait`)
+  - [x] `AbstractListenerAggregate` (point people to `AbstractListenerSubscriber` and/or `ListenerSubscriberTrait`)
+  - [x] `ResponseCollection` (tell people to aggregate state/results in the event itself)
+  - [x] `LazyListener` (point people to `ListenerProvider\LazyListener`)
+  - [x] `LazyEventListener` (point people to `ListenerProvider\LazyListener`)
+  - [x] `LazyListenerAggregate` (point people to `ListenerProvider\LazyListenerSubscriber`)
+  - [x] `FilterChain` and `Filter` subnamespace (this should be done in a separate component)
 
 ## 4.0.0 full release
 
diff --git a/src/AbstractListenerAggregate.php b/src/AbstractListenerAggregate.php
@@ -11,6 +11,11 @@
 
 /**
  * Abstract aggregate listener
+ *
+ * @deprecated since 3.3.0. This class will be removed in version 4.0.0, in
+ *     favor of the ListenerProvider\AbstractListenerSubscriber. In most cases,
+ *     subscribers should fully implement ListenerSubscriberInterface on their
+ *     own, however.
  */
 abstract class AbstractListenerAggregate implements ListenerAggregateInterface
 {
diff --git a/src/EventInterface.php b/src/EventInterface.php
@@ -13,6 +13,9 @@
 
 /**
  * Representation of an event
+ *
+ * @deprecated since 3.3.0. This interface will be removed in version 4.0, in
+ *     favor of using simple PHP objects as events.
  */
 interface EventInterface
 {
diff --git a/src/EventManagerAwareInterface.php b/src/EventManagerAwareInterface.php
@@ -11,6 +11,8 @@
 
 /**
  * Interface to automate setter injection for an EventManager instance
+ *
+ * @deprecated since 3.3.0. This interface will be removed in version 4.0.
  */
 interface EventManagerAwareInterface extends EventsCapableInterface
 {
diff --git a/src/EventManagerAwareTrait.php b/src/EventManagerAwareTrait.php
@@ -20,6 +20,7 @@
  * EventManager into your object when it is pulled from the ServiceManager.
  *
  * @see Zend\Mvc\Service\ServiceManagerConfig
+ * @deprecated since 3.3.0. This trait will be removed in version 4.0.
  */
 trait EventManagerAwareTrait
 {
diff --git a/src/EventManagerInterface.php b/src/EventManagerInterface.php
@@ -11,6 +11,9 @@
 
 /**
  * Interface for messengers
+ *
+ * @deprecated since 3.3.0; this interface will be removed in version 4.0, in
+ *     favor of the PSR-14 EventDispatcherInterface and ListenerProviderInterface.
  */
 interface EventManagerInterface extends SharedEventsCapableInterface
 {
diff --git a/src/EventsCapableInterface.php b/src/EventsCapableInterface.php
@@ -11,6 +11,9 @@
 
 /**
  * Interface indicating that an object composes an EventManagerInterface instance.
+ *
+ * @deprecated since 3.3.0. This interface will be removed in version 4.0, in
+ *     favor of the EventDispatcherInterface introduced in version 3.3.0.
  */
 interface EventsCapableInterface
 {
diff --git a/src/Filter/FilterInterface.php b/src/Filter/FilterInterface.php
@@ -13,6 +13,9 @@
 
 /**
  * Interface for intercepting filter chains
+ *
+ * @deprecated since 3.3.0. This interface will be removed in version 4.0.0. No
+ *     replacement is provided.
  */
 interface FilterInterface
 {
diff --git a/src/Filter/FilterIterator.php b/src/Filter/FilterIterator.php
@@ -16,7 +16,10 @@
  * Specialized priority queue implementation for use with an intercepting
  * filter chain.
  *
- * Allows removal
+ * Allows removal.
+ *
+ * @deprecated since 3.3.0. This class will be removed in version 4.0.0. No
+ *     replacement is provided.
  */
 class FilterIterator extends FastPriorityQueue
 {
diff --git a/src/FilterChain.php b/src/FilterChain.php
@@ -11,6 +11,9 @@
 
 /**
  * FilterChain: intercepting filter manager
+ *
+ * @deprecated since 3.3.0. This class will be removed in version 4.0.0. No
+ *     replacement is provided.
  */
 class FilterChain implements Filter\FilterInterface
 {
diff --git a/src/LazyEventListener.php b/src/LazyEventListener.php
@@ -22,6 +22,9 @@
  *
  * - event: the event name to attach to.
  * - priority: the priority at which to attach the listener, if not the default.
+ *
+ * @deprecated since 3.3.0. This class will be removed in version 4.0.0, in
+ *     favor of the ListenerProvider\LazyListener implementation.
  */
 class LazyEventListener extends LazyListener
 {
diff --git a/src/LazyListener.php b/src/LazyListener.php
@@ -28,6 +28,9 @@
  *
  * Pass instances directly to the event manager's `attach()` method as the
  * listener argument.
+ *
+ * @deprecated since 3.3.0. This class will be removed in version 4.0.0, in
+ *     favor of the ListenerProvider\LazyListener implementation.
  */
 class LazyListener
 {
diff --git a/src/LazyListenerAggregate.php b/src/LazyListenerAggregate.php
@@ -26,6 +26,9 @@
  *     $container
  * ));
  * </code>
+ *
+ * @deprecated since 3.3.0. This class will be removed in version 4.0.0 in
+ *     favor of the ListenerProvider\LazyListenerSubscriber implementation.
  */
 class LazyListenerAggregate implements ListenerAggregateInterface
 {
diff --git a/src/ListenerAggregateInterface.php b/src/ListenerAggregateInterface.php
@@ -16,6 +16,9 @@
  * with an EventManager, without an event name. The {@link attach()} method will
  * then be called with the current EventManager instance, allowing the class to
  * wire up one or more listeners.
+ *
+ * @deprecated since 3.3.0. This interface will be removed in version 4.0.0, in
+ *     favor of the ListenerProvider\ListenerSubscriberInterface.
  */
 interface ListenerAggregateInterface
 {
diff --git a/src/ListenerAggregateTrait.php b/src/ListenerAggregateTrait.php
@@ -12,6 +12,11 @@
 /**
  * Provides logic to easily create aggregate listeners, without worrying about
  * manually detaching events
+ *
+ * @deprecated since 3.3.0. This trait will be removed in version 4.0.0, in
+ *     favor of the ListenerProvider\ListenerSubscriberTrait. In most cases,
+ *     subscribers should fully implement ListenerSubscriberInterface on their
+ *     own, however.
  */
 trait ListenerAggregateTrait
 {
diff --git a/src/ResponseCollection.php b/src/ResponseCollection.php
@@ -13,6 +13,11 @@
 
 /**
  * Collection of signal handler return values
+ *
+ * @deprecated since 3.3.0. This class will be removed in version 4.0.0.
+ *     Listeners should not return values, and any values that should be
+ *     aggregated or used to stop propagation should be injected directly into
+ *     the event instance itself, via its own published API.
  */
 class ResponseCollection extends SplStack
 {
diff --git a/src/SharedEventManagerInterface.php b/src/SharedEventManagerInterface.php
@@ -11,6 +11,9 @@
 
 /**
  * Interface for shared event listener collections
+ *
+ * @deprecated since 3.3.0. This interface will be removed in version 4.0; use
+ *     listener providers instead.
  */
 interface SharedEventManagerInterface
 {
diff --git a/src/SharedEventsCapableInterface.php b/src/SharedEventsCapableInterface.php
@@ -12,6 +12,8 @@
 /**
  * Interface indicating that an object composes or can compose a
  * SharedEventManagerInterface instance.
+ *
+ * @deprecated since 3.3.0. This interface will be removed in version 4.0.
  */
 interface SharedEventsCapableInterface
 {

Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,9 @@`
`13`	`13`
`14`	`14`	`/**`
`15`	`15`	`* Representation of an event`
	`16`	`+ *`
	`17`	`+ * @deprecated since 3.3.0. This interface will be removed in version 4.0, in`
	`18`	`+ * favor of using simple PHP objects as events.`
`16`	`19`	`*/`
`17`	`20`	`interface EventInterface`
`18`	`21`	`{`
Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,8 @@`
`11`	`11`
`12`	`12`	`/**`
`13`	`13`	`* Interface to automate setter injection for an EventManager instance`
	`14`	`+ *`
	`15`	`+ * @deprecated since 3.3.0. This interface will be removed in version 4.0.`
`14`	`16`	`*/`
`15`	`17`	`interface EventManagerAwareInterface extends EventsCapableInterface`
`16`	`18`	`{`
Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,7 @@`
`20`	`20`	`* EventManager into your object when it is pulled from the ServiceManager.`
`21`	`21`	`*`
`22`	`22`	`* @see Zend\Mvc\Service\ServiceManagerConfig`
	`23`	`+ * @deprecated since 3.3.0. This trait will be removed in version 4.0.`
`23`	`24`	`*/`
`24`	`25`	`trait EventManagerAwareTrait`
`25`	`26`	`{`
Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,9 @@`
`11`	`11`
`12`	`12`	`/**`
`13`	`13`	`* Interface for messengers`
	`14`	`+ *`
	`15`	`+ * @deprecated since 3.3.0; this interface will be removed in version 4.0, in`
	`16`	`+ * favor of the PSR-14 EventDispatcherInterface and ListenerProviderInterface.`
`14`	`17`	`*/`
`15`	`18`	`interface EventManagerInterface extends SharedEventsCapableInterface`
`16`	`19`	`{`
Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,10 @@`
`16`	`16`	`* Specialized priority queue implementation for use with an intercepting`
`17`	`17`	`* filter chain.`
`18`	`18`	`*`
`19`		`- * Allows removal`
	`19`	`+ * Allows removal.`
	`20`	`+ *`
	`21`	`+ * @deprecated since 3.3.0. This class will be removed in version 4.0.0. No`
	`22`	`+ * replacement is provided.`
`20`	`23`	`*/`
`21`	`24`	`class FilterIterator extends FastPriorityQueue`
`22`	`25`	`{`
Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,9 @@`
`22`	`22`	`*`
`23`	`23`	`* - event: the event name to attach to.`
`24`	`24`	`* - priority: the priority at which to attach the listener, if not the default.`
	`25`	`+ *`
	`26`	`+ * @deprecated since 3.3.0. This class will be removed in version 4.0.0, in`
	`27`	`+ * favor of the ListenerProvider\LazyListener implementation.`
`25`	`28`	`*/`
`26`	`29`	`class LazyEventListener extends LazyListener`
`27`	`30`	`{`
Original file line number	Diff line number	Diff line change
`@@ -28,6 +28,9 @@`
`28`	`28`	`*`
`29`	`29`	* Pass instances directly to the event manager's `attach()` method as the
`30`	`30`	`* listener argument.`
	`31`	`+ *`
	`32`	`+ * @deprecated since 3.3.0. This class will be removed in version 4.0.0, in`
	`33`	`+ * favor of the ListenerProvider\LazyListener implementation.`
`31`	`34`	`*/`
`32`	`35`	`class LazyListener`
`33`	`36`	`{`
Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,8 @@`
`12`	`12`	`/**`
`13`	`13`	`* Interface indicating that an object composes or can compose a`
`14`	`14`	`* SharedEventManagerInterface instance.`
	`15`	`+ *`
	`16`	`+ * @deprecated since 3.3.0. This interface will be removed in version 4.0.`
`15`	`17`	`*/`
`16`	`18`	`interface SharedEventsCapableInterface`
`17`	`19`	`{`