Improve type definitions and update to PHPStan level max

Author: clue

README.md

@@ -602,7 +602,7 @@ To run the test suite, go to the project root and run:
 vendor/bin/phpunit
 ```
 
-On top of this, we use PHPStan on level 3 to ensure type safety across the project:
+On top of this, we use PHPStan on max level to ensure type safety across the project:
 
 ```bash
 vendor/bin/phpstan

phpstan.neon.dist

@@ -1,5 +1,5 @@
 parameters:
-    level: 3
+    level: max
 
     paths:
         - src/

src/Deferred.php

@@ -4,8 +4,13 @@
 
 final class Deferred
 {
+    /** @var Promise */
     private $promise;
+
+    /** @var callable */
     private $resolveCallback;
+
+    /** @var callable */
     private $rejectCallback;
 
     public function __construct(callable $canceller = null)
@@ -21,6 +26,9 @@ public function promise(): PromiseInterface
         return $this->promise;
     }
 
+    /**
+     * @param mixed $value
+     */
     public function resolve($value): void
     {
         ($this->resolveCallback)($value);

src/Exception/CompositeException.php

@@ -11,9 +11,11 @@
  */
 class CompositeException extends \Exception
 {
+    /** @var \Throwable[] */
     private $throwables;
 
-    public function __construct(array $throwables, $message = '', $code = 0, $previous = null)
+    /** @param \Throwable[] $throwables */
+    public function __construct(array $throwables, string $message = '', int $code = 0, ?\Throwable $previous = null)
     {
         parent::__construct($message, $code, $previous);
 

src/Internal/CancellationQueue.php

@@ -7,7 +7,10 @@
  */
 final class CancellationQueue
 {
+    /** @var bool */
     private $started = false;
+
+    /** @var object[] */
     private $queue = [];
 
     public function __invoke(): void
@@ -20,6 +23,9 @@ public function __invoke(): void
         $this->drain();
     }
 
+    /**
+     * @param mixed $cancellable
+     */
     public function enqueue($cancellable): void
     {
         if (!\is_object($cancellable) || !\method_exists($cancellable, 'then') || !\method_exists($cancellable, 'cancel')) {
@@ -37,6 +43,7 @@ private function drain(): void
     {
         for ($i = \key($this->queue); isset($this->queue[$i]); $i++) {
             $cancellable = $this->queue[$i];
+            assert(\method_exists($cancellable, 'cancel'));
 
             $exception = null;
 

src/Internal/FulfilledPromise.php

@@ -10,8 +10,13 @@
  */
 final class FulfilledPromise implements PromiseInterface
 {
+    /** @var mixed */
     private $value;
 
+    /**
+     * @param mixed $value
+     * @throws \InvalidArgumentException
+     */
     public function __construct($value = null)
     {
         if ($value instanceof PromiseInterface) {

src/Internal/RejectedPromise.php

@@ -11,8 +11,12 @@
  */
 final class RejectedPromise implements PromiseInterface
 {
+    /** @var \Throwable */
     private $reason;
 
+    /**
+     * @param \Throwable $reason
+     */
     public function __construct(\Throwable $reason)
     {
         $this->reason = $reason;

src/Promise.php

@@ -6,11 +6,16 @@
 
 final class Promise implements PromiseInterface
 {
+    /** @var ?callable */
     private $canceller;
+
+    /** @var ?PromiseInterface */
     private $result;
 
+    /** @var callable[] */
     private $handlers = [];
 
+    /** @var int */
     private $requiredCancelRequests = 0;
 
     public function __construct(callable $resolver, callable $canceller = null)
@@ -46,6 +51,7 @@ public function then(callable $onFulfilled = null, callable $onRejected = null):
         return new static(
             $this->resolver($onFulfilled, $onRejected),
             static function () use (&$parent) {
+                assert($parent instanceof self);
                 --$parent->requiredCancelRequests;
 
                 if ($parent->requiredCancelRequests <= 0) {
@@ -187,7 +193,7 @@ private function settle(PromiseInterface $result): void
         }
     }
 
-    private function unwrap($promise): PromiseInterface
+    private function unwrap(PromiseInterface $promise): PromiseInterface
     {
         while ($promise instanceof self && null !== $promise->result) {
             $promise = $promise->result;
@@ -213,6 +219,7 @@ private function call(callable $cb): void
         } elseif (\is_object($callback) && !$callback instanceof \Closure) {
             $ref = new \ReflectionMethod($callback, '__invoke');
         } else {
+            assert($callback instanceof \Closure || \is_string($callback));
             $ref = new \ReflectionFunction($callback);
         }
         $args = $ref->getNumberOfParameters();

src/functions.php

@@ -68,7 +68,7 @@ function reject(\Throwable $reason): PromiseInterface
  * will be an array containing the resolution values of each of the items in
  * `$promisesOrValues`.
  *
- * @param iterable $promisesOrValues
+ * @param iterable<mixed> $promisesOrValues
  * @return PromiseInterface
  */
 function all(iterable $promisesOrValues): PromiseInterface
@@ -77,6 +77,7 @@ function all(iterable $promisesOrValues): PromiseInterface
 
     return new Promise(function ($resolve, $reject) use ($promisesOrValues, $cancellationQueue): void {
         $toResolve = 0;
+        /** @var bool */
         $continue  = true;
         $values    = [];
 
@@ -118,7 +119,7 @@ function (\Throwable $reason) use (&$continue, $reject): void {
  * The returned promise will become **infinitely pending** if  `$promisesOrValues`
  * contains 0 items.
  *
- * @param iterable $promisesOrValues
+ * @param iterable<mixed> $promisesOrValues
  * @return PromiseInterface
  */
 function race(iterable $promisesOrValues): PromiseInterface
@@ -153,7 +154,7 @@ function race(iterable $promisesOrValues): PromiseInterface
  * The returned promise will also reject with a `React\Promise\Exception\LengthException`
  * if `$promisesOrValues` contains 0 items.
  *
- * @param iterable $promisesOrValues
+ * @param iterable<mixed> $promisesOrValues
  * @return PromiseInterface
  */
 function any(iterable $promisesOrValues): PromiseInterface
@@ -215,6 +216,7 @@ function _checkTypehint(callable $callback, \Throwable $reason): bool
     } elseif (\is_object($callback) && !$callback instanceof \Closure) {
         $callbackReflection = new \ReflectionMethod($callback, '__invoke');
     } else {
+        assert($callback instanceof \Closure || \is_string($callback));
         $callbackReflection = new \ReflectionFunction($callback);
     }
 
@@ -257,16 +259,16 @@ function _checkTypehint(callable $callback, \Throwable $reason): bool
         if ($type instanceof \ReflectionIntersectionType) {
             foreach ($type->getTypes() as $typeToMatch) {
                 assert($typeToMatch instanceof \ReflectionNamedType);
-                if (!($matches = ($typeToMatch->isBuiltin() && \gettype($reason) === $typeToMatch->getName())
-                    || (new \ReflectionClass($typeToMatch->getName()))->isInstance($reason))) {
+                $name = $typeToMatch->getName();
+                if (!($matches = (!$typeToMatch->isBuiltin() && $reason instanceof $name))) {
                     break;
                 }
             }
             assert(isset($matches));
         } else {
             assert($type instanceof \ReflectionNamedType);
-            $matches = ($type->isBuiltin() && \gettype($reason) === $type->getName())
-                || (new \ReflectionClass($type->getName()))->isInstance($reason);
+            $name = $type->getName();
+            $matches = !$type->isBuiltin() && $reason instanceof $name;
         }
 
         // If we look for a single match (union), we can return early on match

tests/DeferredTest.php

@@ -8,7 +8,7 @@ class DeferredTest extends TestCase
 {
     use PromiseTest\FullTestTrait;
 
-    public function getPromiseTestAdapter(callable $canceller = null)
+    public function getPromiseTestAdapter(callable $canceller = null): CallbackPromiseAdapter
     {
         $d = new Deferred($canceller);
 
@@ -21,7 +21,7 @@ public function getPromiseTestAdapter(callable $canceller = null)
     }
 
     /** @test */
-    public function shouldRejectWithoutCreatingGarbageCyclesIfCancellerRejectsWithException()
+    public function shouldRejectWithoutCreatingGarbageCyclesIfCancellerRejectsWithException(): void
     {
         gc_collect_cycles();
         $deferred = new Deferred(function ($resolve, $reject) {
@@ -34,7 +34,7 @@ public function shouldRejectWithoutCreatingGarbageCyclesIfCancellerRejectsWithEx
     }
 
     /** @test */
-    public function shouldRejectWithoutCreatingGarbageCyclesIfParentCancellerRejectsWithException()
+    public function shouldRejectWithoutCreatingGarbageCyclesIfParentCancellerRejectsWithException(): void
     {
         gc_collect_cycles();
         gc_collect_cycles(); // clear twice to avoid leftovers in PHP 7.4 with ext-xdebug and code coverage turned on
@@ -49,7 +49,7 @@ public function shouldRejectWithoutCreatingGarbageCyclesIfParentCancellerRejects
     }
 
     /** @test */
-    public function shouldRejectWithoutCreatingGarbageCyclesIfCancellerHoldsReferenceAndExplicitlyRejectWithException()
+    public function shouldRejectWithoutCreatingGarbageCyclesIfCancellerHoldsReferenceAndExplicitlyRejectWithException(): void
     {
         gc_collect_cycles();
         gc_collect_cycles(); // clear twice to avoid leftovers in PHP 7.4 with ext-xdebug and code coverage turned on