Merge branch 'master' into enforce-exception-reasons

Author: jsor

.travis.yml

@@ -6,6 +6,7 @@ php:
   - 5.6
   - 7.0
   - 7.1
+  - 7.2
   - nightly # ignore errors, see below
   - hhvm # ignore errors, see below
 

README.md

@@ -305,14 +305,16 @@ $resolver = function (callable $resolve, callable $reject) {
     // resolve or reject.
 
     $resolve($awesomeResult);
+    // or throw new Exception('Promise rejected');
     // or $resolve($anotherPromise);
     // or $reject($nastyError);
 };
 
-$canceller = function (callable $resolve, callable $reject) {
+$canceller = function () {
     // Cancel/abort any running operations like network connections, streams etc.
 
-    $reject(new \Exception('Promise cancelled'));
+    // Reject promise by throwing an exception
+    throw new Exception('Promise cancelled');
 };
 
 $promise = new React\Promise\Promise($resolver, $canceller);
@@ -326,7 +328,8 @@ function which both will be called with 3 arguments:
     When called with a non-promise value, fulfills promise with that value.
     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.
+  * `$reject($reason)` - Function that rejects the promise. It is recommended to
+    just throw an exception instead of using `$reject()`.
 
 If the resolver or canceller throw an exception, the promise will be rejected
 with that thrown exception as the rejection reason.

composer.json

@@ -9,7 +9,7 @@
         "php": ">=5.4.0"
     },
     "require-dev": {
-        "phpunit/phpunit": "~4.8"
+        "phpunit/phpunit": "~4.8.35 || ~5.7 || ~6.4"
     },
     "autoload": {
         "psr-4": {

src/Deferred.php

@@ -33,13 +33,13 @@ public function resolve($value = null)
     {
         $this->promise();
 
-        call_user_func($this->resolveCallback, $value);
+        \call_user_func($this->resolveCallback, $value);
     }
 
     public function reject($reason)
     {
         $this->promise();
 
-        call_user_func($this->rejectCallback, $reason);
+        \call_user_func($this->rejectCallback, $reason);
     }
 }

src/Internal/CancellationQueue.php

@@ -22,11 +22,11 @@ public function __invoke()
 
     public function enqueue($cancellable)
     {
-        if (!method_exists($cancellable, 'then') || !method_exists($cancellable, 'cancel')) {
+        if (!\method_exists($cancellable, 'then') || !\method_exists($cancellable, 'cancel')) {
             return;
         }
 
-        $length = array_push($this->queue, $cancellable);
+        $length = \array_push($this->queue, $cancellable);
 
         if ($this->started && 1 === $length) {
             $this->drain();
@@ -35,7 +35,7 @@ public function enqueue($cancellable)
 
     private function drain()
     {
-        for ($i = key($this->queue); isset($this->queue[$i]); $i++) {
+        for ($i = \key($this->queue); isset($this->queue[$i]); $i++) {
             $cancellable = $this->queue[$i];
 
             $exception = null;

src/Internal/Queue.php

@@ -11,14 +11,14 @@ final class Queue
 
     public function enqueue(callable $task)
     {
-        if (1 === array_push($this->queue, $task)) {
+        if (1 === \array_push($this->queue, $task)) {
             $this->drain();
         }
     }
 
     private function drain()
     {
-        for ($i = key($this->queue); isset($this->queue[$i]); $i++) {
+        for ($i = \key($this->queue); isset($this->queue[$i]); $i++) {
             $task = $this->queue[$i];
 
             $exception = null;

src/Promise.php

@@ -176,15 +176,33 @@ private function unwrap($promise)
 
     private function call(callable $callback)
     {
+        // Use reflection to inspect number of arguments expected by this callback.
+        // We did some careful benchmarking here: Using reflection to avoid unneeded
+        // function arguments is actually faster than blindly passing them.
+        // Also, this helps avoiding unnecessary function arguments in the call stack
+        // if the callback creates an Exception (creating garbage cycles).
+        if (\is_array($callback)) {
+            $ref = new \ReflectionMethod($callback[0], $callback[1]);
+        } elseif (\is_object($callback) && !$callback instanceof \Closure) {
+            $ref = new \ReflectionMethod($callback, '__invoke');
+        } else {
+            $ref = new \ReflectionFunction($callback);
+        }
+        $args = $ref->getNumberOfParameters();
+
         try {
-            $callback(
-                function ($value = null) {
-                    $this->resolve($value);
-                },
-                function ($reason) {
-                    $this->reject($reason);
-                }
-            );
+            if ($args === 0) {
+                $callback();
+            } else {
+                $callback(
+                    function ($value = null) {
+                        $this->resolve($value);
+                    },
+                    function ($reason) {
+                        $this->reject($reason);
+                    }
+                );
+            }
         } catch (\Throwable $e) {
             $this->reject($e);
         } catch (\Exception $e) {

src/PromiseInterface.php

@@ -5,26 +5,120 @@
 interface PromiseInterface
 {
     /**
+     * Transforms a promise's value by applying a function to the promise's fulfillment
+     * or rejection value. Returns a new promise for the transformed result.
+     *
+     * The `then()` method registers new fulfilled and rejection handlers with a promise
+     * (all parameters are optional):
+     *
+     *  * `$onFulfilled` will be invoked once the promise is fulfilled and passed
+     *     the result as the first argument.
+     *  * `$onRejected` will be invoked once the promise is rejected and passed the
+     *     reason as the first argument.
+     *
+     * It returns a new promise that will fulfill with the return value of either
+     * `$onFulfilled` or `$onRejected`, whichever is called, or will reject with
+     * the thrown exception if either throws.
+     *
+     * A promise makes the following guarantees about handlers registered in
+     * the same call to `then()`:
+     *
+     *  1. Only one of `$onFulfilled` or `$onRejected` will be called,
+     *      never both.
+     *  2. `$onFulfilled` and `$onRejected` will never be called more
+     *      than once.
+     *
+     * @param callable|null $onFulfilled
+     * @param callable|null $onRejected
      * @return PromiseInterface
      */
     public function then(callable $onFulfilled = null, callable $onRejected = null);
 
     /**
+     * Consumes the promise's ultimate value if the promise fulfills, or handles the
+     * ultimate error.
+     *
+     * It will cause a fatal error (`E_USER_ERROR`) if either `$onFulfilled` or
+     * `$onRejected` throw or return a rejected promise.
+     *
+     * Since the purpose of `done()` is consumption rather than transformation,
+     * `done()` always returns `null`.
+     *
+     * @param callable|null $onFulfilled
+     * @param callable|null $onRejected
      * @return void
      */
     public function done(callable $onFulfilled = null, callable $onRejected = null);
 
     /**
+     * Registers a rejection handler for promise. It is a shortcut for:
+     *
+     * ```php
+     * $promise->then(null, $onRejected);
+     * ```
+     *
+     * Additionally, you can type hint the `$reason` argument of `$onRejected` to catch
+     * only specific errors.
+     *
+     * @param callable $onRejected
      * @return PromiseInterface
      */
     public function otherwise(callable $onRejected);
 
     /**
+     * Allows you to execute "cleanup" type tasks in a promise chain.
+     *
+     * It arranges for `$onFulfilledOrRejected` to be called, with no arguments,
+     * when the promise is either fulfilled or rejected.
+     *
+     * * If `$promise` fulfills, and `$onFulfilledOrRejected` returns successfully,
+     *    `$newPromise` will fulfill with the same value as `$promise`.
+     * * If `$promise` fulfills, and `$onFulfilledOrRejected` throws or returns a
+     *    rejected promise, `$newPromise` will reject with the thrown exception or
+     *    rejected promise's reason.
+     * * If `$promise` rejects, and `$onFulfilledOrRejected` returns successfully,
+     *    `$newPromise` will reject with the same reason as `$promise`.
+     * * If `$promise` rejects, and `$onFulfilledOrRejected` throws or returns a
+     *    rejected promise, `$newPromise` will reject with the thrown exception or
+     *    rejected promise's reason.
+     *
+     * `always()` behaves similarly to the synchronous finally statement. When combined
+     * with `otherwise()`, `always()` allows you to write code that is similar to the familiar
+     * synchronous catch/finally pair.
+     *
+     * Consider the following synchronous code:
+     *
+     * ```php
+     * try {
+     *     return doSomething();
+     * } catch(\Exception $e) {
+     *     return handleError($e);
+     * } finally {
+     *     cleanup();
+     * }
+     * ```
+     *
+     * Similar asynchronous code (with `doSomething()` that returns a promise) can be
+     * written:
+     *
+     * ```php
+     * return doSomething()
+     *     ->otherwise('handleError')
+     *     ->always('cleanup');
+     * ```
+     *
+     * @param callable $onFulfilledOrRejected
      * @return PromiseInterface
      */
     public function always(callable $onFulfilledOrRejected);
 
     /**
+     * The `cancel()` method notifies the creator of the promise that there is no
+     * 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.
+     *
      * @return void
      */
     public function cancel();

src/PromisorInterface.php

@@ -5,6 +5,8 @@
 interface PromisorInterface
 {
     /**
+     * Returns the promise of the deferred.
+     *
      * @return PromiseInterface
      */
     public function promise();