[3.x] Add template annotations

Adds template annotations turning the `PromiseInterface` into a generic.

Variables `$p1` and `$p2` in the following code example both are `PromiseInterface<int|string>`.

```php
$f = function (): int|string {
    return time() % 2 ? 'string' : time();
};

/**
 * @return PromiseInterface<int|string>
 */
$fp = function (): PromiseInterface {
    return resolve(time() % 2 ? 'string' : time());
};

$p1 = resolve($f());
$p2 = $fp();
```

When calling `then` on `$p1` or `$p2`, PHPStan understand that function `$f1` is type hinting its parameter fine, but `$f2` will throw during runtime:

```php
$p2->then(static function (int|string $a) {});
$p2->then(static function (bool $a) {});
```

Builds on top of #246 and #188 and is a requirement for reactphp/async#40

Author: simPod

.github/workflows/ci.yml

@@ -52,3 +52,6 @@ jobs:
           coverage: none
       - run: composer install
       - run: vendor/bin/phpstan
+        if: ${{ matrix.php >= 7.2 }}
+      - run: vendor/bin/phpstan --configuration="phpstan.legacy.neon.dist"
+        if: ${{ matrix.php < 7.2 }}

phpstan.legacy.neon.dist

@@ -0,0 +1,7 @@
+parameters:
+	ignoreErrors:
+		- '#Template type T is declared as covariant, but occurs in contravariant position in parameter result of method React\\Promise\\Promise::settle\(\).#'
+		- '#Template type T is declared as covariant, but occurs in contravariant position in parameter promise of method React\\Promise\\Promise::unwrap\(\).#'
+
+includes:
+	- phpstan.neon.dist

phpstan.neon.dist

@@ -4,3 +4,4 @@ parameters:
     paths:
         - src/
         - tests/
+        - types/

src/Deferred.php

@@ -2,9 +2,14 @@
 
 namespace React\Promise;
 
+/**
+ * @template-covariant  T
+ */
 final class Deferred
 {
-    /** @var Promise */
+    /**
+     * @var PromiseInterface<T>
+     */
     private $promise;
 
     /** @var callable */
@@ -21,6 +26,9 @@ public function __construct(callable $canceller = null)
         }, $canceller);
     }
 
+    /**
+     * @return PromiseInterface<T>
+     */
     public function promise(): PromiseInterface
     {
         return $this->promise;

src/Internal/FulfilledPromise.php

@@ -7,14 +7,17 @@
 
 /**
  * @internal
+ *
+ * @template-implements PromiseInterface<T>
+ * @template-covariant T
  */
 final class FulfilledPromise implements PromiseInterface
 {
-    /** @var mixed */
+    /** @var T */
     private $value;
 
     /**
-     * @param mixed $value
+     * @param T $value
      * @throws \InvalidArgumentException
      */
     public function __construct($value = null)

src/Internal/RejectedPromise.php

@@ -8,6 +8,9 @@
 
 /**
  * @internal
+ *
+ * @template-implements PromiseInterface<T>
+ * @template-covariant T
  */
 final class RejectedPromise implements PromiseInterface
 {

src/Promise.php

@@ -4,12 +4,16 @@
 
 use React\Promise\Internal\RejectedPromise;
 
+/**
+ * @template-implements PromiseInterface<T>
+ * @template-covariant T
+ */
 final class Promise implements PromiseInterface
 {
     /** @var ?callable */
     private $canceller;
 
-    /** @var ?PromiseInterface */
+    /** @var PromiseInterface<T> */
     private $result;
 
     /** @var callable[] */
@@ -77,11 +81,11 @@ public function catch(callable $onRejected): PromiseInterface
     public function finally(callable $onFulfilledOrRejected): PromiseInterface
     {
         return $this->then(static function ($value) use ($onFulfilledOrRejected) {
-            return resolve($onFulfilledOrRejected())->then(function () use ($value) {
+            return resolve($onFulfilledOrRejected())->then(function ($_) use ($value) {
                 return $value;
             });
         }, static function ($reason) use ($onFulfilledOrRejected) {
-            return resolve($onFulfilledOrRejected())->then(function () use ($reason) {
+            return resolve($onFulfilledOrRejected())->then(function ($_) use ($reason) {
                 return new RejectedPromise($reason);
             });
         });
@@ -166,6 +170,9 @@ private function reject(\Throwable $reason): void
         $this->settle(reject($reason));
     }
 
+    /**
+     * @param PromiseInterface<T>|PromiseInterface<null> $result
+     */
     private function settle(PromiseInterface $result): void
     {
         $result = $this->unwrap($result);
@@ -193,13 +200,17 @@ private function settle(PromiseInterface $result): void
         }
     }
 
+    /**
+     * @param PromiseInterface<T>|PromiseInterface<null> $promise
+     * @return PromiseInterface<T>
+     */
     private function unwrap(PromiseInterface $promise): PromiseInterface
     {
         while ($promise instanceof self && null !== $promise->result) {
             $promise = $promise->result;
         }
 
-        return $promise;
+        return $promise; /** @phpstan-ignore-line */
     }
 
     private function call(callable $cb): void

src/PromiseInterface.php

@@ -2,6 +2,9 @@
 
 namespace React\Promise;
 
+/**
+ * @template-covariant T
+ */
 interface PromiseInterface
 {
     /**
@@ -28,9 +31,9 @@ interface PromiseInterface
      *  2. `$onFulfilled` and `$onRejected` will never be called more
      *      than once.
      *
-     * @param callable|null $onFulfilled
-     * @param callable|null $onRejected
-     * @return PromiseInterface
+     * @template TFulfilled as PromiseInterface<T>|T
+     * @param (callable(T): TFulfilled)|null $onFulfilled
+     * @return PromiseInterface<T>
      */
     public function then(?callable $onFulfilled = null, ?callable $onRejected = null): PromiseInterface;
 
@@ -44,8 +47,7 @@ public function then(?callable $onFulfilled = null, ?callable $onRejected = null
      * Additionally, you can type hint the `$reason` argument of `$onRejected` to catch
      * only specific errors.
      *
-     * @param callable $onRejected
-     * @return PromiseInterface
+     * @return PromiseInterface<T>
      */
     public function catch(callable $onRejected): PromiseInterface;
 
@@ -91,8 +93,9 @@ public function catch(callable $onRejected): PromiseInterface;
      *     ->finally('cleanup');
      * ```
      *
-     * @param callable $onFulfilledOrRejected
-     * @return PromiseInterface
+     * @template TReturn of PromiseInterface<T>|T
+     * @param callable(T=): TReturn $onFulfilledOrRejected
+     * @return PromiseInterface<T>
      */
     public function finally(callable $onFulfilledOrRejected): PromiseInterface;
 
@@ -118,7 +121,7 @@ public function cancel(): void;
      * ```
      *
      * @param callable $onRejected
-     * @return PromiseInterface
+     * @return PromiseInterface<T>
      * @deprecated 3.0.0 Use catch() instead
      * @see self::catch()
      */
@@ -135,7 +138,7 @@ public function otherwise(callable $onRejected): PromiseInterface;
      * ```
      *
      * @param callable $onFulfilledOrRejected
-     * @return PromiseInterface
+     * @return PromiseInterface<T>
      * @deprecated 3.0.0 Use finally() instead
      * @see self::finally()
      */

src/functions.php

@@ -17,8 +17,9 @@
  *
  * If `$promiseOrValue` is a promise, it will be returned as is.
  *
- * @param mixed $promiseOrValue
- * @return PromiseInterface
+ * @template T
+ * @param PromiseInterface<T>|T $promiseOrValue
+ * @return PromiseInterface<T>
  */
 function resolve($promiseOrValue): PromiseInterface
 {
@@ -30,6 +31,7 @@ function resolve($promiseOrValue): PromiseInterface
         $canceller = null;
 
         if (\method_exists($promiseOrValue, 'cancel')) {
+            /** @var callable $canceller */
             $canceller = [$promiseOrValue, 'cancel'];
         }
 
@@ -54,8 +56,7 @@ function resolve($promiseOrValue): PromiseInterface
  * throwing an exception. For example, it allows you to propagate a rejection with
  * the value of another promise.
  *
- * @param \Throwable $reason
- * @return PromiseInterface
+ * @return PromiseInterface<null>
  */
 function reject(\Throwable $reason): PromiseInterface
 {
@@ -68,8 +69,9 @@ function reject(\Throwable $reason): PromiseInterface
  * will be an array containing the resolution values of each of the items in
  * `$promisesOrValues`.
  *
- * @param iterable<mixed> $promisesOrValues
- * @return PromiseInterface
+ * @template T
+ * @param iterable<PromiseInterface<T>|T> $promisesOrValues
+ * @return PromiseInterface<array<T>>
  */
 function all(iterable $promisesOrValues): PromiseInterface
 {
@@ -87,7 +89,7 @@ function all(iterable $promisesOrValues): PromiseInterface
             ++$toResolve;
 
             resolve($promiseOrValue)->then(
-                function ($value) use ($i, &$values, &$toResolve, &$continue, $resolve): void {
+                function ($value) use ($i, &$values, &$toResolve, &$continue, $resolve): void { /** @phpstan-ignore-line */
                     $values[$i] = $value;
 
                     if (0 === --$toResolve && !$continue) {
@@ -119,8 +121,9 @@ function (\Throwable $reason) use (&$continue, $reject): void {
  * The returned promise will become **infinitely pending** if  `$promisesOrValues`
  * contains 0 items.
  *
- * @param iterable<mixed> $promisesOrValues
- * @return PromiseInterface
+ * @template T
+ * @param iterable<PromiseInterface<T>|T> $promisesOrValues
+ * @return PromiseInterface<T>
  */
 function race(iterable $promisesOrValues): PromiseInterface
 {
@@ -132,7 +135,7 @@ function race(iterable $promisesOrValues): PromiseInterface
         foreach ($promisesOrValues as $promiseOrValue) {
             $cancellationQueue->enqueue($promiseOrValue);
 
-            resolve($promiseOrValue)->then($resolve, $reject)->finally(function () use (&$continue): void {
+            resolve($promiseOrValue)->then($resolve, $reject)->finally(function () use (&$continue): void { /** @phpstan-ignore-line */
                 $continue = false;
             });
 
@@ -154,8 +157,9 @@ function race(iterable $promisesOrValues): PromiseInterface
  * The returned promise will also reject with a `React\Promise\Exception\LengthException`
  * if `$promisesOrValues` contains 0 items.
  *
- * @param iterable<mixed> $promisesOrValues
- * @return PromiseInterface
+ * @template T
+ * @param iterable<PromiseInterface<T>|T> $promisesOrValues
+ * @return PromiseInterface<T>
  */
 function any(iterable $promisesOrValues): PromiseInterface
 {
@@ -171,7 +175,7 @@ function any(iterable $promisesOrValues): PromiseInterface
             ++$toReject;
 
             resolve($promiseOrValue)->then(
-                function ($value) use ($resolve, &$continue): void {
+                function ($value) use ($resolve, &$continue): void { /** @phpstan-ignore-line */
                     $continue = false;
                     $resolve($value);
                 },

tests/FunctionAllTest.php

@@ -9,9 +9,9 @@ class FunctionAllTest extends TestCase
     /** @test */
     public function shouldResolveEmptyInput(): void
     {
-        $mock = $this->createCallableMock();
-        $mock
-            ->expects(self::once())
+        /** @var callable $mock */
+        $mock = $_ = $this->createCallableMock();
+        $_->expects(self::once())
             ->method('__invoke')
             ->with(self::identicalTo([]));
 
@@ -22,9 +22,9 @@ public function shouldResolveEmptyInput(): void
     /** @test */
     public function shouldResolveValuesArray(): void
     {
-        $mock = $this->createCallableMock();
-        $mock
-            ->expects(self::once())
+        /** @var callable $mock */
+        $mock = $_ = $this->createCallableMock();
+        $_->expects(self::once())
             ->method('__invoke')
             ->with(self::identicalTo([1, 2, 3]));
 
@@ -35,9 +35,9 @@ public function shouldResolveValuesArray(): void
     /** @test */
     public function shouldResolvePromisesArray(): void
     {
-        $mock = $this->createCallableMock();
-        $mock
-            ->expects(self::once())
+        /** @var callable $mock */
+        $mock = $_ = $this->createCallableMock();
+        $_->expects(self::once())
             ->method('__invoke')
             ->with(self::identicalTo([1, 2, 3]));
 
@@ -48,9 +48,9 @@ public function shouldResolvePromisesArray(): void
     /** @test */
     public function shouldResolveSparseArrayInput(): void
     {
-        $mock = $this->createCallableMock();
-        $mock
-            ->expects(self::once())
+        /** @var callable $mock */
+        $mock = $_ = $this->createCallableMock();
+        $_->expects(self::once())
             ->method('__invoke')
             ->with(self::identicalTo([null, 1, null, 1, 1]));
 
@@ -61,9 +61,9 @@ public function shouldResolveSparseArrayInput(): void
     /** @test */
     public function shouldResolveValuesGenerator(): void
     {
-        $mock = $this->createCallableMock();
-        $mock
-            ->expects(self::once())
+        /** @var callable $mock */
+        $mock = $_ = $this->createCallableMock();
+        $_->expects(self::once())
             ->method('__invoke')
             ->with(self::identicalTo([1, 2, 3]));
 
@@ -79,9 +79,9 @@ public function shouldResolveValuesGenerator(): void
     /** @test */
     public function shouldResolveValuesGeneratorEmpty(): void
     {
-        $mock = $this->createCallableMock();
-        $mock
-            ->expects(self::once())
+        /** @var callable $mock */
+        $mock = $_ = $this->createCallableMock();
+        $_->expects(self::once())
             ->method('__invoke')
             ->with(self::identicalTo([]));
 
@@ -131,9 +131,9 @@ public function shouldRejectInfiteGeneratorOrRejectedPromises(): void
     /** @test */
     public function shouldPreserveTheOrderOfArrayWhenResolvingAsyncPromises(): void
     {
-        $mock = $this->createCallableMock();
-        $mock
-            ->expects(self::once())
+        /** @var callable $mock */
+        $mock = $_ = $this->createCallableMock();
+        $_->expects(self::once())
             ->method('__invoke')
             ->with(self::identicalTo([1, 2, 3]));