Merge pull request #75 from reactphp/merge-interfaces

Merge promise interfaces

Author: jsor

CHANGELOG.md

@@ -12,3 +12,32 @@ CHANGELOG for 3.x
       `some()`, `map()`, `reduce()`) now require an array of promises or values
       as input. Before, arrays and promises which resolve to an array were
       supported, other input types resolved to empty arrays or `null` (#35).
+    * BC break: The interfaces `PromiseInterface`, `ExtendedPromiseInterface`
+      and `CancellablePromiseInterface` have been merged into a single
+      `PromiseInterface` (#75).
+
+      Please note, that the following code (which has been commonly used to
+      conditionally cancel a promise) is not longer possible:
+
+      ```php
+      if ($promise instanceof CancellablePromiseInterface) {
+          $promise->cancel();
+      }
+      ```
+
+      If only supporting react/promise >= 3.0, it can be simply changed to:
+
+      ```php
+      if ($promise instanceof PromiseInterface) {
+          $promise->cancel();
+      }
+      ```
+
+      If also react/promise < 3.0 must be supported, the following code can be
+      used:
+
+      ```php
+      if ($promise instanceof PromiseInterface) {
+          \React\Promise\resolve($promise)->cancel();
+      }
+      ```

README.md

@@ -25,12 +25,10 @@ Table of Contents
      * [Deferred::reject()](#deferredreject)
    * [PromiseInterface](#promiseinterface)
      * [PromiseInterface::then()](#promiseinterfacethen)
-   * [ExtendedPromiseInterface](#extendedpromiseinterface)
-        * [ExtendedPromiseInterface::done()](#extendedpromiseinterfacedone)
-        * [ExtendedPromiseInterface::otherwise()](#extendedpromiseinterfaceotherwise)
-        * [ExtendedPromiseInterface::always()](#extendedpromiseinterfacealways)
-   * [CancellablePromiseInterface](#cancellablepromiseinterface)
-        * [CancellablePromiseInterface::cancel()](#cancellablepromiseinterfacecancel)
+     * [PromiseInterface::done()](#promiseinterfacedone)
+     * [PromiseInterface::otherwise()](#promiseinterfaceotherwise)
+     * [PromiseInterface::always()](#promiseinterfacealways)
+     * [PromiseInterface::cancel()](#promiseinterfacecancel)
    * [Promise](#promise-1)
    * [FulfilledPromise](#fulfilledpromise)
    * [RejectedPromise](#rejectedpromise)
@@ -193,22 +191,10 @@ the same call to `then()`:
 
 * [resolve()](#resolve) - Creating a resolved promise
 * [reject()](#reject) - Creating a rejected promise
-* [ExtendedPromiseInterface::done()](#extendedpromiseinterfacedone)
+* [PromiseInterface::done()](#promiseinterfacedone)
 * [done() vs. then()](#done-vs-then)
 
-### ExtendedPromiseInterface
-
-The ExtendedPromiseInterface extends the PromiseInterface with useful shortcut
-and utility methods which are not part of the Promises/A specification.
-
-#### Implementations
-
-* [Promise](#promise-1)
-* [FulfilledPromise](#fulfilledpromise)
-* [RejectedPromise](#rejectedpromise)
-* [LazyPromise](#lazypromise)
-
-#### ExtendedPromiseInterface::done()
+#### PromiseInterface::done()
 
 ```php
 $promise->done(callable $onFulfilled = null, callable $onRejected = null);
@@ -228,7 +214,7 @@ Since the purpose of `done()` is consumption rather than transformation,
 * [PromiseInterface::then()](#promiseinterfacethen)
 * [done() vs. then()](#done-vs-then)
 
-#### ExtendedPromiseInterface::otherwise()
+#### PromiseInterface::otherwise()
 
 ```php
 $promise->otherwise(callable $onRejected);
@@ -254,7 +240,7 @@ $promise
     )};
 ```
 
-#### ExtendedPromiseInterface::always()
+#### PromiseInterface::always()
 
 ```php
 $newPromise = $promise->always(callable $onFulfilledOrRejected);
@@ -301,13 +287,7 @@ return doSomething()
     ->always('cleanup');
 ```
 
-### CancellablePromiseInterface
-
-A cancellable promise provides a mechanism for consumers to notify the creator
-of the promise that they are not longer interested in the result of an
-operation.
-
-#### CancellablePromiseInterface::cancel()
+#### PromiseInterface::cancel()
 
 ``` php
 $promise->cancel();
@@ -319,13 +299,6 @@ further interest in the results of the operation.
 Once a promise is settled (either fulfilled or rejected), calling `cancel()` on
 a promise has no effect.
 
-#### Implementations
-
-* [Promise](#promise-1)
-* [FulfilledPromise](#fulfilledpromise)
-* [RejectedPromise](#rejectedpromise)
-* [LazyPromise](#lazypromise)
-
 ### Promise
 
 Creates a promise whose state is controlled by the functions passed to
@@ -435,11 +408,6 @@ a trusted promise that follows the state of the thenable is returned.
 
 If `$promiseOrValue` is a promise, it will be returned as is.
 
-Note: The promise returned is always a promise implementing
-[ExtendedPromiseInterface](#extendedpromiseinterface). If you pass in a custom
-promise which only implements [PromiseInterface](#promiseinterface), this
-promise will be assimilated to a extended promise following `$promiseOrValue`.
-
 #### reject()
 
 ```php

src/CancellablePromiseInterface.php

@@ -2,7 +2,7 @@
 
 namespace React\Promise;
 
-class FulfilledPromise implements ExtendedPromiseInterface, CancellablePromiseInterface
+class FulfilledPromise implements PromiseInterface
 {
     private $value;
 
@@ -43,7 +43,7 @@ public function done(callable $onFulfilled = null, callable $onRejected = null)
         queue()->enqueue(function () use ($onFulfilled) {
             $result = $onFulfilled($this->value);
 
-            if ($result instanceof ExtendedPromiseInterface) {
+            if ($result instanceof PromiseInterface) {
                 $result->done();
             }
         });

src/ExtendedPromiseInterface.php

@@ -2,7 +2,7 @@
 
 namespace React\Promise;
 
-class LazyPromise implements ExtendedPromiseInterface, CancellablePromiseInterface
+class LazyPromise implements PromiseInterface
 {
     private $factory;
     private $promise;

src/FulfilledPromise.php

@@ -2,7 +2,7 @@
 
 namespace React\Promise;
 
-class Promise implements ExtendedPromiseInterface, CancellablePromiseInterface
+class Promise implements PromiseInterface
 {
     private $canceller;
     private $result;
@@ -45,7 +45,7 @@ public function done(callable $onFulfilled = null, callable $onRejected = null)
             return $this->result()->done($onFulfilled, $onRejected);
         }
 
-        $this->handlers[] = function (ExtendedPromiseInterface $promise) use ($onFulfilled, $onRejected) {
+        $this->handlers[] = function (PromiseInterface $promise) use ($onFulfilled, $onRejected) {
             $promise
                 ->done($onFulfilled, $onRejected);
         };
@@ -90,7 +90,7 @@ public function cancel()
     private function resolver(callable $onFulfilled = null, callable $onRejected = null)
     {
         return function ($resolve, $reject) use ($onFulfilled, $onRejected) {
-            $this->handlers[] = function (ExtendedPromiseInterface $promise) use ($onFulfilled, $onRejected, $resolve, $reject) {
+            $this->handlers[] = function (PromiseInterface $promise) use ($onFulfilled, $onRejected, $resolve, $reject) {
                 $promise
                     ->then($onFulfilled, $onRejected)
                     ->done($resolve, $reject);
@@ -116,7 +116,7 @@ private function reject($reason = null)
         $this->settle(reject($reason));
     }
 
-    private function settle(ExtendedPromiseInterface $result)
+    private function settle(PromiseInterface $result)
     {
         if ($result instanceof LazyPromise) {
             $result = $result->promise();

src/LazyPromise.php

@@ -8,4 +8,24 @@ interface PromiseInterface
      * @return PromiseInterface
      */
     public function then(callable $onFulfilled = null, callable $onRejected = null);
+
+    /**
+     * @return void
+     */
+    public function done(callable $onFulfilled = null, callable $onRejected = null);
+
+    /**
+     * @return PromiseInterface
+     */
+    public function otherwise(callable $onRejected);
+
+    /**
+     * @return PromiseInterface
+     */
+    public function always(callable $onFulfilledOrRejected);
+
+    /**
+     * @return void
+     */
+    public function cancel();
 }

src/Promise.php

@@ -2,7 +2,7 @@
 
 namespace React\Promise;
 
-class RejectedPromise implements ExtendedPromiseInterface, CancellablePromiseInterface
+class RejectedPromise implements PromiseInterface
 {
     private $reason;
 
@@ -47,7 +47,7 @@ public function done(callable $onFulfilled = null, callable $onRejected = null)
                 throw UnhandledRejectionException::resolve($result->reason);
             }
 
-            if ($result instanceof ExtendedPromiseInterface) {
+            if ($result instanceof PromiseInterface) {
                 $result->done();
             }
         });

src/PromiseInterface.php

@@ -4,7 +4,7 @@
 
 function resolve($promiseOrValue = null)
 {
-    if ($promiseOrValue instanceof ExtendedPromiseInterface) {
+    if ($promiseOrValue instanceof PromiseInterface) {
         return $promiseOrValue;
     }