Feature: accept iterable of file paths

This commit adds support for `ColocatedMappingDriver` to accept
`iterable` of file paths. Before it was only possible to accept
an array of directory paths. Now, one could provide fine-grained
iterator of only necessary files to the Driver. Bundles should
use Symfony Finder to implement it, since it gives much flexibility
to the client code to configure which files should be included
and which not.

Backward compatibility is achieved with the following approach:
If it's an array, then it should be OK to take a look at `$paths[0]`
and determine if it is a file or a directory. If it's not an array,
we can assume that it's `$filePaths` iterable that's given.

Author: rela589n

src/Persistence/Mapping/Driver/ColocatedMappingDriver.php

@@ -21,8 +21,11 @@
  */
 trait ColocatedMappingDriver
 {
+    /** @var iterable<array-key,string> */
+    private iterable $filePaths;
+
     /**
-     * The paths where to look for mapping files.
+     * The directory paths where to look for mapping files.
      *
      * @var array<int, string>
      */
@@ -39,7 +42,7 @@ trait ColocatedMappingDriver
     protected string $fileExtension = '.php';
 
     /**
-     * Cache for getAllClassNames().
+     * Cache for {@see getAllClassNames()}.
      *
      * @var array<int, string>|null
      * @phpstan-var list<class-string>|null
@@ -67,7 +70,7 @@ public function getPaths(): array
     }
 
     /**
-     * Append exclude lookup paths to metadata driver.
+     * Append exclude lookup paths to a metadata driver.
      *
      * @param string[] $paths
      */
@@ -120,13 +123,17 @@ public function getAllClassNames(): array
             return $this->classNames;
         }
 
-        if ($this->paths === []) {
+        if ($this->paths === [] && ! isset($this->filePaths)) {
             throw MappingException::pathRequiredForDriver(static::class);
         }
 
         $dirFilesIterator = new DirectoryFilesIterator($this->paths, $this->fileExtension);
+
         /** @var iterable<string> $filePathsIterator */
-        $filePathsIterator = new FilePathNameIterator($dirFilesIterator);
+        $filePathsIterator = $this->concatIterables(
+            $this->filePaths ?? [],
+            new FilePathNameIterator($dirFilesIterator),
+        );
 
         /** @var array<string,true> $includedFiles */
         $includedFiles = [];
@@ -172,4 +179,19 @@ public function getAllClassNames(): array
 
         return $classes;
     }
+
+    /**
+     * @param iterable<TKey, T> $iterable1
+     * @param iterable<TKey, T> $iterable2
+     *
+     * @return iterable<TKey, T>
+     *
+     * @template TKey
+     * @template T
+     */
+    private function concatIterables(iterable $iterable1, iterable $iterable2): iterable
+    {
+        yield from $iterable1;
+        yield from $iterable2;
+    }
 }

src/Persistence/Mapping/MappingException.php

@@ -30,7 +30,7 @@ public static function classNotFoundInNamespaces(
     public static function pathRequiredForDriver(string $driverClassName): self
     {
         return new self(sprintf(
-            'Specifying the paths to your entities is required when using %s to retrieve all class names.',
+            'Specifying source file paths to your entities is required when using %s to retrieve all class names.',
             $driverClassName,
         ));
     }

tests/Persistence/Mapping/ColocatedMappingDriverTest.php

@@ -12,14 +12,16 @@
 use Doctrine\Tests\Persistence\Mapping\_files\colocated\TestClass;
 use Generator;
 use PHPUnit\Framework\TestCase;
+use Traversable;
 
+use function is_file;
 use function sort;
 
 class ColocatedMappingDriverTest extends TestCase
 {
     public function testAddGetPaths(): void
     {
-        $driver = $this->createDriver(__DIR__ . '/_files/colocated');
+        $driver = $this->createDirectoryPathDriver(__DIR__ . '/_files/colocated');
         self::assertSame([
             __DIR__ . '/_files/colocated',
         ], $driver->getPaths());
@@ -35,7 +37,7 @@ public function testAddGetPaths(): void
 
     public function testAddGetExcludePaths(): void
     {
-        $driver = $this->createDriver(__DIR__ . '/_files/colocated');
+        $driver = $this->createDirectoryPathDriver(__DIR__ . '/_files/colocated');
         self::assertSame([], $driver->getExcludePaths());
 
         $driver->addExcludePaths(['/test/path1', '/test/path2']);
@@ -48,46 +50,86 @@ public function testAddGetExcludePaths(): void
 
     public function testGetSetFileExtension(): void
     {
-        $driver = $this->createDriver(__DIR__ . '/_files/colocated');
+        $driver = $this->createDirectoryPathDriver(__DIR__ . '/_files/colocated');
         self::assertSame('.php', $driver->getFileExtension());
 
         $driver->setFileExtension('.php1');
 
         self::assertSame('.php1', $driver->getFileExtension());
     }
 
-    /** @dataProvider pathProvider */
-    public function testGetAllClassNames(string $path): void
+    /** @dataProvider directoryPathProvider */
+    public function testGetAllClassNamesForDirectory(string $dirPath): void
     {
-        $driver = $this->createDriver($path);
+        $driver = $this->createDirectoryPathDriver($dirPath);
 
         $classes = $driver->getAllClassNames();
 
         sort($classes);
         self::assertSame([Entity::class, EntityFixture::class], $classes);
     }
 
+    public function testGetAllClassNamesForFilePaths(): void
+    {
+        $driver = $this->createFilePathsDriver([
+            __DIR__ . '/_files/colocated/Entity.php',
+            __DIR__ . '/_files/colocated/TestClass.php',
+        ]);
+
+        $classes = $driver->getAllClassNames();
+
+        self::assertSame([Entity::class], $classes, 'The driver should only return the class names for the provided file path names, excluding transient class names.');
+    }
+
+    public function testGetAllClassNamesWorksBothForFilePathsAndRetroactivelyAddedDirectoryPaths(): void
+    {
+        $driver = $this->createFilePathsDriver([__DIR__ . '/_files/colocated/Entity.php']);
+
+        $driver->addPaths([__DIR__ . '/_files/colocated/']);
+
+        $classes = $driver->getAllClassNames();
+        sort($classes);
+
+        self::assertSame(
+            [Entity::class, EntityFixture::class],
+            $classes,
+            'The driver should return class names from both the provided file path names and the retroactively added directory paths (these should not be ignored).',
+        );
+    }
+
     /** @return Generator<string, array{string}> */
-    public static function pathProvider(): Generator
+    public static function directoryPathProvider(): Generator
     {
         yield 'straigthforward path' => [__DIR__ . '/_files/colocated'];
         yield 'winding path' => [__DIR__ . '/../Mapping/_files/colocated'];
     }
 
-    private function createDriver(string $path): MyDriver
+    private function createDirectoryPathDriver(string $dirPath): MyDriver
     {
-        return new MyDriver([$path]);
+        return new MyDriver([$dirPath]);
+    }
+
+    /** @param list<string> $filePaths */
+    private function createFilePathsDriver(array $filePaths): MyDriver
+    {
+        return new MyDriver($filePaths);
     }
 }
 
 final class MyDriver implements MappingDriver
 {
     use ColocatedMappingDriver;
 
-    /** @param non-empty-list<string> $paths One or multiple paths where mapping classes can be found. */
-    public function __construct(array $paths)
+    /** @param iterable<string> $paths One or multiple paths where mapping classes can be found. */
+    public function __construct(iterable $paths)
     {
-        $this->addPaths($paths);
+        $isFilePaths = $paths instanceof Traversable || is_file($paths[0]);
+
+        if (! $isFilePaths) {
+            $this->paths = $paths;
+        } else {
+            $this->filePaths = $paths;
+        }
     }
 
     /**