[4.x] Add PHPStan to test environment with max level

.gitattributes

@@ -1,5 +1,6 @@
 /.gitattributes export-ignore
 /.github/ export-ignore
 /.gitignore export-ignore
+/phpstan.neon.dist export-ignore
 /phpunit.xml.dist export-ignore
 /tests/ export-ignore

.github/workflows/ci.yml

@@ -22,3 +22,20 @@ jobs:
           ini-file: development
       - run: composer install
       - run: vendor/bin/phpunit --coverage-text
+
+  PHPStan:
+    name: PHPStan (PHP ${{ matrix.php }})
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        php:
+          - 8.2
+          - 8.1
+    steps:
+      - uses: actions/checkout@v3
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+      - run: composer install
+      - run: vendor/bin/phpstan

README.md

@@ -659,6 +659,12 @@ To run the test suite, go to the project root and run:
 vendor/bin/phpunit
 ```
 
+On top of this, we use PHPStan on max level to ensure type safety across the project:
+
+```bash
+vendor/bin/phpstan
+```
+
 ## License
 
 MIT, see [LICENSE file](LICENSE).

composer.json

@@ -31,6 +31,7 @@
         "react/promise": "^3.0 || ^2.8 || ^1.2.1"
     },
     "require-dev": {
+        "phpstan/phpstan": "1.10.18",
         "phpunit/phpunit": "^9.5"
     },
     "autoload": {

phpstan.neon.dist

@@ -0,0 +1,11 @@
+parameters:
+    level: max
+
+    paths:
+        - src/
+        - tests/
+
+    reportUnmatchedIgnoredErrors: false
+    ignoreErrors:
+        # ignore generic usage like `PromiseInterface<T>` until fixed upstream
+        - '/^PHPDoc .* contains generic type React\\Promise\\PromiseInterface<.+> but interface React\\Promise\\PromiseInterface is not generic\.$/'

src/FiberMap.php

@@ -9,35 +9,43 @@
  */
 final class FiberMap
 {
+    /** @var array<int,bool> */
     private static array $status = [];
-    private static array $map   = [];
 
+    /** @var array<int,PromiseInterface> */
+    private static array $map = [];
+
+    /** @param \Fiber<mixed,mixed,mixed,mixed> $fiber */
     public static function register(\Fiber $fiber): void
     {
         self::$status[\spl_object_id($fiber)] = false;
-        self::$map[\spl_object_id($fiber)] = [];
     }
 
+    /** @param \Fiber<mixed,mixed,mixed,mixed> $fiber */
     public static function cancel(\Fiber $fiber): void
     {
         self::$status[\spl_object_id($fiber)] = true;
     }
 
+    /** @param \Fiber<mixed,mixed,mixed,mixed> $fiber */
     public static function setPromise(\Fiber $fiber, PromiseInterface $promise): void
     {
         self::$map[\spl_object_id($fiber)] = $promise;
     }
 
+    /** @param \Fiber<mixed,mixed,mixed,mixed> $fiber */
     public static function unsetPromise(\Fiber $fiber, PromiseInterface $promise): void
     {
         unset(self::$map[\spl_object_id($fiber)]);
     }
 
+    /** @param \Fiber<mixed,mixed,mixed,mixed> $fiber */
     public static function getPromise(\Fiber $fiber): ?PromiseInterface
     {
         return self::$map[\spl_object_id($fiber)] ?? null;
     }
 
+    /** @param \Fiber<mixed,mixed,mixed,mixed> $fiber */
     public static function unregister(\Fiber $fiber): void
     {
         unset(self::$status[\spl_object_id($fiber)], self::$map[\spl_object_id($fiber)]);

src/SimpleFiber.php

@@ -9,8 +9,12 @@
  */
 final class SimpleFiber implements FiberInterface
 {
+    /** @var ?\Fiber<void,void,void,callable(): mixed> */
     private static ?\Fiber $scheduler = null;
+
     private static ?\Closure $suspend = null;
+
+    /** @var ?\Fiber<mixed,mixed,mixed,mixed> */
     private ?\Fiber $fiber = null;
 
     public function __construct()
@@ -57,13 +61,17 @@ public function suspend(): mixed
                 self::$scheduler = new \Fiber(static fn() => Loop::run());
                 // Run event loop to completion on shutdown.
                 \register_shutdown_function(static function (): void {
+                    assert(self::$scheduler instanceof \Fiber);
                     if (self::$scheduler->isSuspended()) {
                         self::$scheduler->resume();
                     }
                 });
             }
 
-            return (self::$scheduler->isStarted() ? self::$scheduler->resume() : self::$scheduler->start())();
+            $ret = (self::$scheduler->isStarted() ? self::$scheduler->resume() : self::$scheduler->start());
+            assert(\is_callable($ret));
+
+            return $ret();
         }
 
         return \Fiber::suspend();

src/functions.php

@@ -176,8 +176,8 @@
  * await($promise);
  * ```
  *
- * @param callable(mixed ...$args):mixed $function
- * @return callable(): PromiseInterface<mixed>
+ * @param callable $function
+ * @return callable(mixed ...): PromiseInterface<mixed>
  * @since 4.0.0
  * @see coroutine()
  */
@@ -192,6 +192,7 @@ function async(callable $function): callable
                 } catch (\Throwable $exception) {
                     $reject($exception);
                 } finally {
+                    assert($fiber instanceof \Fiber);
                     FiberMap::unregister($fiber);
                 }
             });
@@ -200,6 +201,7 @@ function async(callable $function): callable
 
             $fiber->start();
         }, function () use (&$fiber): void {
+            assert($fiber instanceof \Fiber);
             FiberMap::cancel($fiber);
             $promise = FiberMap::getPromise($fiber);
             if ($promise instanceof PromiseInterface && \method_exists($promise, 'cancel')) {
@@ -287,6 +289,7 @@ function (mixed $value) use (&$resolved, &$resolvedValue, &$fiber, $lowLevelFibe
                 FiberMap::unsetPromise($lowLevelFiber, $promise);
             }
 
+            /** @var ?\Fiber<mixed,mixed,mixed,mixed> $fiber */
             if ($fiber === null) {
                 $resolved = true;
                 $resolvedValue = $value;
@@ -309,6 +312,7 @@ function (mixed $throwable) use (&$rejected, &$rejectedThrowable, &$fiber, $lowL
                 // what a lovely piece of code!
                 $r = new \ReflectionProperty('Exception', 'trace');
                 $trace = $r->getValue($throwable);
+                assert(\is_array($trace));
 
                 // Exception trace arguments only available when zend.exception_ignore_args is not set
                 // @codeCoverageIgnoreStart
@@ -340,6 +344,7 @@ function (mixed $throwable) use (&$rejected, &$rejectedThrowable, &$fiber, $lowL
     }
 
     if ($rejected) {
+        assert($rejectedThrowable instanceof \Throwable);
         throw $rejectedThrowable;
     }
 
@@ -587,7 +592,7 @@ function delay(float $seconds): void
  * });
  * ```
  *
- * @param callable(...$args):\Generator<mixed,PromiseInterface,mixed,mixed> $function
+ * @param callable(mixed ...$args):(\Generator<mixed,PromiseInterface,mixed,mixed>|mixed) $function
  * @param mixed ...$args Optional list of additional arguments that will be passed to the given `$function` as is
  * @return PromiseInterface<mixed>
  * @since 3.0.0
@@ -606,6 +611,7 @@ function coroutine(callable $function, mixed ...$args): PromiseInterface
 
     $promise = null;
     $deferred = new Deferred(function () use (&$promise) {
+        /** @var ?PromiseInterface $promise */
         if ($promise instanceof PromiseInterface && \method_exists($promise, 'cancel')) {
             $promise->cancel();
         }
@@ -626,6 +632,7 @@ function coroutine(callable $function, mixed ...$args): PromiseInterface
             return;
         }
 
+        /** @var mixed $promise */
         $promise = $generator->current();
         if (!$promise instanceof PromiseInterface) {
             $next = null;
@@ -635,6 +642,7 @@ function coroutine(callable $function, mixed ...$args): PromiseInterface
             return;
         }
 
+        assert($next instanceof \Closure);
         $promise->then(function ($value) use ($generator, $next) {
             $generator->send($value);
             $next();
@@ -657,6 +665,7 @@ function coroutine(callable $function, mixed ...$args): PromiseInterface
  */
 function parallel(iterable $tasks): PromiseInterface
 {
+    /** @var array<int,PromiseInterface> $pending */
     $pending = [];
     $deferred = new Deferred(function () use (&$pending) {
         foreach ($pending as $promise) {
@@ -718,6 +727,7 @@ function series(iterable $tasks): PromiseInterface
 {
     $pending = null;
     $deferred = new Deferred(function () use (&$pending) {
+        /** @var ?PromiseInterface $pending */
         if ($pending instanceof PromiseInterface && \method_exists($pending, 'cancel')) {
             $pending->cancel();
         }
@@ -730,9 +740,9 @@ function series(iterable $tasks): PromiseInterface
         assert($tasks instanceof \Iterator);
     }
 
-    /** @var callable():void $next */
     $taskCallback = function ($result) use (&$results, &$next) {
         $results[] = $result;
+        /** @var \Closure $next */
         $next();
     };
 
@@ -746,9 +756,11 @@ function series(iterable $tasks): PromiseInterface
             $task = $tasks->current();
             $tasks->next();
         } else {
+            assert(\is_array($tasks));
             $task = \array_shift($tasks);
         }
 
+        assert(\is_callable($task));
         $promise = \call_user_func($task);
         assert($promise instanceof PromiseInterface);
         $pending = $promise;
@@ -762,13 +774,14 @@ function series(iterable $tasks): PromiseInterface
 }
 
 /**
- * @param iterable<callable(mixed=):PromiseInterface<mixed>> $tasks
+ * @param iterable<(callable():PromiseInterface<mixed>)|(callable(mixed):PromiseInterface<mixed>)> $tasks
  * @return PromiseInterface<mixed>
  */
 function waterfall(iterable $tasks): PromiseInterface
 {
     $pending = null;
     $deferred = new Deferred(function () use (&$pending) {
+        /** @var ?PromiseInterface $pending */
         if ($pending instanceof PromiseInterface && \method_exists($pending, 'cancel')) {
             $pending->cancel();
         }
@@ -791,9 +804,11 @@ function waterfall(iterable $tasks): PromiseInterface
             $task = $tasks->current();
             $tasks->next();
         } else {
+            assert(\is_array($tasks));
             $task = \array_shift($tasks);
         }
 
+        assert(\is_callable($task));
         $promise = \call_user_func_array($task, func_get_args());
         assert($promise instanceof PromiseInterface);
         $pending = $promise;