Feature: add support for $sourceFilePathNames

rela589n · rela589n · commit 8794b184ae37 · 2025-08-07T11:01:30.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. The new behaviour is adapted by using `glob()` on 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 {@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
