Feature: accept Traversable of file paths

This commit adds support for `ColocatedMappingDriver` to accept
`Traversable` of file paths. Before it was only possible to accept
an array of directory paths. Now, one could provide fine-grained
iterator of only needed 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.

Author: rela589n

src/Persistence/Mapping/Driver/ColocatedMappingDriver.php

@@ -6,6 +6,7 @@
 
 use Doctrine\Persistence\Mapping\MappingException;
 use ReflectionClass;
+use Traversable;
 
 use function array_merge;
 use function array_unique;
@@ -21,8 +22,11 @@
  */
 trait ColocatedMappingDriver
 {
+    /** @var Traversable<array-key,string> */
+    private Traversable $filePaths;
+
     /**
-     * The paths where to look for mapping files.
+     * The directory paths where to look for mapping files.
      *
      * @var array<int, string>
      */
@@ -39,7 +43,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 +71,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 +124,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 +180,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

@@ -4,6 +4,7 @@
 
 namespace Doctrine\Tests\Persistence\Mapping;
 
+use ArrayIterator;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\Mapping\Driver\ColocatedMappingDriver;
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
@@ -12,14 +13,15 @@
 use Doctrine\Tests\Persistence\Mapping\_files\colocated\TestClass;
 use Generator;
 use PHPUnit\Framework\TestCase;
+use Traversable;
 
 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(new ArrayIterator($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 non-empty-list<string>|Traversable<string> $paths One or multiple paths where mapping classes can be found. */
+    public function __construct(iterable $paths)
     {
-        $this->addPaths($paths);
+        $isFilePaths = $paths instanceof Traversable;
+
+        if (! $isFilePaths) {
+            $this->paths = $paths;
+        } else {
+            $this->filePaths = $paths;
+        }
     }
 
     /**