Feature: Support ClassLocator from doctrine/persistence 4.1 and first steps to be compatible with the new persistence 4.1(#875)

* Make signatures forward-comaptible with doctrine/persistence 4.x

These changes are the first of migration toward doctrine/persistence 4.0.
Most of the signatures that could've been made compatible have been made compatible.
There are some other, which require more in-depth knowledge of repository to adjust / rework.

* Add support for `ClassLocator` from doctrine/persistence 4.1

These changes integrate doctrine/persistence#433
`ClassLocator` allows clients to pass any iterable of classes they might want.

Author: rela589n

.phpstan/phpstan-baseline.neon

@@ -40,3 +40,24 @@ parameters:
             message: "#^Call to an undefined method Doctrine\\\\ODM\\\\PHPCR\\\\Query\\\\Builder\\\\AbstractNode\\:\\:setConverter\\(\\)\\.$#"
             count: 1
             path: ../tests/Doctrine/Tests/ODM/PHPCR/Query/Builder/QueryBuilderTest.php
+
+        -
+            message: '#^Access to an undefined property Doctrine\\ODM\\PHPCR\\Mapping\\Driver\\AttributeDriver\:\:\$classLocator\.$#'
+            identifier: property.notFound
+            count: 1
+            path: ../lib/Doctrine/ODM/PHPCR/Mapping/Driver/AttributeDriver.php
+            reportUnmatched: false
+
+        -
+            message: '#^Class Doctrine\\Persistence\\Mapping\\Driver\\ClassLocator not found\.$#'
+            identifier: class.notFound
+            count: 1
+            path: ../lib/Doctrine/ODM/PHPCR/Mapping/Driver/AttributeDriver.php
+            reportUnmatched: false
+
+        -
+            message: '#^Parameter \$paths of method Doctrine\\ODM\\PHPCR\\Mapping\\Driver\\AttributeDriver\:\:__construct\(\) has invalid type Doctrine\\Persistence\\Mapping\\Driver\\ClassLocator\.$#'
+            identifier: class.notFound
+            count: 2
+            path: ../lib/Doctrine/ODM/PHPCR/Mapping/Driver/AttributeDriver.php
+            reportUnmatched: false

lib/Doctrine/ODM/PHPCR/Decorator/DocumentManagerDecorator.php

@@ -7,6 +7,7 @@
 use Doctrine\ODM\PHPCR\ChildrenCollection;
 use Doctrine\ODM\PHPCR\Configuration;
 use Doctrine\ODM\PHPCR\DocumentManagerInterface;
+use Doctrine\ODM\PHPCR\Mapping\ClassMetadata as PhpcrClassMetadata;
 use Doctrine\ODM\PHPCR\Proxy\ProxyFactory;
 use Doctrine\ODM\PHPCR\Query\Builder\QueryBuilder;
 use Doctrine\ODM\PHPCR\Query\Query;
@@ -38,6 +39,12 @@ public function __construct(DocumentManagerInterface $wrapped)
         $this->wrapped = $wrapped;
     }
 
+    /** @noinspection SenselessMethodDuplicationInspection - return type is made more specific to match {@see DocumentManagerInterface::getClassMetadata()} */
+    public function getClassMetadata(string $className): PhpcrClassMetadata
+    {
+        return $this->wrapped->getClassMetadata($className);
+    }
+
     public function setTranslationStrategy(string $key, TranslationStrategyInterface $strategy): void
     {
         $this->wrapped->setTranslationStrategy($key, $strategy);

lib/Doctrine/ODM/PHPCR/DocumentManagerInterface.php

@@ -45,13 +45,11 @@
 interface DocumentManagerInterface extends ObjectManager
 {
     /**
-     * @{@inheritDoc}
-     *
-     * Overwritten to tighten return type. We can't tighten the return type declaration because of Doctrine\Persistence\ObjectManagerDecorator.
+     * {@inheritdoc}
      *
-     * @return PhpcrClassMetadata
+     * Overwritten to tighten the return type.
      */
-    public function getClassMetadata(string $className);
+    public function getClassMetadata(string $className): PhpcrClassMetadata;
 
     /**
      * Add or replace a translation strategy.

lib/Doctrine/ODM/PHPCR/Mapping/ClassMetadata.php

@@ -1317,7 +1317,7 @@ public function getAssociationTargetClass($fieldName): ?string
         return $this->mappings[$fieldName]['targetDocument'];
     }
 
-    public function getAssociationMappedByTargetField($assocName)
+    public function getAssociationMappedByTargetField($assocName): string
     {
         throw new BadMethodCallException(sprintf(
             '%s not yet implemented in "%s"',
@@ -1326,7 +1326,7 @@ public function getAssociationMappedByTargetField($assocName)
         ));
     }
 
-    public function isAssociationInverseSide($assocName)
+    public function isAssociationInverseSide($assocName): bool
     {
         throw new BadMethodCallException(sprintf(
             '%s not yet implemented in "%s"',

lib/Doctrine/ODM/PHPCR/Mapping/Driver/AttributeDriver.php

@@ -27,6 +27,7 @@
 use Doctrine\ODM\PHPCR\Mapping\ClassMetadata;
 use Doctrine\ODM\PHPCR\Mapping\MappingException;
 use Doctrine\Persistence\Mapping\ClassMetadata as PersistenceClassMetadata;
+use Doctrine\Persistence\Mapping\Driver\ClassLocator;
 use Doctrine\Persistence\Mapping\Driver\ColocatedMappingDriver;
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
 
@@ -55,15 +56,20 @@ class AttributeDriver implements MappingDriver
     private AttributeReader $reader;
 
     /**
-     * @param array<string> $paths
+     * @param array<string>|ClassLocator $paths directory paths or class locator
      */
-    public function __construct(array $paths)
+    public function __construct(array|ClassLocator $paths)
     {
         $this->reader = new AttributeReader();
-        $this->addPaths($paths);
+
+        if ($paths instanceof ClassLocator) {
+            $this->classLocator = $paths;
+        } else {
+            $this->addPaths($paths);
+        }
     }
 
-    public function isTransient($className)
+    public function isTransient($className): bool
     {
         $classAttributes = $this->reader->getClassAttributes(new \ReflectionClass($className));
 

lib/Doctrine/ODM/PHPCR/Mapping/Driver/YamlDriver.php

@@ -262,7 +262,7 @@ private function addMappingFromReference(ClassMetadata $class, string $fieldName
         }
     }
 
-    protected function loadMappingFile($file)
+    protected function loadMappingFile($file): array
     {
         if (!is_file($file)) {
             throw new InvalidArgumentException(sprintf('File "%s" not found', $file));

tests/Doctrine/Tests/ODM/PHPCR/Mapping/AttributeDriverTest.php

@@ -3,24 +3,28 @@
 namespace Doctrine\Tests\ODM\PHPCR\Mapping;
 
 use Doctrine\ODM\PHPCR\Mapping\Driver\AttributeDriver;
+use Doctrine\Persistence\Mapping\Driver\FileClassLocator;
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
 
 /**
  * @group mapping
  */
 class AttributeDriverTest extends AbstractMappingDriverTest
 {
-    protected function loadDriver(): AttributeDriver
+    /** @param list<string> $paths */
+    protected function loadDriver(array $paths = []): AttributeDriver
     {
-        return new AttributeDriver([]);
+        // Available in Doctrine Persistence 4.1+
+        if (class_exists(FileClassLocator::class)) {
+            $paths = FileClassLocator::createFromDirectories($paths);
+        }
+
+        return new AttributeDriver($paths);
     }
 
     protected function loadDriverForTestMappingDocuments(): MappingDriver
     {
-        $attributeDriver = $this->loadDriver();
-        $attributeDriver->addPaths([__DIR__.'/Model']);
-
-        return $attributeDriver;
+        return $this->loadDriver([__DIR__.'/Model']);
     }
 
     /**