[2.x] Add template annotations

Author: WyriHaximus

.github/workflows/ci.yml

@@ -45,3 +45,16 @@ jobs:
       - run: composer self-update --2.2 # downgrade Composer for HHVM
       - run: hhvm $(which composer) install
       - run: hhvm vendor/bin/phpunit
+
+  static-analysis:
+    name: PHPStan
+    runs-on: ubuntu-20.04
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v3
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.1
+      - run: composer require phpstan/phpstan
+      - name: Execute type checking
+        run: vendor/bin/phpstan --configuration="phpstan.types.neon.dist"

composer.json

@@ -25,7 +25,8 @@
         }
     ],
     "require": {
-        "php": ">=5.4.0"
+        "php": ">=5.4.0",
+        "phpstan/phpstan": "^1.7"
     },
     "require-dev": {
         "phpunit/phpunit": "^9.3 || ^5.7 || ^4.8.36"

phpstan.types.neon.dist

@@ -0,0 +1,4 @@
+parameters:
+  paths:
+    - types
+  level: max

src/ExtendedPromiseInterface.php

@@ -2,6 +2,7 @@
 
 namespace React\Promise;
 
+/** @template T */
 interface ExtendedPromiseInterface extends PromiseInterface
 {
     /**
@@ -78,8 +79,9 @@ public function otherwise(callable $onRejected);
      *     ->always('cleanup');
      * ```
      *
-     * @param callable $onFulfilledOrRejected
-     * @return ExtendedPromiseInterface
+     * @template TReturn of mixed
+     * @param callable(T): TReturn $onFulfilledOrRejected
+     * @return (TReturn is ExtendedPromiseInterface ? TReturn : ExtendedPromiseInterface<TReturn>)
      */
     public function always(callable $onFulfilledOrRejected);
 

src/FulfilledPromise.php

@@ -4,11 +4,16 @@
 
 /**
  * @deprecated 2.8.0 External usage of FulfilledPromise is deprecated, use `resolve()` instead.
+ * @template T
+ * @template-implements PromiseInterface<T>
  */
 class FulfilledPromise implements ExtendedPromiseInterface, CancellablePromiseInterface
 {
     private $value;
 
+    /**
+     * @param T $value
+     */
     public function __construct($value = null)
     {
         if ($value instanceof PromiseInterface) {
@@ -18,6 +23,9 @@ public function __construct($value = null)
         $this->value = $value;
     }
 
+    /**
+     * @inheritDoc
+     */
     public function then(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null)
     {
         if (null === $onFulfilled) {

src/Promise.php

@@ -2,9 +2,15 @@
 
 namespace React\Promise;
 
+/**
+ * @template F
+ * @template R
+ * @template-implements PromiseInterface<F|R>
+ */
 class Promise implements ExtendedPromiseInterface, CancellablePromiseInterface
 {
     private $canceller;
+    /** @var F */
     private $result;
 
     private $handlers = [];
@@ -25,6 +31,9 @@ public function __construct(callable $resolver, callable $canceller = null)
         $this->call($cb);
     }
 
+    /**
+     * @inheritDoc
+     */
     public function then(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null)
     {
         if (null !== $this->result) {

src/PromiseInterface.php

@@ -2,6 +2,10 @@
 
 namespace React\Promise;
 
+/**
+ * @template F
+ * @template R
+ */
 interface PromiseInterface
 {
     /**
@@ -32,10 +36,15 @@ interface PromiseInterface
      *      than once.
      *  3. `$onProgress` (deprecated) may be called multiple times.
      *
-     * @param callable|null $onFulfilled
-     * @param callable|null $onRejected
-     * @param callable|null $onProgress This argument is deprecated and should not be used anymore.
-     * @return PromiseInterface
+     * @template TFulfilled of mixed
+     * @template TRejected of mixed
+     * @param (callable(F): (PromiseInterface<TFulfilled>|TFulfilled))|null $onFulfilled
+     * @param (callable(R): (PromiseInterface<TRejected>|TRejected))|null $onRejected
+     * @return PromiseInterface<(
+     *   $onFulfilled is not null
+     *     ? ($onRejected is not null ? TFulfilled|TRejected : TFulfilled)
+     *     : ($onRejected is not null ? TRejected : F)
+     * )>
      */
     public function then(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null);
 }

src/functions.php

@@ -13,8 +13,9 @@
  *
  * If `$promiseOrValue` is a promise, it will be returned as is.
  *
- * @param mixed $promiseOrValue
- * @return PromiseInterface
+ * @template T
+ * @param T $promiseOrValue
+ * @return PromiseInterface<T>
  */
 function resolve($promiseOrValue = null)
 {
@@ -72,8 +73,9 @@ function reject($promiseOrValue = null)
  * will be an array containing the resolution values of each of the items in
  * `$promisesOrValues`.
  *
- * @param array $promisesOrValues
- * @return PromiseInterface
+ * @template T
+ * @param array<PromiseInterface<T>|T> $promisesOrValues
+ * @return PromiseInterface<array<T>>
  */
 function all($promisesOrValues)
 {
@@ -89,8 +91,9 @@ function all($promisesOrValues)
  * The returned promise will become **infinitely pending** if  `$promisesOrValues`
  * contains 0 items.
  *
- * @param array $promisesOrValues
- * @return PromiseInterface
+ * @template T
+ * @param array<PromiseInterface<T>|T> $promisesOrValues
+ * @return PromiseInterface<T>
  */
 function race($promisesOrValues)
 {
@@ -126,8 +129,9 @@ function race($promisesOrValues)
  * The returned promise will also reject with a `React\Promise\Exception\LengthException`
  * if `$promisesOrValues` contains 0 items.
  *
- * @param array $promisesOrValues
- * @return PromiseInterface
+ * @template T
+ * @param array<PromiseInterface<T>|T> $promisesOrValues
+ * @return PromiseInterface<T>
  */
 function any($promisesOrValues)
 {
@@ -151,9 +155,10 @@ function any($promisesOrValues)
  * The returned promise will also reject with a `React\Promise\Exception\LengthException`
  * if `$promisesOrValues` contains less items than `$howMany`.
  *
- * @param array $promisesOrValues
+ * @template T
+ * @param array<PromiseInterface<T>|T> $promisesOrValues
  * @param int $howMany
- * @return PromiseInterface
+ * @return PromiseInterface<array<T>>
  */
 function some($promisesOrValues, $howMany)
 {
@@ -228,9 +233,10 @@ function some($promisesOrValues, $howMany)
  * The map function receives each item as argument, where item is a fully resolved
  * value of a promise or value in `$promisesOrValues`.
  *
- * @param array $promisesOrValues
- * @param callable $mapFunc
- * @return PromiseInterface
+ * @template T
+ * @param array<PromiseInterface<T>|T> $promisesOrValues
+ * @param callable(): T $mapFunc
+ * @return PromiseInterface<array<T>>
  */
 function map($promisesOrValues, callable $mapFunc)
 {
@@ -276,10 +282,11 @@ function ($mapped) use ($i, &$values, &$toResolve, $resolve) {
  * promise, *and* `$initialValue` may be a promise or a value for the starting
  * value.
  *
- * @param array $promisesOrValues
- * @param callable $reduceFunc
+ * @template T
+ * @param array<PromiseInterface<T>|T> $promisesOrValues
+ * @param callable(T): bool $reduceFunc
  * @param mixed $initialValue
- * @return PromiseInterface
+ * @return PromiseInterface<array<T>>
  */
 function reduce($promisesOrValues, callable $reduceFunc, $initialValue = null)
 {

types/Promises.php

@@ -0,0 +1,40 @@
+<?php
+
+use React\Promise\FulfilledPromise;
+use React\Promise\PromiseInterface;
+use Throwable;
+
+use function PHPStan\Testing\assertType;
+use function React\Promise\all;
+use function React\Promise\race;
+use function React\Promise\reject;
+use function React\Promise\resolve;
+
+$passThroughBoolFn = static fn (bool $bool): bool => $bool;
+$passThroughThrowable = static function (Throwable $t): PromiseInterface {
+    return reject($t);
+};
+$tosseable = new Exception('Oops I did it again!');
+
+assertType('React\Promise\PromiseInterface<bool>', resolve(true));
+assertType('React\Promise\PromiseInterface<array<bool>>', all([resolve(true), resolve(false)]));
+assertType('React\Promise\PromiseInterface<array<bool>>', all([resolve(true), false]));
+assertType('React\Promise\PromiseInterface<array<bool|int>>', all([resolve(true), resolve(time())]));
+assertType('React\Promise\PromiseInterface<array<bool|int>>', all([resolve(true), time()]));
+assertType('React\Promise\PromiseInterface<array<bool|int>>', all([true, resolve(time())]));
+assertType('React\Promise\PromiseInterface<bool>', race([resolve(true), resolve(true)]));
+assertType('React\Promise\PromiseInterface<bool>', resolve(true)->then($passThroughBoolFn));
+assertType('React\Promise\PromiseInterface<bool>', resolve(true)->then()->then($passThroughBoolFn));
+assertType('React\Promise\PromiseInterface<bool>', resolve(true)->then(null)->then($passThroughBoolFn));
+assertType('React\Promise\PromiseInterface<bool>', resolve(true)->then($passThroughBoolFn)->then($passThroughBoolFn));
+assertType('React\Promise\PromiseInterface<bool>', resolve(true)->then($passThroughBoolFn, $passThroughThrowable)->then($passThroughBoolFn));
+assertType('React\Promise\PromiseInterface<bool>', resolve(true)->then(null, $passThroughThrowable)->then($passThroughBoolFn));
+assertType('React\Promise\PromiseInterface<bool>', resolve(true)->then()->then(null, $passThroughThrowable)->then($passThroughBoolFn));
+assertType('React\Promise\FulfilledPromise<bool>', new FulfilledPromise(true));
+assertType('React\Promise\PromiseInterface<bool>', (new FulfilledPromise(true))->then($passThroughBoolFn));
+
+assertType('React\Promise\PromiseInterface<Throwable>', reject($tosseable));
+assertType('React\Promise\PromiseInterface<Throwable>', reject($tosseable)->then($passThroughBoolFn, $passThroughThrowable));
+assertType('React\Promise\PromiseInterface<Throwable>', reject($tosseable)->then()->then($passThroughBoolFn, $passThroughThrowable));
+assertType('React\Promise\PromiseInterface<Throwable>', reject($tosseable)->then(null, $passThroughThrowable));
+assertType('React\Promise\PromiseInterface<Throwable>', reject($tosseable)->then()->then(null, $passThroughThrowable));