Merge remote-tracking branch 'origin/promise-rejection'

* origin/promise-rejection:
  Document passing promises to resolve()/reject() methods of a Defered/Resolver
  Ensure reject() always rejects with a reason value even if rejection value is a promise

Author: igorw

README.md

@@ -159,6 +159,9 @@ Resolves a Deferred. All consumers are notified by having their
 `$fulfilledHandler` (which they registered via `$promise->then()`) called with
 `$result`.
 
+If `$result` itself is a promise, the Deferred will transition to the state of
+this promise once it is resolved.
+
 ``` php
 $resolver->reject(mixed $reason = null);
 ```
@@ -167,6 +170,9 @@ Rejects a Deferred, signalling that the Deferred's computation failed.
 All consumers are notified by having their `$errorHandler` (which they
 registered via `$promise->then()`) called with `$reason`.
 
+If `$reason` itself is a promise, the Deferred will be rejected with the outcome
+of this promise regardless whether it fulfills or rejects.
+
 ``` php
 $resolver->progress(mixed $update = null);
 ```

src/React/Promise/Deferred.php

@@ -66,7 +66,7 @@ public function resolve($result = null)
 
     public function reject($reason = null)
     {
-        return $this->resolve(new RejectedPromise($reason));
+        return $this->resolve(Util::rejectedPromiseFor($reason));
     }
 
     public function progress($update = null)

src/React/Promise/Util.php

@@ -12,4 +12,15 @@ public static function promiseFor($promiseOrValue)
 
         return new FulfilledPromise($promiseOrValue);
     }
+
+    public static function rejectedPromiseFor($promiseOrValue)
+    {
+        if ($promiseOrValue instanceof PromiseInterface) {
+            return $promiseOrValue->then(function ($value) {
+                return new RejectedPromise($value);
+            });
+        }
+
+        return new RejectedPromise($promiseOrValue);
+    }
 }

src/React/Promise/When.php

@@ -11,9 +11,7 @@ public static function resolve($promiseOrValue = null)
 
     public static function reject($promiseOrValue = null)
     {
-        return static::resolve($promiseOrValue)->then(function ($value = null) {
-            return new RejectedPromise($value);
-        });
+        return Util::rejectedPromiseFor($promiseOrValue);
     }
 
     public static function all($promisesOrValues, $fulfilledHandler = null, $errorHandler = null, $progressHandler = null)

tests/React/Promise/DeferredRejectTest.php

@@ -9,7 +9,7 @@
 class DeferredRejectTest extends TestCase
 {
     /** @test */
-    public function shouldReject()
+    public function shouldRejectWithAnImmediateValue()
     {
         $d = new Deferred();
 
@@ -28,6 +28,46 @@ public function shouldReject()
             ->reject(1);
     }
 
+    /** @test */
+    public function shouldRejectWithFulfilledPromise()
+    {
+        $d = new Deferred();
+
+        $mock = $this->createCallableMock();
+        $mock
+            ->expects($this->once())
+            ->method('__invoke')
+            ->with($this->identicalTo(1));
+
+        $d
+            ->promise()
+            ->then($this->expectCallableNever(), $mock);
+
+        $d
+            ->resolver()
+            ->reject(new FulfilledPromise(1));
+    }
+
+    /** @test */
+    public function shouldRejectWithRejectedPromise()
+    {
+        $d = new Deferred();
+
+        $mock = $this->createCallableMock();
+        $mock
+            ->expects($this->once())
+            ->method('__invoke')
+            ->with($this->identicalTo(1));
+
+        $d
+            ->promise()
+            ->then($this->expectCallableNever(), $mock);
+
+        $d
+            ->resolver()
+            ->reject(new RejectedPromise(1));
+    }
+
     /** @test */
     public function shouldReturnAPromiseForTheRejectionValue()
     {

tests/React/Promise/UtilRejectedPromiseForTest.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace React\Promise;
+
+/**
+ * @group Util
+ * @group UtilRejectedPromiseFor
+ */
+class UtilRejectedPromiseForTest extends TestCase
+{
+    /** @test */
+    public function shouldRejectWithAnImmediateValue()
+    {
+        $expected = 123;
+
+        $mock = $this->createCallableMock();
+        $mock
+            ->expects($this->once())
+            ->method('__invoke')
+            ->with($this->identicalTo($expected));
+
+        Util::rejectedPromiseFor($expected)
+            ->then(
+                $this->expectCallableNever(),
+                $mock
+            );
+    }
+
+    /** @test */
+    public function shouldRejectWithFulfilledPromise()
+    {
+        $expected = 123;
+
+        $resolved = new FulfilledPromise($expected);
+
+        $mock = $this->createCallableMock();
+        $mock
+            ->expects($this->once())
+            ->method('__invoke')
+            ->with($this->identicalTo($expected));
+
+        Util::rejectedPromiseFor($resolved)
+            ->then(
+                $this->expectCallableNever(),
+                $mock
+            );
+    }
+
+    /** @test */
+    public function shouldRejectWithRejectedPromise()
+    {
+        $expected = 123;
+
+        $resolved = new RejectedPromise($expected);
+
+        $mock = $this->createCallableMock();
+        $mock
+            ->expects($this->once())
+            ->method('__invoke')
+            ->with($this->identicalTo($expected));
+
+        Util::rejectedPromiseFor($resolved)
+            ->then(
+                $this->expectCallableNever(),
+                $mock
+            );
+    }
+}