Implement PHPStan up to level 4

phpstan.neon

@@ -1,5 +1,5 @@
 parameters:
-	level: 3
+	level: 4
 	ignoreErrors:
 	    -
 	        identifier: new.static

src/Connection/ImapConnection.php

@@ -24,6 +24,7 @@
 use Exception;
 use Generator;
 use LogicException;
+use Throwable;
 
 class ImapConnection implements ConnectionInterface
 {
@@ -122,6 +123,8 @@ public function connect(string $host, ?int $port = null, array $options = []): v
 
     /**
      * Get the default socket options for the given transport.
+     *
+     * @param  'ssl'|'tls'|'starttls'|'tcp'  $transport
      */
     protected function getDefaultSocketOptions(string $transport, array $proxy = [], bool $validateCert = true): array
     {
@@ -595,6 +598,8 @@ public function done(): void
 
     /**
      * Send an IMAP command.
+     *
+     * @param-out string $tag
      */
     public function send(string $name, array $tokens = [], ?string &$tag = null): void
     {
@@ -722,8 +727,12 @@ protected function assertTaggedResponse(string $tag, ?callable $exception = null
      *
      * @template T of Response
      *
-     * @param  callable(T): bool  $filter
+     * @param  callable(Response): bool  $filter
+     * @param  callable(T): bool  $assertion
+     * @param  callable(T): Throwable  $exception
      * @return T
+     *
+     * @throws ImapResponseException
      */
     protected function assertNextResponse(callable $filter, callable $assertion, callable $exception): Response
     {
@@ -744,9 +753,9 @@ protected function assertNextResponse(callable $filter, callable $assertion, cal
      * @template T of Response
      *
      * @param  callable(T): bool  $filter
-     * @return T
+     * @return T|null
      */
-    protected function nextResponse(callable $filter): Response
+    protected function nextResponse(callable $filter): ?Response
     {
         if (! $this->parser) {
             throw new LogicException('No parser instance set');
@@ -764,7 +773,7 @@ protected function nextResponse(callable $filter): Response
             }
         }
 
-        throw new ImapResponseException('No matching response found');
+        return null;
     }
 
     /**

src/Connection/ImapQueryBuilder.php

@@ -373,6 +373,8 @@ protected function parseDate(mixed $date): CarbonInterface
 
     /**
      * Build a single expression node from a basic or nested where.
+     *
+     * @param  array{type: 'basic'|'nested', boolean: 'AND'|'OR', query: ImapQueryBuilder}  $where
      */
     protected function makeExpressionNode(array $where): array
     {
@@ -391,6 +393,8 @@ protected function makeExpressionNode(array $where): array
 
     /**
      * Merge the existing expression with the next expression, respecting the boolean operator.
+     *
+     * @param  'AND'|'OR'  $boolean
      */
     protected function mergeExpressions(string $existing, string $next, string $boolean): string
     {

src/FlaggableInterface.php

@@ -120,6 +120,8 @@ public function hasFlag(BackedEnum|string $flag): bool;
 
     /**
      * Add or remove a flag from the message.
+     *
+     * @param  '+'|'-'  $operation
      */
     public function flag(BackedEnum|string $flag, string $operation, bool $expunge = false): void;
 }

src/MessageQuery.php

@@ -302,8 +302,8 @@ protected function fetch(Collection $messages): array
             return [
                 $uid => [
                     'flags' => $data->lookup('FLAGS')?->values() ?? [],
-                    'headers' => $data->lookup('[HEADER]')?->value ?? '',
-                    'contents' => $data->lookup('[TEXT]')?->value ?? '',
+                    'headers' => $data->lookup('[HEADER]')->value ?? '',
+                    'contents' => $data->lookup('[TEXT]')->value ?? '',
                 ],
             ];
         })->all();

src/QueriesMessages.php

@@ -42,6 +42,8 @@ trait QueriesMessages
 
     /**
      * The fetch order.
+     *
+     * @var 'asc'|'desc'
      */
     protected string $fetchOrder = 'desc';
 

src/Support/Str.php

@@ -148,6 +148,7 @@ public static function fromImapUtf7(string $string): string
 
         // Direct implementation of IMAP's modified UTF-7 decoding.
         return preg_replace_callback('/&([^-]*)-?/', function ($matches) {
+            /** @var array{0: string, 1: string, 2?: string} $matches */
             // If it's just an ampersand.
             if ($matches[1] === '') {
                 return '&';