Feature: add support for $sourceFilePathNames

rela589n · rela589n · commit 582a0b82b036 · 2025-08-07T14:37:40.000+03:00
In the scope of doctrine/persistence#429 (available from `doctrine/persistence` >= 4.1) there was added `ColocatedMappingDriver::$sourceFilePathNames`, which allows passing the iterable of file paths for the mapping driver to use. This commit integrates those changes into `AttributeDriver`. Since `doctrine/orm` maintains the support for `doctrine/persistence` of older versions, `AttributeDriver` ensures that `$sourceFilePathNames` is actually defined. Tests use `InstalledVersions` to opt into new behaviour if `doctrine/persistence` is at least version 4.1. `AttributeDriver` now accepts a new boolean to opt into the new behaviour. This flag is used to distinguish between an array of directory paths (the existing way) and iterable of file paths (the new way). The old behaviour can be adapted into new by using `glob()` search on directory paths.
diff --git a/composer.json b/composer.json
@@ -37,6 +37,7 @@
         "symfony/var-exporter": "^6.3.9 || ^7.0"
     },
     "require-dev": {
+        "doctrine/persistence": "^3.3.1 || ^4.0 || 4.1.x-dev",
         "doctrine/coding-standard": "^13.0",
         "phpbench/phpbench": "^1.0",
         "phpdocumentor/guides-cli": "^1.4",
diff --git a/docs/en/reference/advanced-configuration.rst b/docs/en/reference/advanced-configuration.rst
@@ -29,7 +29,7 @@ steps of configuration.
 
     $config = new Configuration;
     $config->setMetadataCache($metadataCache);
-    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
+    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities']);
     $config->setMetadataDriverImpl($driverImpl);
     $config->setQueryCache($queryCache);
 
@@ -154,7 +154,7 @@ The attribute driver can be injected in the ``Doctrine\ORM\Configuration``:
     <?php
     use Doctrine\ORM\Mapping\Driver\AttributeDriver;
 
-    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
+    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities']);
     $config->setMetadataDriverImpl($driverImpl);
 
 The path information to the entities is required for the attribute
diff --git a/src/Mapping/Driver/AttributeDriver.php b/src/Mapping/Driver/AttributeDriver.php
@@ -13,13 +13,16 @@
 use Doctrine\Persistence\Mapping\Driver\ColocatedMappingDriver;
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
 use InvalidArgumentException;
+use LogicException;
 use ReflectionClass;
 use ReflectionMethod;
 
 use function assert;
 use function class_exists;
 use function constant;
 use function defined;
+use function is_array;
+use function property_exists;
 use function sprintf;
 
 class AttributeDriver implements MappingDriver
@@ -35,10 +38,11 @@ class AttributeDriver implements MappingDriver
     private readonly AttributeReader $reader;
 
     /**
-     * @param array<string> $paths
-     * @param true          $reportFieldsWhereDeclared no-op, to be removed in 4.0
+     * @param iterable<string> $paths                     iterable of source file path names (if {@see $pathsAsFilePaths}), or an array of directories.
+     * @param true             $reportFieldsWhereDeclared no-op, to be removed in 4.0
+     * @param bool             $pathsAsFilePaths          whether {@see $paths} are paths to files or directories
      */
-    public function __construct(array $paths, bool $reportFieldsWhereDeclared = true)
+    public function __construct(iterable $paths, bool $reportFieldsWhereDeclared = true, bool $pathsAsFilePaths = false)
     {
         if (! $reportFieldsWhereDeclared) {
             throw new InvalidArgumentException(sprintf(
@@ -47,8 +51,19 @@ public function __construct(array $paths, bool $reportFieldsWhereDeclared = true
             ));
         }
 
+        if ($pathsAsFilePaths) {
+            if (! property_exists(self::class, 'sourceFilePathNames')) {
+                throw new LogicException('Source file path names support for AttributeDriver is available since doctrine/persistence 4.1.');
+            }
+
+            $this->sourceFilePathNames = $paths;
+        } elseif (is_array($paths)) {
+            $this->addPaths($paths);
+        } else {
+            throw new LogicException('The $paths argument must be an array of directories.');
+        }
+
         $this->reader = new AttributeReader();
-        $this->addPaths($paths);
     }
 
     public function isTransient(string $className): bool
diff --git a/src/ORMSetup.php b/src/ORMSetup.php
@@ -35,6 +35,7 @@ public static function createAttributeMetadataConfiguration(
         bool $isDevMode = false,
         string|null $proxyDir = null,
         CacheItemPoolInterface|null $cache = null,
+        bool $pathsAsFilePaths = false,
     ): Configuration {
         if (PHP_VERSION_ID >= 80400) {
             Deprecation::trigger(
@@ -47,7 +48,7 @@ public static function createAttributeMetadataConfiguration(
         }
 
         $config = self::createConfiguration($isDevMode, $proxyDir, $cache);
-        $config->setMetadataDriverImpl(new AttributeDriver($paths));
+        $config->setMetadataDriverImpl(new AttributeDriver($paths, true, $pathsAsFilePaths));
 
         return $config;
     }
@@ -62,9 +63,10 @@ public static function createAttributeMetadataConfig(
         bool $isDevMode = false,
         string|null $cacheNamespaceSeed = null,
         CacheItemPoolInterface|null $cache = null,
+        bool $pathsAsFilePaths = false,
     ): Configuration {
         $config = self::createConfig($isDevMode, $cacheNamespaceSeed, $cache);
-        $config->setMetadataDriverImpl(new AttributeDriver($paths));
+        $config->setMetadataDriverImpl(new AttributeDriver($paths, true, $pathsAsFilePaths));
 
         return $config;
     }
diff --git a/tests/Performance/EntityManagerFactory.php b/tests/Performance/EntityManagerFactory.php
@@ -13,14 +13,13 @@
 use Doctrine\ORM\Configuration;
 use Doctrine\ORM\EntityManager;
 use Doctrine\ORM\EntityManagerInterface;
-use Doctrine\ORM\Mapping\Driver\AttributeDriver;
 use Doctrine\ORM\Proxy\ProxyFactory;
 use Doctrine\ORM\Tools\SchemaTool;
 use Doctrine\Tests\Mocks\ArrayResultFactory;
+use Doctrine\Tests\Mocks\AttributeDriverFactory;
 use Doctrine\Tests\TestUtil;
 
 use function array_map;
-use function realpath;
 
 final class EntityManagerFactory
 {
@@ -30,10 +29,7 @@ public static function getEntityManager(array $schemaClassNames): EntityManagerI
 
         TestUtil::configureProxies($config);
         $config->setAutoGenerateProxyClasses(ProxyFactory::AUTOGENERATE_EVAL);
-        $config->setMetadataDriverImpl(new AttributeDriver([
-            realpath(__DIR__ . '/Models/Cache'),
-            realpath(__DIR__ . '/Models/GeoNames'),
-        ]));
+        $config->setMetadataDriverImpl(AttributeDriverFactory::createAttributeDriver([__DIR__ . '/../Tests/Models/Cache', __DIR__ . '/../Tests/Models/GeoNames']));
 
         $entityManager = new EntityManager(
             DriverManager::getConnection([
@@ -55,11 +51,7 @@ public static function makeEntityManagerWithNoResultsConnection(): EntityManager
 
         TestUtil::configureProxies($config);
         $config->setAutoGenerateProxyClasses(ProxyFactory::AUTOGENERATE_EVAL);
-        $config->setMetadataDriverImpl(new AttributeDriver([
-            realpath(__DIR__ . '/Models/Cache'),
-            realpath(__DIR__ . '/Models/Generic'),
-            realpath(__DIR__ . '/Models/GeoNames'),
-        ]));
+        $config->setMetadataDriverImpl(AttributeDriverFactory::createAttributeDriver([__DIR__ . '/../Tests/Models/Cache', __DIR__ . '/../Tests/Models/Generic', __DIR__ . '/../Tests/Models/GeoNames']));
 
         // A connection that doesn't really do anything
         $connection = new class ([], new Driver(), null, new EventManager()) extends Connection
diff --git a/tests/Tests/Mocks/AttributeDriverFactory.php b/tests/Tests/Mocks/AttributeDriverFactory.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Tests\Mocks;
+
+use Composer\InstalledVersions;
+use Doctrine\ORM\Mapping\Driver\AttributeDriver;
+use LogicException;
+
+use function array_map;
+use function array_merge;
+use function assert;
+use function glob;
+use function realpath;
+use function version_compare;
+
+use const GLOB_BRACE;
+
+final class AttributeDriverFactory
+{
+    /** @param list<string> $paths */
+    public static function createAttributeDriver(array $paths = []): AttributeDriver
+    {
+        if (! self::isPathsFilePathsSupported()) {
+            return new AttributeDriver($paths, true, false);
+        }
+
+        $filePaths = array_merge(...array_map(self::pathFiles(...), $paths));
+
+        return new AttributeDriver($filePaths, true, true);
+    }
+
+    public static function isPathsFilePathsSupported(): bool
+    {
+        return version_compare(InstalledVersions::getVersion('doctrine/persistence'), '4.1', '>=');
+    }
+
+    /** @return list<string> */
+    public static function pathFiles(string $path): array
+    {
+        $realpath = realpath($path);
+
+        assert($realpath !== false);
+
+        return glob($realpath . '/{,*/}*.php', GLOB_BRACE)
+            ?: throw new LogicException('Could not load driver files');
+    }
+}
diff --git a/tests/Tests/Mocks/EntityManagerMock.php b/tests/Tests/Mocks/EntityManagerMock.php
@@ -8,7 +8,6 @@
 use Doctrine\DBAL\Connection;
 use Doctrine\ORM\Configuration;
 use Doctrine\ORM\EntityManager;
-use Doctrine\ORM\Mapping\Driver\AttributeDriver;
 use Doctrine\ORM\Proxy\ProxyFactory;
 use Doctrine\ORM\UnitOfWork;
 use Doctrine\Tests\TestUtil;
@@ -26,7 +25,8 @@ public function __construct(Connection $conn, Configuration|null $config = null,
         if ($config === null) {
             $config = new Configuration();
             TestUtil::configureProxies($config);
-            $config->setMetadataDriverImpl(new AttributeDriver([]));
+            $attributeDriver = AttributeDriverFactory::createAttributeDriver();
+            $config->setMetadataDriverImpl($attributeDriver);
         }
 
         parent::__construct($conn, $config, $eventManager);
diff --git a/tests/Tests/ORM/Functional/EnumTest.php b/tests/Tests/ORM/Functional/EnumTest.php
@@ -7,10 +7,10 @@
 use Doctrine\DBAL\Types\EnumType;
 use Doctrine\ORM\AbstractQuery;
 use Doctrine\ORM\Mapping\Column;
-use Doctrine\ORM\Mapping\Driver\AttributeDriver;
 use Doctrine\ORM\Mapping\MappingException;
 use Doctrine\ORM\Query\Expr\Func;
 use Doctrine\ORM\Tools\SchemaTool;
+use Doctrine\Tests\Mocks\AttributeDriverFactory;
 use Doctrine\Tests\Models\DataTransferObjects\DtoWithArrayOfEnums;
 use Doctrine\Tests\Models\DataTransferObjects\DtoWithEnum;
 use Doctrine\Tests\Models\Enums\Card;
@@ -28,7 +28,6 @@
 use PHPUnit\Framework\Attributes\DataProvider;
 
 use function class_exists;
-use function dirname;
 use function sprintf;
 use function uniqid;
 
@@ -38,7 +37,9 @@ public function setUp(): void
     {
         parent::setUp();
 
-        $this->_em         = $this->getEntityManager(null, new AttributeDriver([dirname(__DIR__, 2) . '/Models/Enums'], true));
+        $mappingDriver = AttributeDriverFactory::createAttributeDriver([__DIR__ . '/../../Models/Enums']);
+
+        $this->_em         = $this->getEntityManager(null, $mappingDriver);
         $this->_schemaTool = new SchemaTool($this->_em);
 
         if ($this->isSecondLevelCacheEnabled) {
diff --git a/tests/Tests/ORM/Functional/Locking/LockAgentWorker.php b/tests/Tests/ORM/Functional/Locking/LockAgentWorker.php
@@ -9,6 +9,7 @@
 use Doctrine\ORM\Configuration;
 use Doctrine\ORM\EntityManager;
 use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\Tests\Mocks\AttributeDriverFactory;
 use Doctrine\Tests\ORM\Functional\Locking\Doctrine\ORM\Query;
 use Doctrine\Tests\TestUtil;
 use GearmanWorker;
@@ -116,8 +117,8 @@ protected function createEntityManager(Connection $conn): EntityManagerInterface
         TestUtil::configureProxies($config);
         $config->setAutoGenerateProxyClasses(true);
 
-        $annotDriver = new AttributeDriver([__DIR__ . '/../../../Models/']);
-        $config->setMetadataDriverImpl($annotDriver);
+        $attributeDriver = AttributeDriverFactory::createAttributeDriver([__DIR__ . '/../../../Models']);
+        $config->setMetadataDriverImpl($attributeDriver);
         $config->setMetadataCache(new ArrayAdapter());
 
         $config->setQueryCache(new ArrayAdapter());
diff --git a/tests/Tests/ORM/Functional/ReadonlyPropertiesTest.php b/tests/Tests/ORM/Functional/ReadonlyPropertiesTest.php
@@ -4,16 +4,14 @@
 
 namespace Doctrine\Tests\ORM\Functional;
 
-use Doctrine\ORM\Mapping\Driver\AttributeDriver;
 use Doctrine\ORM\Tools\SchemaTool;
+use Doctrine\Tests\Mocks\AttributeDriverFactory;
 use Doctrine\Tests\Models\ReadonlyProperties\Author;
 use Doctrine\Tests\Models\ReadonlyProperties\Book;
 use Doctrine\Tests\Models\ReadonlyProperties\SimpleBook;
 use Doctrine\Tests\OrmFunctionalTestCase;
 use Doctrine\Tests\TestUtil;
 
-use function dirname;
-
 class ReadonlyPropertiesTest extends OrmFunctionalTestCase
 {
     protected function setUp(): void
@@ -22,10 +20,8 @@ protected function setUp(): void
             static::$sharedConn = TestUtil::getConnection();
         }
 
-        $this->_em         = $this->getEntityManager(null, new AttributeDriver(
-            [dirname(__DIR__, 2) . '/Models/ReadonlyProperties'],
-            true,
-        ));
+        $attributeDriver   = AttributeDriverFactory::createAttributeDriver([__DIR__ . '/../../Models/ReadonlyProperties']);
+        $this->_em         = $this->getEntityManager(null, $attributeDriver);
         $this->_schemaTool = new SchemaTool($this->_em);
 
         parent::setUp();
diff --git a/tests/Tests/ORM/Mapping/AttributeDriverTest.php b/tests/Tests/ORM/Mapping/AttributeDriverTest.php
@@ -11,6 +11,7 @@
 use Doctrine\ORM\Mapping\JoinColumnMapping;
 use Doctrine\ORM\Mapping\MappingAttribute;
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
+use Doctrine\Tests\Mocks\AttributeDriverFactory;
 use Doctrine\Tests\ORM\Mapping\Fixtures\AttributeEntityWithNestedJoinColumns;
 use InvalidArgumentException;
 use stdClass;
@@ -19,9 +20,7 @@ class AttributeDriverTest extends MappingDriverTestCase
 {
     protected function loadDriver(): MappingDriver
     {
-        $paths = [];
-
-        return new AttributeDriver($paths, true);
+        return AttributeDriverFactory::createAttributeDriver();
     }
 
     public function testOriginallyNestedAttributesDeclaredWithoutOriginalParent(): void
@@ -93,7 +92,7 @@ public function testItThrowsWhenSettingReportFieldsWhereDeclaredToFalse(): void
     {
         $this->expectException(InvalidArgumentException::class);
 
-        new AttributeDriver([], false);
+        new AttributeDriver([], false, true);
     }
 }
 
diff --git a/tests/Tests/ORM/Persisters/BinaryIdPersisterTest.php b/tests/Tests/ORM/Persisters/BinaryIdPersisterTest.php
@@ -11,6 +11,7 @@
 use Doctrine\ORM\ORMSetup;
 use Doctrine\ORM\Tools\SchemaTool;
 use Doctrine\ORM\Tools\SchemaValidator;
+use Doctrine\Tests\Mocks\AttributeDriverFactory;
 use Doctrine\Tests\Mocks\EntityManagerMock;
 use Doctrine\Tests\Models\BinaryPrimaryKey\BinaryIdType;
 use Doctrine\Tests\Models\BinaryPrimaryKey\Category;
@@ -63,7 +64,11 @@ private function createEntityManager(): EntityManager
             return $this->entityManager;
         }
 
-        $config = ORMSetup::createAttributeMetadataConfiguration([__DIR__ . '/../../Models/BinaryPrimaryKey'], isDevMode: true);
+        $config = ORMSetup::createAttributeMetadataConfiguration(
+            $this->getDriverPaths(),
+            isDevMode: true,
+            pathsAsFilePaths: AttributeDriverFactory::isPathsFilePathsSupported(),
+        );
 
         if (! DbalType::hasType(BinaryIdType::NAME)) {
             DbalType::addType(BinaryIdType::NAME, BinaryIdType::class);
@@ -82,4 +87,16 @@ private function createEntityManager(): EntityManager
 
         return $entityManager;
     }
+
+    /** @return string[] */
+    private function getDriverPaths(): array
+    {
+        $path = __DIR__ . '/../../Models/BinaryPrimaryKey';
+
+        if (! AttributeDriverFactory::isPathsFilePathsSupported()) {
+            return [$path];
+        }
+
+        return AttributeDriverFactory::pathFiles($path);
+    }
 }
diff --git a/tests/Tests/ORM/Tools/Console/Command/SchemaTool/CommandTestCase.php b/tests/Tests/ORM/Tools/Console/Command/SchemaTool/CommandTestCase.php
@@ -5,9 +5,9 @@
 namespace Doctrine\Tests\ORM\Tools\Console\Command\SchemaTool;
 
 use Doctrine\DBAL\Platforms\SQLitePlatform;
-use Doctrine\ORM\Mapping\Driver\AttributeDriver;
 use Doctrine\ORM\Tools\Console\Command\SchemaTool\AbstractCommand;
 use Doctrine\ORM\Tools\Console\EntityManagerProvider\SingleManagerProvider;
+use Doctrine\Tests\Mocks\AttributeDriverFactory;
 use Doctrine\Tests\OrmFunctionalTestCase;
 use Symfony\Component\Console\Tester\CommandTester;
 
@@ -16,9 +16,7 @@ abstract class CommandTestCase extends OrmFunctionalTestCase
     /** @param class-string<AbstractCommand> $commandClass */
     protected function getCommandTester(string $commandClass, string|null $commandName = null): CommandTester
     {
-        $entityManager = $this->getEntityManager(null, new AttributeDriver([
-            __DIR__ . '/Models',
-        ]));
+        $entityManager = $this->getEntityManager(null, AttributeDriverFactory::createAttributeDriver([__DIR__ . '/Models']));
 
         if (! $entityManager->getConnection()->getDatabasePlatform() instanceof SQLitePlatform) {
             self::markTestSkipped('We are testing the symfony/console integration');
diff --git a/tests/Tests/OrmFunctionalTestCase.php b/tests/Tests/OrmFunctionalTestCase.php
diff --git a/tests/Tests/OrmTestCase.php b/tests/Tests/OrmTestCase.php
