Add optional phpstan-doctrine integration for metadata resolution (#33)

Author: JanTvrdik

README.md

@@ -63,6 +63,8 @@ includes:
     - vendor/shipmonk/doctrine-entity-preloader/rules.neon
 ```
 
+If [phpstan/phpstan-doctrine](https://github.com/phpstan/phpstan-doctrine) is installed, real Doctrine metadata will be used for more accurate type inference.
+
 ## Usage
 
 Below is a basic example demonstrating how to use `EntityPreloader` to preload related entities and avoid the n+1 problem:

composer-dependency-analyser.php

@@ -6,4 +6,5 @@
 return (new Configuration())
     ->ignoreUnknownFunctions(['PHPStan\Testing\assertType'])
     ->ignoreErrorsOnPackage('nikic/php-parser', [ErrorType::DEV_DEPENDENCY_IN_PROD])
-    ->ignoreErrorsOnPackage('phpstan/phpstan', [ErrorType::DEV_DEPENDENCY_IN_PROD]);
+    ->ignoreErrorsOnPackage('phpstan/phpstan', [ErrorType::DEV_DEPENDENCY_IN_PROD])
+    ->ignoreErrorsOnPackage('phpstan/phpstan-doctrine', [ErrorType::DEV_DEPENDENCY_IN_PROD]);

composer.json

@@ -12,15 +12,16 @@
     "require-dev": {
         "composer/semver": "^3.0",
         "doctrine/collections": "^2.2",
-        "doctrine/persistence": "^3.3 || ^4.0",
+        "doctrine/persistence": "^3.4.3 || ^4.0",
         "editorconfig-checker/editorconfig-checker": "^10.6.0",
         "ergebnis/composer-normalize": "^2.42.0",
         "nette/utils": "^4",
         "nikic/php-parser": "^5.6",
         "phpstan/phpstan": "^2.1.26",
+        "phpstan/phpstan-doctrine": "^2.0",
         "phpstan/phpstan-phpunit": "^2.0",
         "phpstan/phpstan-strict-rules": "^2.0",
-        "phpunit/phpunit": "^10.5",
+        "phpunit/phpunit": "^10.5.60",
         "psr/log": "^3",
         "shipmonk/coding-standard": "^0.2.0",
         "shipmonk/composer-dependency-analyser": "^1.7",
@@ -29,6 +30,9 @@
         "shipmonk/phpstan-rules": "^4.0",
         "symfony/cache": "^6 || ^7 || ^8"
     },
+    "suggest": {
+        "phpstan/phpstan-doctrine": "For enhanced Doctrine metadata resolution using real ORM mappings (^2.0)"
+    },
     "autoload": {
         "psr-4": {
             "ShipMonk\\DoctrineEntityPreloader\\": "src/"

src/PHPStan/EntityPreloaderCore.php

@@ -10,6 +10,7 @@
 use PHPStan\Analyser\Scope;
 use PHPStan\Type\Accessory\AccessoryArrayListType;
 use PHPStan\Type\ArrayType;
+use PHPStan\Type\Doctrine\ObjectMetadataResolver;
 use PHPStan\Type\IntegerType;
 use PHPStan\Type\IntersectionType;
 use PHPStan\Type\ObjectType;
@@ -25,6 +26,12 @@
 abstract class EntityPreloaderCore
 {
 
+    public function __construct(
+        private ?ObjectMetadataResolver $objectMetadataResolver = null,
+    )
+    {
+    }
+
     protected function getPreloadedPropertyName(
         MethodCall $methodCall,
         Scope $scope,
@@ -147,20 +154,58 @@ private function getAssociationTargetTypeFromObjectType(
             throw EntityPreloaderRuleException::classNotFound($type->getClassName());
         }
 
+        if ($this->objectMetadataResolver !== null) {
+            return $this->getAssociationTargetTypeFromMetadata(
+                $this->objectMetadataResolver,
+                $classReflection->getName(),
+                $propertyName,
+            );
+        }
+
         for ($currentClassReflection = $classReflection; $currentClassReflection !== null; $currentClassReflection = $currentClassReflection->getParentClass()) {
             if ($currentClassReflection->hasInstanceProperty($propertyName)) {
                 $propertyReflection = $currentClassReflection->getNativeProperty($propertyName)->getNativeReflection();
-                return $this->getAssociationTargetTypeFromPropertyReflection($propertyReflection);
+                return $this->getAssociationTargetTypeFromPropertyReflection($classReflection->getName(), $propertyReflection);
             }
         }
 
         throw EntityPreloaderRuleException::propertyNotFound($classReflection->getName(), $propertyName);
     }
 
     /**
+     * @param class-string $className
+     *
      * @throws EntityPreloaderRuleException
      */
-    private function getAssociationTargetTypeFromPropertyReflection(ReflectionProperty $propertyReflection): Type
+    private function getAssociationTargetTypeFromMetadata(
+        ObjectMetadataResolver $metadataResolver,
+        string $className,
+        string $propertyName,
+    ): Type
+    {
+        $classMetadata = $metadataResolver->getClassMetadata($className);
+
+        if ($classMetadata === null) {
+            throw EntityPreloaderRuleException::classNotFound($className);
+        }
+
+        if (!$classMetadata->hasAssociation($propertyName)) {
+            throw $classMetadata->hasField($propertyName)
+                ? EntityPreloaderRuleException::invalidAssociations($className, $propertyName)
+                : EntityPreloaderRuleException::propertyNotFound($className, $propertyName);
+        }
+
+        $associationMapping = $classMetadata->getAssociationMapping($propertyName);
+        return new ObjectType($associationMapping['targetEntity']);
+    }
+
+    /**
+     * @throws EntityPreloaderRuleException
+     */
+    private function getAssociationTargetTypeFromPropertyReflection(
+        string $className,
+        ReflectionProperty $propertyReflection,
+    ): Type
     {
         $associationAttributes = [
             OneToOne::class,
@@ -182,7 +227,7 @@ private function getAssociationTargetTypeFromPropertyReflection(ReflectionProper
             }
         }
 
-        throw EntityPreloaderRuleException::invalidAssociations($propertyReflection->getDeclaringClass()->getName(), $propertyReflection->getName());
+        throw EntityPreloaderRuleException::invalidAssociations($className, $propertyReflection->getName());
     }
 
     protected function createListType(Type $type): Type

tests/PHPStan/Data/EntityPreloaderRuleTestData.php

@@ -37,7 +37,7 @@ public function preloadOneHasMany(): void
         assertType('list<ShipMonkTests\DoctrineEntityPreloader\Fixtures\Blog\Article>', $this->entityPreloader->preload($categories, 'articles'));
         assertType('list<object>', $this->entityPreloader->preload($categories, 'notFound')); // error: Property 'ShipMonkTests\DoctrineEntityPreloader\Fixtures\Blog\Category::$notFound' not found.
         assertType('list<object>', $this->entityPreloader->preload($categories, 'name')); // error: Property 'ShipMonkTests\DoctrineEntityPreloader\Fixtures\Blog\Category::$name' is not a valid Doctrine association.
-        assertType('list<object>', $this->entityPreloader->preload($categories, 'id')); // error: Property 'ShipMonkTests\DoctrineEntityPreloader\Fixtures\Blog\TestEntityWithCustomPrimaryKey::$id' is not a valid Doctrine association.
+        assertType('list<object>', $this->entityPreloader->preload($categories, 'id')); // error: Property 'ShipMonkTests\DoctrineEntityPreloader\Fixtures\Blog\Category::$id' is not a valid Doctrine association.
 
         $bots = $this->entityManager->getRepository(Bot::class)->findAll();
         assertType('list<ShipMonkTests\DoctrineEntityPreloader\Fixtures\Blog\Comment>', $this->entityPreloader->preload($bots, 'comments'));

tests/PHPStan/EntityPreloaderReturnTypeExtensionTest.php

@@ -4,16 +4,10 @@
 
 use PHPStan\Testing\TypeInferenceTestCase;
 use PHPUnit\Framework\Attributes\DataProvider;
-use ShipMonk\DoctrineEntityPreloader\PHPStan\EntityPreloaderRule;
 
 final class EntityPreloaderReturnTypeExtensionTest extends TypeInferenceTestCase
 {
 
-    protected function getRule(): EntityPreloaderRule
-    {
-        return new EntityPreloaderRule();
-    }
-
     #[DataProvider('provideTypeAssertsData')]
     public function testTypeAsserts(
         string $assertType,

tests/PHPStan/EntityPreloaderReturnTypeExtensionWithMetadataTest.php

@@ -0,0 +1,37 @@
+<?php declare(strict_types = 1);
+
+namespace ShipMonkTests\DoctrineEntityPreloader\PHPStan;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+final class EntityPreloaderReturnTypeExtensionWithMetadataTest extends TypeInferenceTestCase
+{
+
+    #[DataProvider('provideTypeAssertsData')]
+    public function testTypeAsserts(
+        string $assertType,
+        string $file,
+        mixed ...$args,
+    ): void
+    {
+        $this->assertFileAsserts($assertType, $file, ...$args);
+    }
+
+    public static function provideTypeAssertsData(): iterable
+    {
+        yield from self::gatherAssertTypes(__DIR__ . '/Data/EntityPreloaderRuleTestData.php');
+    }
+
+    /**
+     * @return list<string>
+     */
+    public static function getAdditionalConfigFiles(): array
+    {
+        return [
+            __DIR__ . '/phpstan-doctrine.neon',
+            __DIR__ . '/../../extension.neon',
+        ];
+    }
+
+}

tests/PHPStan/EntityPreloaderRuleWithMetadataTest.php

@@ -0,0 +1,37 @@
+<?php declare(strict_types = 1);
+
+namespace ShipMonkTests\DoctrineEntityPreloader\PHPStan;
+
+use PHPStan\Rules\Rule;
+use PHPStan\Type\Doctrine\ObjectMetadataResolver;
+use ShipMonk\DoctrineEntityPreloader\PHPStan\EntityPreloaderRule;
+use ShipMonk\PHPStanDev\RuleTestCase;
+
+/**
+ * @extends RuleTestCase<EntityPreloaderRule>
+ */
+final class EntityPreloaderRuleWithMetadataTest extends RuleTestCase
+{
+
+    protected function getRule(): Rule
+    {
+        return new EntityPreloaderRule(new ObjectMetadataResolver( // @phpstan-ignore phpstanApi.constructor
+            __DIR__ . '/object-manager-loader.php',
+            __DIR__ . '/../../cache',
+        ));
+    }
+
+    public function testRule(): void
+    {
+        $this->analyzeFiles([__DIR__ . '/Data/EntityPreloaderRuleTestData.php']);
+    }
+
+    /**
+     * @return list<string>
+     */
+    public static function getAdditionalConfigFiles(): array
+    {
+        return [__DIR__ . '/../../extension.neon'];
+    }
+
+}

tests/PHPStan/object-manager-loader.php

@@ -0,0 +1,20 @@
+<?php declare(strict_types = 1);
+
+use Doctrine\DBAL\DriverManager;
+use Doctrine\ORM\EntityManager;
+use Doctrine\ORM\Mapping\UnderscoreNamingStrategy;
+use Doctrine\ORM\ORMSetup;
+
+// Use new non-deprecated API on Doctrine ORM 3.5+ with PHP 8.4+
+if (PHP_VERSION_ID >= 8_04_00 && method_exists(ORMSetup::class, 'createAttributeMetadataConfig')) { // @phpstan-ignore function.alreadyNarrowedType (BC for older Doctrine)
+    $config = ORMSetup::createAttributeMetadataConfig([__DIR__ . '/../Fixtures'], isDevMode: true);
+    $config->enableNativeLazyObjects(true);
+} else {
+    $config = ORMSetup::createAttributeMetadataConfiguration([__DIR__ . '/../Fixtures'], isDevMode: true, proxyDir: __DIR__ . '/../../cache/proxies');
+}
+
+$config->setNamingStrategy(new UnderscoreNamingStrategy());
+
+$connection = DriverManager::getConnection(['driver' => 'pdo_sqlite', 'memory' => true], $config);
+
+return new EntityManager($connection, $config);

tests/PHPStan/phpstan-doctrine.neon

@@ -0,0 +1,6 @@
+includes:
+    - ../../vendor/phpstan/phpstan-doctrine/extension.neon
+
+parameters:
+    doctrine:
+        objectManagerLoader: %rootDir%/../../../tests/PHPStan/object-manager-loader.php