Implement AsyncInterop\Promise

README.md

@@ -43,6 +43,7 @@ Table of Contents
      * [map()](#map)
      * [reduce()](#reduce)
    * [PromisorInterface](#promisorinterface)
+   * [AsyncInterop\Promise compatibility](#asyncinteroppromise-compatibility)
 4. [Examples](#examples)
    * [How to use Deferred](#how-to-use-deferred)
    * [How promise forwarding works](#how-promise-forwarding-works)
@@ -151,6 +152,11 @@ and an associated value, or rejection (failure) and an associated reason.
 Once in the fulfilled or rejected state, a promise becomes immutable.
 Neither its state nor its result (or error) can be modified.
 
+This interface extends the
+[`AsyncInterop\Promise`](https://github.com/async-interop/promise) interface.
+See [`AsyncInterop\Promise` compatibility](#asyncinteroppromise-compatibility),
+for further information.
+
 #### Implementations
 
 * [Promise](#promise-1)
@@ -402,6 +408,10 @@ Creates a promise for the supplied `$promiseOrValue`.
 If `$promiseOrValue` is a value, it will be the resolution value of the
 returned promise.
 
+If `$promiseOrValue` is a
+[`AsyncInterop\Promise`](https://github.com/async-interop/promise), a trusted
+promise that follows the state of the `AsyncInterop\Promise` is returned.
+
 If `$promiseOrValue` is a thenable (any object that provides a `then()` method),
 a trusted promise that follows the state of the thenable is returned.
 
@@ -512,6 +522,27 @@ The `React\Promise\PromisorInterface` provides a common interface for objects
 that provide a promise. `React\Promise\Deferred` implements it, but since it
 is part of the public API anyone can implement it.
 
+### AsyncInterop\Promise compatibility
+
+The [`PromiseInterface`](#promiseinterface) extends the
+[`AsyncInterop\Promise`](https://github.com/async-interop/promise) interface and
+thereby all promise implementations from React/Promise implement its `when()`
+method.
+
+The `AsyncInterop\Promise` interface is intended for interoperability with other
+libraries and their combinator and conversion functions.
+
+Note, that although the interface is named *Promise*, it has nothing to do with
+promises commonly known from the
+[CommonJS Promises/A](http://wiki.commonjs.org/wiki/Promises/A),
+[Promises/A+](https://promisesaplus.com) or
+[ECMAScript 2015 (ES6)](http://www.ecma-international.org/ecma-262/6.0/#sec-promise-constructor)
+specifications.
+
+If you're using React/Promise as your primary value placeholder implementation, 
+it is recommended to **not** use the `when()` method directly but the methods
+provided by the [`PromiseInterface`](#promiseinterface).
+
 Examples
 --------
 

composer.json

@@ -6,9 +6,11 @@
         {"name": "Jan Sorgalla", "email": "[email protected]"}
     ],
     "require": {
-        "php": ">=5.4.0"
+        "php": ">=5.4.0",
+        "async-interop/promise": "^0.4.0"
     },
     "require-dev": {
+        "async-interop/promise-test": "^0.4.1",
         "phpunit/phpunit": "~4.8"
     },
     "autoload": {

src/FulfilledPromise.php

@@ -2,13 +2,15 @@
 
 namespace React\Promise;
 
+use AsyncInterop\Promise as AsyncInteropPromise;
+
 final class FulfilledPromise implements PromiseInterface
 {
     private $value;
 
     public function __construct($value = null)
     {
-        if ($value instanceof PromiseInterface) {
+        if ($value instanceof AsyncInteropPromise) {
             throw new \InvalidArgumentException('You cannot create React\Promise\FulfilledPromise with a promise. Use React\Promise\resolve($promiseOrValue) instead.');
         }
 
@@ -66,4 +68,15 @@ public function always(callable $onFulfilledOrRejected)
     public function cancel()
     {
     }
+
+    public function when(callable $onResolved)
+    {
+        try {
+            $onResolved(null, $this->value);
+        } catch (\Throwable $exception) {
+            AsyncInteropPromise\ErrorHandler::notify($exception);
+        } catch (\Exception $exception) {
+            AsyncInteropPromise\ErrorHandler::notify($exception);
+        }
+    }
 }

src/LazyPromise.php

@@ -37,6 +37,11 @@ public function cancel()
         return $this->promise()->cancel();
     }
 
+    public function when(callable $onResolved)
+    {
+        return $this->promise()->when($onResolved);
+    }
+
     /**
      * @internal
      * @see Promise::settle()

src/Promise.php

@@ -86,6 +86,17 @@ public function cancel()
         $this->call($canceller);
     }
 
+    public function when(callable $onResolved)
+    {
+        if (null !== $this->result) {
+            return $this->result()->when($onResolved);
+        }
+
+        $this->handlers[] = function (PromiseInterface $promise) use ($onResolved) {
+            $promise->when($onResolved);
+        };
+    }
+
     private function resolver(callable $onFulfilled = null, callable $onRejected = null)
     {
         return function ($resolve, $reject) use ($onFulfilled, $onRejected) {

src/PromiseInterface.php

@@ -2,7 +2,9 @@
 
 namespace React\Promise;
 
-interface PromiseInterface
+use AsyncInterop\Promise as AsyncInteropPromise;
+
+interface PromiseInterface extends AsyncInteropPromise
 {
     /**
      * @return PromiseInterface

src/RejectedPromise.php

@@ -2,13 +2,15 @@
 
 namespace React\Promise;
 
+use AsyncInterop\Promise as AsyncInteropPromise;
+
 final class RejectedPromise implements PromiseInterface
 {
     private $reason;
 
     public function __construct($reason = null)
     {
-        if ($reason instanceof PromiseInterface) {
+        if ($reason instanceof AsyncInteropPromise) {
             throw new \InvalidArgumentException('You cannot create React\Promise\RejectedPromise with a promise. Use React\Promise\reject($promiseOrValue) instead.');
         }
 
@@ -74,4 +76,18 @@ public function always(callable $onFulfilledOrRejected)
     public function cancel()
     {
     }
+
+    public function when(callable $onResolved)
+    {
+        try {
+            $onResolved(
+                UnhandledRejectionException::resolve($this->reason),
+                null
+            );
+        } catch (\Throwable $exception) {
+            AsyncInteropPromise\ErrorHandler::notify($exception);
+        } catch (\Exception $exception) {
+            AsyncInteropPromise\ErrorHandler::notify($exception);
+        }
+    }
 }

src/functions.php

@@ -2,12 +2,27 @@
 
 namespace React\Promise;
 
+use AsyncInterop\Promise as AsyncInteropPromise;
+
 function resolve($promiseOrValue = null)
 {
     if ($promiseOrValue instanceof PromiseInterface) {
         return $promiseOrValue;
     }
 
+    if ($promiseOrValue instanceof AsyncInteropPromise) {
+        return new Promise(function ($resolve, $reject) use ($promiseOrValue) {
+            $promiseOrValue->when(function ($reason = null, $value = null) use ($resolve, $reject) {
+                if ($reason) {
+                    $reject($reason);
+                    return;
+                }
+
+                $resolve($value);
+            });
+        });
+    }
+
     if (method_exists($promiseOrValue, 'then')) {
         $canceller = null;
 
@@ -31,6 +46,14 @@ function reject($promiseOrValue = null)
         });
     }
 
+    if ($promiseOrValue instanceof AsyncInteropPromise) {
+        return new Promise(function ($resolve, $reject) use ($promiseOrValue) {
+            $promiseOrValue->when(function ($reason = null, $value = null) use ($resolve, $reject) {
+                $reject($reason ? $reason : $value);
+            });
+        });
+    }
+
     return new RejectedPromise($promiseOrValue);
 }
 

tests/AsyncInterop/DeferredTest.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace React\Promise\AsyncInterop;
+
+use AsyncInterop\Promise\Test;
+use React\Promise\Deferred;
+
+class DeferredTest extends Test
+{
+    public function promise(callable $canceller = null)
+    {
+        $d = new Deferred($canceller);
+
+        return [
+            $d->promise(),
+            [$d, 'resolve'],
+            [$d, 'reject']
+        ];
+    }
+}

tests/AsyncInterop/LazyPromiseTest.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace React\Promise\AsyncInterop;
+
+use AsyncInterop\Promise\Test;
+use React\Promise\Deferred;
+use React\Promise\LazyPromise;
+
+class LazyPromiseTest extends Test
+{
+    public function promise(callable $canceller = null)
+    {
+        $d = new Deferred($canceller);
+
+        $factory = function () use ($d) {
+            return $d->promise();
+        };
+
+        return [
+            new LazyPromise($factory),
+            [$d, 'resolve'],
+            [$d, 'reject']
+        ];
+    }
+}

tests/AsyncInterop/PromiseTest.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace React\Promise\AsyncInterop;
+
+use AsyncInterop\Promise\Test;
+use React\Promise\Promise;
+
+class PromiseTest extends Test
+{
+    public function promise(callable $canceller = null)
+    {
+        $resolveCallback = $rejectCallback = null;
+
+        $promise = new Promise(function ($resolve, $reject) use (&$resolveCallback, &$rejectCallback) {
+            $resolveCallback = $resolve;
+            $rejectCallback  = $reject;
+        }, $canceller);
+
+        return [
+            $promise,
+            $resolveCallback,
+            $rejectCallback
+        ];
+    }
+}

tests/FulfilledPromiseTest.php

@@ -44,4 +44,12 @@ public function shouldThrowExceptionIfConstructedWithAPromise()
 
         return new FulfilledPromise(new FulfilledPromise());
     }
+
+    /** @test */
+    public function shouldThrowExceptionIfConstructedWithAAsyncInteropPromise()
+    {
+        $this->setExpectedException('\InvalidArgumentException');
+
+        return new FulfilledPromise(new SimpleFulfilledAsyncInteropTestPromise());
+    }
 }

tests/FunctionRejectTest.php

@@ -42,6 +42,24 @@ public function shouldRejectAFulfilledPromise()
             );
     }
 
+    /** @test */
+    public function shouldRejectAFulfilledAsyncInteropPromise()
+    {
+        $resolved = new SimpleFulfilledAsyncInteropTestPromise();
+
+        $mock = $this->createCallableMock();
+        $mock
+            ->expects($this->once())
+            ->method('__invoke')
+            ->with($this->identicalTo('foo'));
+
+        reject($resolved)
+            ->then(
+                $this->expectCallableNever(),
+                $mock
+            );
+    }
+
     /** @test */
     public function shouldRejectARejectedPromise()
     {
@@ -61,4 +79,23 @@ public function shouldRejectARejectedPromise()
                 $mock
             );
     }
+
+    /** @test */
+    public function shouldRejectARejectedAsyncInteropPromise()
+    {
+        $exception = new \Exception('foo');
+        $resolved = new SimpleRejectedAsyncInteropTestPromise($exception);
+
+        $mock = $this->createCallableMock();
+        $mock
+            ->expects($this->once())
+            ->method('__invoke')
+            ->with($this->identicalTo($exception));
+
+        reject($resolved)
+            ->then(
+                $this->expectCallableNever(),
+                $mock
+            );
+    }
 }