From 576a8c2cc81030d99a971dad0460cd5d5f02ff41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20L=C3=BCck?= <christian@lueck.tv>
Date: Mon, 23 Apr 2018 20:28:31 +0200
Subject: [PATCH] Mark legacy progress support / notification API as deprecated

---
 README.md                        | 16 +++++++++++-----
 src/Deferred.php                 |  4 ++++
 src/ExtendedPromiseInterface.php |  4 ++++
 src/PromiseInterface.php         |  3 +++
 4 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 4e6588b0..1cc11274 100644
--- a/README.md
+++ b/README.md
@@ -103,7 +103,7 @@ The `promise` method returns the promise of the deferred.
 
 The `resolve` and `reject` methods control the state of the deferred.
 
-The `notify` method is for progress notification.
+The deprecated `notify` method is for progress notification.
 
 The constructor of the `Deferred` accepts an optional `$canceller` argument.
 See [Promise](#promise-2) for more information.
@@ -146,6 +146,8 @@ of this promise regardless whether it fulfills or rejects.
 
 #### Deferred::notify()
 
+> Deprecated in v2.6.0: Progress support is deprecated and should not be used anymore.
+
 ```php
 $deferred->notify(mixed $update = null);
 ```
@@ -190,7 +192,7 @@ with a promise (all parameters are optional):
     the result as the first argument.
   * `$onRejected` will be invoked once the promise is rejected and passed the
     reason as the first argument.
-  * `$onProgress` will be invoked whenever the producer of the promise
+  * `$onProgress` (deprecated) will be invoked whenever the producer of the promise
     triggers progress notifications and passed a single argument (whatever it
     wants) to indicate progress.
 
@@ -205,7 +207,7 @@ the same call to `then()`:
      never both.
   2. `$onFulfilled` and `$onRejected` will never be called more
      than once.
-  3. `$onProgress` may be called multiple times.
+  3. `$onProgress` (deprecated) may be called multiple times.
 
 #### See also
 
@@ -321,6 +323,8 @@ return doSomething()
 
 #### ExtendedPromiseInterface::progress()
 
+> Deprecated in v2.6.0: Progress support is deprecated and should not be used anymore.
+
 ```php
 $promise->progress(callable $onProgress);
 ```
@@ -364,7 +368,7 @@ Creates a promise whose state is controlled by the functions passed to
 ```php
 $resolver = function (callable $resolve, callable $reject, callable $notify) {
     // Do some work, possibly asynchronously, and then
-    // resolve or reject. You can notify of progress events
+    // resolve or reject. You can notify of progress events (deprecated)
     // along the way if you want/need.
 
     $resolve($awesomeResult);
@@ -391,7 +395,7 @@ function which both will be called with 3 arguments:
     When called with another promise, e.g. `$resolve($otherPromise)`, promise's
     fate will be equivalent to that of `$otherPromise`.
   * `$reject($reason)` - Function that rejects the promise.
-  * `$notify($update)` - Function that issues progress events for the promise.
+  * `$notify($update)` - Deprecated function that issues progress events for the promise.
 
 If the resolver or canceller throw an exception, the promise will be rejected
 with that thrown exception as the rejection reason.
@@ -721,6 +725,8 @@ $deferred->resolve(1);  // Prints "Mixed 4"
 
 #### Progress event forwarding
 
+> Deprecated in v2.6.0: Progress support is deprecated and should not be used anymore.
+
 In the same way as resolution and rejection handlers, your progress handler
 **MUST** return a progress event to be propagated to the next link in the chain.
 If you return nothing, `null` will be propagated.
diff --git a/src/Deferred.php b/src/Deferred.php
index f23980c3..6ac5eaa0 100644
--- a/src/Deferred.php
+++ b/src/Deferred.php
@@ -42,6 +42,10 @@ public function reject($reason = null)
         call_user_func($this->rejectCallback, $reason);
     }
 
+    /**
+     * @deprecated 2.6.0 Progress support is deprecated and should not be used anymore.
+     * @param mixed $update
+     */
     public function notify($update = null)
     {
         $this->promise();
diff --git a/src/ExtendedPromiseInterface.php b/src/ExtendedPromiseInterface.php
index 9cb64359..3654177c 100644
--- a/src/ExtendedPromiseInterface.php
+++ b/src/ExtendedPromiseInterface.php
@@ -5,6 +5,9 @@
 interface ExtendedPromiseInterface extends PromiseInterface
 {
     /**
+     *
+     * The `$onProgress` argument is deprecated and should not be used anymore.
+     *
      * @return void
      */
     public function done(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null);
@@ -21,6 +24,7 @@ public function always(callable $onFulfilledOrRejected);
 
     /**
      * @return ExtendedPromiseInterface
+     * @deprecated 2.6.0 Progress support is deprecated and should not be used anymore.
      */
     public function progress(callable $onProgress);
 }
diff --git a/src/PromiseInterface.php b/src/PromiseInterface.php
index d80d1142..fcd763d3 100644
--- a/src/PromiseInterface.php
+++ b/src/PromiseInterface.php
@@ -5,6 +5,9 @@
 interface PromiseInterface
 {
     /**
+     *
+     * The `$onProgress` argument is deprecated and should not be used anymore.
+     *
      * @return PromiseInterface
      */
     public function then(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null);