PHPStan improvements

composer.json

@@ -29,7 +29,7 @@
         "league/flysystem-ziparchive": "^3.12",
         "league/glide": "^2.2",
         "league/mime-type-detection": ">=1.8",
-        "phpstan/phpstan": "^1.4",
+        "phpstan/phpstan": "^2.0",
         "phpunit/phpunit": "^9.6.18",
         "srwiez/thumbhash": "^1.2",
         "symfony/browser-kit": "^6.4|^7.0",

src/Filesystem/Attribute/PendingUploadedFile.php

@@ -20,9 +20,6 @@
 
 /**
  * @author Jakub Caban <kuba.iluvatar@gmail.com>
- *
- * @phpstan-consistent-constructor
- * @readonly
  */
 #[\Attribute(\Attribute::TARGET_PARAMETER | \Attribute::TARGET_PROPERTY)]
 class PendingUploadedFile
@@ -48,7 +45,7 @@ public static function forArgument(ArgumentMetadata $argument): self
             $attribute = $attributes[0];
             \assert($attribute instanceof self);
         } else {
-            $attribute = new static();
+            $attribute = new self();
         }
 
         $attribute->path ??= $argument->getName();

src/Filesystem/Doctrine/Mapping/Stateless.php

@@ -27,11 +27,11 @@ public function __construct(string $filesystem, string|Namer $namer)
 
     public function filesystem(): string
     {
-        return parent::filesystem(); // @phpstan-ignore-line
+        return parent::filesystem(); // @phpstan-ignore return.type
     }
 
     public function namer(): Namer
     {
-        return parent::namer(); // @phpstan-ignore-line
+        return parent::namer(); // @phpstan-ignore return.type
     }
 }

src/Filesystem/Doctrine/Mapping/StoreAsPath.php

@@ -31,6 +31,6 @@ public function __construct(
 
     public function filesystem(): string
     {
-        return parent::filesystem(); // @phpstan-ignore-line
+        return parent::filesystem(); // @phpstan-ignore return.type
     }
 }

src/Filesystem/Doctrine/Types/JsonType.php

@@ -54,7 +54,7 @@ public function convertToDatabaseValue($value, AbstractPlatform $platform): ?str
             throw InvalidType::new($value, SerializableFile::class, [SerializableFile::class, 'null']);
         }
 
-        throw ConversionException::conversionFailedInvalidType($value, SerializableFile::class, [SerializableFile::class, 'null']); // @phpstan-ignore-line
+        throw ConversionException::conversionFailedInvalidType($value, SerializableFile::class, [SerializableFile::class, 'null']); // @phpstan-ignore staticMethod.notFound
     }
 
     public function convertToPHPValue($value, AbstractPlatform $platform): ?LazyFile
@@ -72,7 +72,7 @@ public function convertToPHPValue($value, AbstractPlatform $platform): ?LazyFile
             throw InvalidType::new($value, File::class, ['array', 'null']);
         }
 
-        throw ConversionException::conversionFailedFormat($value, File::class, 'array|null'); // @phpstan-ignore-line
+        throw ConversionException::conversionFailedFormat($value, File::class, 'array|null'); // @phpstan-ignore staticMethod.notFound
     }
 
     final public function requiresSQLCommentHint(AbstractPlatform $platform): bool

src/Filesystem/Doctrine/Types/StringType.php

@@ -45,7 +45,7 @@ final public function convertToDatabaseValue($value, AbstractPlatform $platform)
             throw InvalidType::new($value, File::class, [File::class, 'null']);
         }
 
-        throw ConversionException::conversionFailedInvalidType($value, File::class, [File::class, 'null']); // @phpstan-ignore-line
+        throw ConversionException::conversionFailedInvalidType($value, File::class, [File::class, 'null']); // @phpstan-ignore staticMethod.notFound
     }
 
     final public function convertToPHPValue($value, AbstractPlatform $platform): ?LazyFile

src/Filesystem/Flysystem/AdapterFactory.php

@@ -67,7 +67,7 @@ private static function createRealAdapter(string $dsn): FilesystemAdapter
         };
     }
 
-    private static function createLocalAdapter(string $dsn, array $parsed): LocalFilesystemAdapter // @phpstan-ignore-line
+    private static function createLocalAdapter(string $dsn, array $parsed): LocalFilesystemAdapter // @phpstan-ignore missingType.iterableValue
     {
         $parsed = self::normalizeQuery($parsed);
         $visibility = $parsed['query']['visibility'] ?? [];
@@ -81,7 +81,7 @@ private static function createLocalAdapter(string $dsn, array $parsed): LocalFil
         );
     }
 
-    private static function parse(string $dsn): array // @phpstan-ignore-line
+    private static function parse(string $dsn): array // @phpstan-ignore missingType.iterableValue
     {
         $parsed = \parse_url($dsn);
 
@@ -105,7 +105,7 @@ private static function parse(string $dsn): array // @phpstan-ignore-line
         return $parsed;
     }
 
-    private static function normalizeQuery(array $parts): array // @phpstan-ignore-line
+    private static function normalizeQuery(array $parts): array // @phpstan-ignore missingType.iterableValue, missingType.iterableValue
     {
         $query = [];
 
@@ -116,7 +116,7 @@ private static function normalizeQuery(array $parts): array // @phpstan-ignore-l
         return $parts;
     }
 
-    private static function createInMemoryAdapter(array $parsed): InMemoryFilesystemAdapter // @phpstan-ignore-line
+    private static function createInMemoryAdapter(array $parsed): InMemoryFilesystemAdapter // @phpstan-ignore missingType.iterableValue
     {
         if ($name = $parsed['path'] ?? null) {
             return StaticInMemoryAdapterRegistry::get($name);
@@ -125,7 +125,7 @@ private static function createInMemoryAdapter(array $parsed): InMemoryFilesystem
         return new InMemoryFilesystemAdapter();
     }
 
-    private static function createSftpAdapter(array $parsed): FilesystemAdapter // @phpstan-ignore-line
+    private static function createSftpAdapter(array $parsed): FilesystemAdapter // @phpstan-ignore missingType.iterableValue
     {
         if (!\class_exists(SftpAdapter::class)) {
             throw new \LogicException('league/flysystem-sftp-v3 is required to use the SFTP adapter. Install with "composer require league/flysystem-sftp-v3".');
@@ -146,7 +146,7 @@ private static function createSftpAdapter(array $parsed): FilesystemAdapter // @
         );
     }
 
-    private static function createFtpAdapter(array $parsed): FilesystemAdapter // @phpstan-ignore-line
+    private static function createFtpAdapter(array $parsed): FilesystemAdapter // @phpstan-ignore missingType.iterableValue
     {
         if (!\class_exists(FtpAdapter::class)) {
             throw new \LogicException('league/flysystem-ftp is required to use the FTP adapter. Install with "composer require league/flysystem-ftp".');
@@ -164,7 +164,7 @@ private static function createFtpAdapter(array $parsed): FilesystemAdapter // @p
         ])));
     }
 
-    private static function createS3Adapter(array $parsed): FilesystemAdapter // @phpstan-ignore-line
+    private static function createS3Adapter(array $parsed): FilesystemAdapter // @phpstan-ignore missingType.iterableValue
     {
         $parsed = self::normalizeQuery($parsed);
 
@@ -181,8 +181,8 @@ private static function createS3Adapter(array $parsed): FilesystemAdapter // @ph
         }
 
         if (\class_exists(AwsS3V3Adapter::class)) {
-            return new AwsS3V3Adapter( // @phpstan-ignore-line
-                new S3Client([ // @phpstan-ignore-line
+            return new AwsS3V3Adapter( // @phpstan-ignore return.type
+                new S3Client([ // @phpstan-ignore class.notFound
                     'region' => $parsed['query']['region'] ?? $parsed['fragment'] ?? throw new \InvalidArgumentException('A region must be set in the query (ie ?region=us-east-1) or as the fragment (ie #us-east-1).'),
                     'credentials' => [
                         'key' => $parsed['user'] ?? null,

src/Filesystem/Flysystem/Operator.php

@@ -51,7 +51,7 @@ public function name(): string
         return $this->name;
     }
 
-    public function publicUrl(string $path, array $config = []): string // @phpstan-ignore-line
+    public function publicUrl(string $path, array $config = []): string // @phpstan-ignore missingType.iterableValue
     {
         try {
             return $this->feature(PublicUrlGenerator::class)->publicUrl($path, new Config($config));
@@ -60,7 +60,7 @@ public function publicUrl(string $path, array $config = []): string // @phpstan-
         }
     }
 
-    public function temporaryUrl(string $path, \DateTimeInterface $expiresAt, array $config = []): string // @phpstan-ignore-line
+    public function temporaryUrl(string $path, \DateTimeInterface $expiresAt, array $config = []): string // @phpstan-ignore missingType.iterableValue
     {
         try {
             return $this->feature(TemporaryUrlGenerator::class)->temporaryUrl($path, $expiresAt, new Config($config));
@@ -69,7 +69,7 @@ public function temporaryUrl(string $path, \DateTimeInterface $expiresAt, array
         }
     }
 
-    public function checksum(string $path, array $config = []): string // @phpstan-ignore-line
+    public function checksum(string $path, array $config = []): string // @phpstan-ignore missingType.iterableValue
     {
         return $this->inner->checksum($path, $config);
     }
@@ -124,12 +124,12 @@ public function visibility(string $path): string
         return $this->inner->visibility($path);
     }
 
-    public function write(string $location, string $contents, array $config = []): void // @phpstan-ignore-line
+    public function write(string $location, string $contents, array $config = []): void // @phpstan-ignore missingType.iterableValue
     {
         $this->inner->write($location, $contents, $config);
     }
 
-    public function writeStream(string $location, $contents, array $config = []): void // @phpstan-ignore-line
+    public function writeStream(string $location, $contents, array $config = []): void // @phpstan-ignore missingType.iterableValue
     {
         $this->inner->writeStream($location, $contents, $config);
     }
@@ -149,17 +149,17 @@ public function deleteDirectory(string $location): void
         $this->inner->deleteDirectory($location);
     }
 
-    public function createDirectory(string $location, array $config = []): void // @phpstan-ignore-line
+    public function createDirectory(string $location, array $config = []): void // @phpstan-ignore missingType.iterableValue
     {
         $this->inner->createDirectory($location, $config);
     }
 
-    public function move(string $source, string $destination, array $config = []): void // @phpstan-ignore-line
+    public function move(string $source, string $destination, array $config = []): void // @phpstan-ignore missingType.iterableValue
     {
         $this->inner->move($source, $destination, $config);
     }
 
-    public function copy(string $source, string $destination, array $config = []): void // @phpstan-ignore-line
+    public function copy(string $source, string $destination, array $config = []): void // @phpstan-ignore missingType.iterableValue
     {
         $this->inner->copy($source, $destination, $config);
     }
@@ -183,7 +183,7 @@ private function feature(string $feature): object
         }
 
         if (\is_array($this->features) && isset($this->features[$feature])) {
-            return $this->features[$feature]; // @phpstan-ignore-line
+            return $this->features[$feature]; // @phpstan-ignore return.type
         }
 
         throw new UnsupportedFeature($feature, $this->name(), $e ?? null);

src/Filesystem/FlysystemFilesystem.php

@@ -142,7 +142,7 @@ public function mkdir(string $path, Directory|\SplFileInfo|null $content = null,
             $progress = $config['progress'] ?? static fn() => null;
 
             foreach ($content->files() as $file) {
-                $file = $this->write($prefixer->prefixPath(\mb_substr($file->path(), $prefixLength)), $file, $config); // @phpstan-ignore-line
+                $file = $this->write($prefixer->prefixPath(\mb_substr($file->path(), $prefixLength)), $file, $config); // @phpstan-ignore argument.type
                 $progress($file);
             }
 

src/Filesystem/Glide/GlideTransformUrlGenerator.php

@@ -28,8 +28,8 @@ public function transformUrl(string $path, array|string $filter, Config $config)
     {
         $filter = match (true) {
             \is_string($filter) => ['p' => $filter], // is glide "preset"
-            \is_array($filter) && !\array_is_list($filter) => $filter, // is standard glide parameters
-            \is_array($filter) => ['p' => \implode(',', $filter)], // is array of "presets"
+            !\array_is_list($filter) => $filter, // is standard glide parameters
+            default => ['p' => \implode(',', $filter)], // is array of "presets"
         };
 
         return $this->urlBuilder->getUrl($path, $filter);

src/Filesystem/Node/Directory.php

@@ -19,28 +19,35 @@
 /**
  * @author Kevin Bond <kevinbond@gmail.com>
  *
- * @extends \IteratorAggregate<Node|File|Directory>
+ * @extends \IteratorAggregate<File|Directory> (required for intellisense)
+ *
+ * @phpstan-template T of Node = Node
+ * @phpstan-extends \IteratorAggregate<T>
  */
 interface Directory extends Node, \IteratorAggregate
 {
     public function recursive(): static;
 
+    /**
+     * @return File|Directory
+     * @phpstan-return T|null
+     */
     public function first(): ?Node;
 
     /**
      * Filter nodes (return true = include, return false = exclude).
      *
-     * @param callable(Node):bool|callable(File):bool|callable(Directory):bool $predicate
+     * @param callable(T):bool $predicate
      */
     public function filter(callable $predicate): static;
 
     /**
-     * @return $this<File>|File[]
+     * @return static<File>
      */
     public function files(): static;
 
     /**
-     * @return $this<Directory>|Directory[]
+     * @return static<self>
      */
     public function directories(): static;
 
@@ -152,8 +159,6 @@ public function notMatchingPath(string|array $patterns): static;
     /**
      * @see FilesystemReader::listContents()
      *
-     * @return Node[]|File[]|Directory[]|\Traversable<Node|File|Directory>
-     *
      * @throws UnableToListContents
      * @throws FilesystemException
      */

src/Filesystem/Node/Directory/FlysystemDirectory.php

@@ -135,7 +135,7 @@ public function size(array|int|string $sizes): static
         $clone = clone $this;
 
         foreach ((array) $sizes as $size) {
-            $clone->sizes[] = new NumberComparator($size); // @phpstan-ignore-line
+            $clone->sizes[] = new NumberComparator($size); // @phpstan-ignore argument.type
         }
 
         return $clone;

src/Filesystem/Node/Directory/LazyDirectory.php

@@ -30,6 +30,6 @@ public function ensureDirectory(): self
 
     protected function inner(): Directory
     {
-        return $this->inner ??= $this->filesystem()->directory($this->path()); // @phpstan-ignore-line
+        return $this->inner ??= $this->filesystem()->directory($this->path()); // @phpstan-ignore return.type
     }
 }

src/Filesystem/Node/Dsn.php

@@ -51,7 +51,7 @@ public static function create(string $filesystem, Path|string $path): self
     public static function normalize(string $value): array
     {
         if (2 === \count($parts = \explode('://', $value, 2))) {
-            return $parts; // @phpstan-ignore-line
+            return $parts;
         }
 
         return [null, $value];

src/Filesystem/Node/File/Image/FlysystemImage.php

@@ -56,7 +56,7 @@ public function iptc(): array
 
     public function tempFile(): ImageFileInfo
     {
-        return parent::tempFile(); // @phpstan-ignore-line
+        return parent::tempFile(); // @phpstan-ignore return.type
     }
 
     protected function createTempFile(): \SplFileInfo

src/Filesystem/Node/File/Image/LazyImage.php

@@ -82,6 +82,6 @@ public function ensureImage(): self
 
     protected function inner(): Image
     {
-        return $this->inner ??= $this->filesystem()->image($this->path()); // @phpstan-ignore-line
+        return $this->inner ??= $this->filesystem()->image($this->path()); // @phpstan-ignore return.type
     }
 }

src/Filesystem/Node/File/LazyFile.php

@@ -68,6 +68,6 @@ public function ensureFile(): static
 
     protected function inner(): File
     {
-        return $this->inner ??= $this->filesystem()->file($this->path()); // @phpstan-ignore-line
+        return $this->inner ??= $this->filesystem()->file($this->path()); // @phpstan-ignore return.type
     }
 }

src/Filesystem/Node/File/PendingFile.php

@@ -74,7 +74,7 @@ public function dsn(): Dsn
 
     public function lastModified(): \DateTimeImmutable
     {
-        return \DateTimeImmutable::createFromFormat('U', (string) $this->getMTime()) // @phpstan-ignore-line
+        return \DateTimeImmutable::createFromFormat('U', (string) $this->getMTime()) // @phpstan-ignore method.nonObject
             ->setTimezone(new \DateTimeZone(\date_default_timezone_get()))
         ;
     }

src/Filesystem/Node/FlysystemNode.php

@@ -56,7 +56,7 @@ public function directory(): ?Directory
 
     public function lastModified(): \DateTimeImmutable
     {
-        return $this->cache['last-modified'] ??= \DateTimeImmutable::createFromFormat('U', $this->operator->lastModified($this->path())) // @phpstan-ignore-line
+        return $this->cache['last-modified'] ??= \DateTimeImmutable::createFromFormat('U', $this->operator->lastModified($this->path())) // @phpstan-ignore method.nonObject, argument.type
             ->setTimezone(new \DateTimeZone(\date_default_timezone_get()))
         ;
     }

src/Filesystem/Node/LazyNode.php

@@ -108,7 +108,7 @@ public function lastModified(): \DateTimeImmutable
 
         $lastModified = \is_numeric($lastModified) ? \DateTimeImmutable::createFromFormat('U', (string) $lastModified) : new \DateTimeImmutable($lastModified);
 
-        return $lastModified->setTimezone(new \DateTimeZone(\date_default_timezone_get())); // @phpstan-ignore-line
+        return $lastModified->setTimezone(new \DateTimeZone(\date_default_timezone_get())); // @phpstan-ignore method.nonObject
     }
 
     public function visibility(): string

src/Filesystem/Node/Mapping.php

@@ -75,7 +75,7 @@ public function __construct(
     /**
      * @internal
      */
-    public static function fromArray(array $array): self // @phpstan-ignore-line
+    public static function fromArray(array $array): self // @phpstan-ignore missingType.iterableValue
     {
         $filesystem = $array['filesystem'] ?? null;
 
@@ -214,7 +214,7 @@ public function serialize(Node $node): string|array
             };
         }
 
-        return \array_filter($ret, fn($v) => null !== $v); // @phpstan-ignore-line
+        return \array_filter($ret, fn($v) => null !== $v); // @phpstan-ignore return.type
     }
 
     private function requiresFilesystem(): bool