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

.gitattributes

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

.github/workflows/ci.yml

@@ -30,3 +30,25 @@ jobs:
         if: ${{ matrix.php >= 7.3 }}
       - run: vendor/bin/phpunit --coverage-text -c phpunit.xml.legacy
         if: ${{ matrix.php < 7.3 }}
+
+  PHPStan:
+    name: PHPStan (PHP ${{ matrix.php }})
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        php:
+          - 8.2
+          - 8.1
+          - 8.0
+          - 7.4
+          - 7.3
+          - 7.2
+          - 7.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

@@ -426,6 +426,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 || 1.4.10",
         "phpunit/phpunit": "^9.5 || ^7.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/functions.php

@@ -56,6 +56,8 @@ function await(PromiseInterface $promise)
     $resolved = null;
     $exception = null;
     $rejected = false;
+
+    /** @var bool $loopStarted */
     $loopStarted = false;
 
     $promise->then(
@@ -294,7 +296,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
@@ -313,6 +315,7 @@ function coroutine(callable $function, ...$args): PromiseInterface
 
     $promise = null;
     $deferred = new Deferred(function () use (&$promise) {
+        /** @var ?PromiseInterface $promise */
         if ($promise instanceof PromiseInterface && \method_exists($promise, 'cancel')) {
             $promise->cancel();
         }
@@ -333,6 +336,7 @@ function coroutine(callable $function, ...$args): PromiseInterface
             return;
         }
 
+        /** @var mixed $promise */
         $promise = $generator->current();
         if (!$promise instanceof PromiseInterface) {
             $next = null;
@@ -342,6 +346,7 @@ function coroutine(callable $function, ...$args): PromiseInterface
             return;
         }
 
+        assert($next instanceof \Closure);
         $promise->then(function ($value) use ($generator, $next) {
             $generator->send($value);
             $next();
@@ -364,6 +369,7 @@ function coroutine(callable $function, ...$args): PromiseInterface
  */
 function parallel(iterable $tasks): PromiseInterface
 {
+    /** @var array<int,PromiseInterface> $pending */
     $pending = [];
     $deferred = new Deferred(function () use (&$pending) {
         foreach ($pending as $promise) {
@@ -425,6 +431,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();
         }
@@ -437,9 +444,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();
     };
 
@@ -453,9 +460,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;
@@ -469,13 +478,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();
         }
@@ -498,9 +508,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;

tests/AwaitTest.php

@@ -8,7 +8,7 @@
 
 class AwaitTest extends TestCase
 {
-    public function testAwaitThrowsExceptionWhenPromiseIsRejectedWithException()
+    public function testAwaitThrowsExceptionWhenPromiseIsRejectedWithException(): void
     {
         $promise = new Promise(function () {
             throw new \Exception('test');
@@ -19,7 +19,7 @@ public function testAwaitThrowsExceptionWhenPromiseIsRejectedWithException()
         React\Async\await($promise);
     }
 
-    public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWithFalse()
+    public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWithFalse(): void
     {
         if (!interface_exists('React\Promise\CancellablePromiseInterface')) {
             $this->markTestSkipped('Promises must be rejected with a \Throwable instance since Promise v3');
@@ -34,7 +34,7 @@ public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWith
         React\Async\await($promise);
     }
 
-    public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWithNull()
+    public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWithNull(): void
     {
         if (!interface_exists('React\Promise\CancellablePromiseInterface')) {
             $this->markTestSkipped('Promises must be rejected with a \Throwable instance since Promise v3');
@@ -49,7 +49,7 @@ public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWith
         React\Async\await($promise);
     }
 
-    public function testAwaitThrowsErrorWhenPromiseIsRejectedWithError()
+    public function testAwaitThrowsErrorWhenPromiseIsRejectedWithError(): void
     {
         $promise = new Promise(function ($_, $reject) {
             throw new \Error('Test', 42);
@@ -61,7 +61,7 @@ public function testAwaitThrowsErrorWhenPromiseIsRejectedWithError()
         React\Async\await($promise);
     }
 
-    public function testAwaitReturnsValueWhenPromiseIsFullfilled()
+    public function testAwaitReturnsValueWhenPromiseIsFullfilled(): void
     {
         $promise = new Promise(function ($resolve) {
             $resolve(42);
@@ -70,7 +70,7 @@ public function testAwaitReturnsValueWhenPromiseIsFullfilled()
         $this->assertEquals(42, React\Async\await($promise));
     }
 
-    public function testAwaitReturnsValueWhenPromiseIsFulfilledEvenWhenOtherTimerStopsLoop()
+    public function testAwaitReturnsValueWhenPromiseIsFulfilledEvenWhenOtherTimerStopsLoop(): void
     {
         $promise = new Promise(function ($resolve) {
             Loop::addTimer(0.02, function () use ($resolve) {
@@ -84,7 +84,7 @@ public function testAwaitReturnsValueWhenPromiseIsFulfilledEvenWhenOtherTimerSto
         $this->assertEquals(2, React\Async\await($promise));
     }
 
-    public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutRunningLoop()
+    public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutRunningLoop(): void
     {
         $now = true;
 
@@ -100,7 +100,7 @@ public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutRunningLoop
         $this->assertTrue($now);
     }
 
-    public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutStoppingLoop()
+    public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutStoppingLoop(): void
     {
         $ticks = 0;
 
@@ -128,7 +128,7 @@ public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutStoppingLoo
         $this->assertEquals(2, $ticks);
     }
 
-    public function testAwaitWithPendingPromiseThatWillResolveWillStopLoopBeforeLastTimerFinishes()
+    public function testAwaitWithPendingPromiseThatWillResolveWillStopLoopBeforeLastTimerFinishes(): void
     {
         $promise = new Promise(function ($resolve) {
             Loop::addTimer(0.02, function () use ($resolve) {
@@ -159,7 +159,7 @@ public function testAwaitWithPendingPromiseThatWillResolveWillStopLoopBeforeLast
         $this->assertEquals(1, $ticks);
     }
 
-    public function testAwaitWithAlreadyRejectedPromiseWillReturnWithoutStoppingLoop()
+    public function testAwaitWithAlreadyRejectedPromiseWillReturnWithoutStoppingLoop(): void
     {
         $ticks = 0;
 
@@ -191,7 +191,7 @@ public function testAwaitWithAlreadyRejectedPromiseWillReturnWithoutStoppingLoop
         $this->assertEquals(2, $ticks);
     }
 
-    public function testAwaitWithPendingPromiseThatWillRejectWillStopLoopBeforeLastTimerFinishes()
+    public function testAwaitWithPendingPromiseThatWillRejectWillStopLoopBeforeLastTimerFinishes(): void
     {
         $promise = new Promise(function ($_, $reject) {
             Loop::addTimer(0.02, function () use (&$reject) {
@@ -227,7 +227,7 @@ public function testAwaitWithPendingPromiseThatWillRejectWillStopLoopBeforeLastT
         $this->assertEquals(1, $ticks);
     }
 
-    public function testAwaitShouldNotCreateAnyGarbageReferencesForResolvedPromise()
+    public function testAwaitShouldNotCreateAnyGarbageReferencesForResolvedPromise(): void
     {
         if (class_exists('React\Promise\When')) {
             $this->markTestSkipped('Not supported on legacy Promise v1 API');
@@ -244,7 +244,7 @@ public function testAwaitShouldNotCreateAnyGarbageReferencesForResolvedPromise()
         $this->assertEquals(0, gc_collect_cycles());
     }
 
-    public function testAwaitShouldNotCreateAnyGarbageReferencesForRejectedPromise()
+    public function testAwaitShouldNotCreateAnyGarbageReferencesForRejectedPromise(): void
     {
         if (class_exists('React\Promise\When')) {
             $this->markTestSkipped('Not supported on legacy Promise v1 API');
@@ -265,7 +265,7 @@ public function testAwaitShouldNotCreateAnyGarbageReferencesForRejectedPromise()
         $this->assertEquals(0, gc_collect_cycles());
     }
 
-    public function testAwaitShouldNotCreateAnyGarbageReferencesForPromiseRejectedWithNullValue()
+    public function testAwaitShouldNotCreateAnyGarbageReferencesForPromiseRejectedWithNullValue(): void
     {
         if (!interface_exists('React\Promise\CancellablePromiseInterface')) {
             $this->markTestSkipped('Promises must be rejected with a \Throwable instance since Promise v3');