Allow ::referencedEntities on field items (#265)

* First stab at this

* Tiny refactor that makes more sense

* Refactor and add tests

* Fix phpstan warnings (leverage ObjectType)

* Put back items lost in rebase for property tags

* Refactor method detection, so method reflection can be used for any item list

Co-authored-by: Matt Glaman <[email protected]>

Author: eiriksm

extension.neon

@@ -281,6 +281,9 @@ services:
 	-
 		class: mglaman\PHPStanDrupal\Reflection\EntityFieldsViaMagicReflectionExtension
 		tags: [phpstan.broker.propertiesClassReflectionExtension]
+	-
+		class: mglaman\PHPStanDrupal\Reflection\EntityFieldMethodsViaMagicReflectionExtension
+		tags: [phpstan.broker.methodsClassReflectionExtension]
 	-
 		class: mglaman\PHPStanDrupal\Rules\Classes\ClassExtendsInternalClassRule
 		tags: [phpstan.rules.rule]

src/Reflection/EntityFieldMethodsViaMagicReflectionExtension.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace mglaman\PHPStanDrupal\Reflection;
+
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\MethodsClassReflectionExtension;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\ObjectType;
+
+/**
+ * Allows some common methods on fields.
+ */
+class EntityFieldMethodsViaMagicReflectionExtension implements MethodsClassReflectionExtension
+{
+
+    public function hasMethod(ClassReflection $classReflection, string $methodName): bool
+    {
+        if ($classReflection->hasNativeMethod($methodName) || array_key_exists($methodName, $classReflection->getMethodTags())) {
+            // Let other parts of PHPStan handle this.
+            return false;
+        }
+        $interfaceObject = new ObjectType('Drupal\Core\Field\FieldItemListInterface');
+        $objectType = new ObjectType($classReflection->getName());
+        if (!$interfaceObject->isSuperTypeOf($objectType)->yes()) {
+            return false;
+        }
+
+        if ($methodName === 'referencedEntities') {
+            return true;
+        }
+
+        return false;
+    }
+
+    public function getMethod(ClassReflection $classReflection, string $methodName): MethodReflection
+    {
+        if ($methodName === 'referencedEntities') {
+            $entityReferenceFieldItemListInterfaceType = new ObjectType('Drupal\Core\Field\EntityReferenceFieldItemListInterface');
+            $classReflection = $entityReferenceFieldItemListInterfaceType->getClassReflection();
+            assert($classReflection !== null);
+        }
+
+        return new FieldItemListMethodReflection(
+            $classReflection,
+            $methodName
+        );
+    }
+}

src/Reflection/EntityFieldsViaMagicReflectionExtension.php

@@ -37,7 +37,7 @@ public function hasProperty(ClassReflection $classReflection, string $propertyNa
             // Content entities have magical __get... so it is kind of true.
             return true;
         }
-        if (self::classObjectIsSuperOfFieldItemList($reflection)->yes()) {
+        if (self::classObjectIsSuperOfInterface($reflection, self::getFieldItemListInterfaceObject())->yes()) {
             return FieldItemListPropertyReflection::canHandleProperty($classReflection, $propertyName);
         }
 
@@ -50,17 +50,17 @@ public function getProperty(ClassReflection $classReflection, string $propertyNa
         if ($reflection->implementsInterface('Drupal\Core\Entity\EntityInterface')) {
             return new EntityFieldReflection($classReflection, $propertyName);
         }
-        if (self::classObjectIsSuperOfFieldItemList($reflection)->yes()) {
+        if (self::classObjectIsSuperOfInterface($reflection, self::getFieldItemListInterfaceObject())->yes()) {
             return new FieldItemListPropertyReflection($classReflection, $propertyName);
         }
 
         throw new \LogicException($classReflection->getName() . "::$propertyName should be handled earlier.");
     }
 
-    protected static function classObjectIsSuperOfFieldItemList(\ReflectionClass $reflection) : TrinaryLogic
+    public static function classObjectIsSuperOfInterface(\ReflectionClass $reflection, ObjectType $interfaceObject) : TrinaryLogic
     {
         $classObject = new ObjectType($reflection->getName());
-        return self::getFieldItemListInterfaceObject()->isSuperTypeOf($classObject);
+        return $interfaceObject->isSuperTypeOf($classObject);
     }
 
     protected static function getFieldItemListInterfaceObject() : ObjectType

src/Reflection/FieldItemListMethodReflection.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace mglaman\PHPStanDrupal\Reflection;
+
+use Drupal\Core\Field\EntityReferenceFieldItemListInterface;
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\ClassMemberReflection;
+use PHPStan\Reflection\ReflectionProviderStaticAccessor;
+use PHPStan\Reflection\TrivialParametersAcceptor;
+use PHPStan\ShouldNotHappenException;
+use PHPStan\TrinaryLogic;
+use PHPStan\Type\NullType;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\StringType;
+use PHPStan\Type\Type;
+
+/**
+ * Allows field access to common methods.
+ */
+class FieldItemListMethodReflection implements MethodReflection
+{
+
+    /** @var ClassReflection */
+    private $declaringClass;
+
+    /** @var string */
+    private $methodName;
+
+    public function __construct(ClassReflection $declaringClass, string $methodName)
+    {
+        $this->declaringClass = $declaringClass;
+        $this->methodName = $methodName;
+    }
+
+    public function getDeclaringClass(): ClassReflection
+    {
+        return $this->declaringClass;
+    }
+
+    public function isStatic(): bool
+    {
+        return false;
+    }
+
+    public function isPrivate(): bool
+    {
+        return false;
+    }
+
+    public function isPublic(): bool
+    {
+        return true;
+    }
+
+    public function getDocComment(): ?string
+    {
+        return null;
+    }
+
+    public function getName(): string
+    {
+        return $this->methodName;
+    }
+
+    public function getPrototype(): ClassMemberReflection
+    {
+        return $this;
+    }
+
+    /**
+     * @return \PHPStan\Reflection\ParametersAcceptor[]
+     */
+    public function getVariants(): array
+    {
+        return [
+            new TrivialParametersAcceptor(),
+        ];
+    }
+
+    public function isDeprecated(): TrinaryLogic
+    {
+        return TrinaryLogic::createNo();
+    }
+
+    public function getDeprecatedDescription(): ?string
+    {
+        return '';
+    }
+
+    public function isFinal(): TrinaryLogic
+    {
+        return TrinaryLogic::createYes();
+    }
+
+    public function isInternal(): TrinaryLogic
+    {
+        return TrinaryLogic::createNo();
+    }
+
+    public function getThrowType(): ?Type
+    {
+        return null;
+    }
+
+    public function hasSideEffects(): TrinaryLogic
+    {
+        return TrinaryLogic::createNo();
+    }
+}

tests/src/Reflection/EntityFieldMethodsViaMagicReflectionExtensionTest.php

@@ -0,0 +1,57 @@
+<?php declare(strict_types=1);
+
+namespace mglaman\PHPStanDrupal\Tests\Reflection;
+
+use Drupal\Core\Field\FieldItemListInterface;
+use Drupal\entity_test\Entity\EntityTest;
+use Drupal\node\Entity\Node;
+use mglaman\PHPStanDrupal\Reflection\EntityFieldMethodsViaMagicReflectionExtension;
+use mglaman\PHPStanDrupal\Tests\AdditionalConfigFilesTrait;
+use PHPStan\Testing\PHPStanTestCase;
+
+final class EntityFieldMethodsViaMagicReflectionExtensionTest extends PHPStanTestCase {
+
+    use AdditionalConfigFilesTrait;
+
+    /**
+     * @var \mglaman\PHPStanDrupal\Reflection\EntityFieldMethodsViaMagicReflectionExtension
+     */
+    private $extension;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->extension = new EntityFieldMethodsViaMagicReflectionExtension();
+    }
+
+    /**
+     * @dataProvider dataHasMethod
+     *
+     * @param string $method
+     * @param bool $result
+     */
+    public function testHasMethod(string $class, string $method, bool $result): void
+    {
+        $reflection = $this->createReflectionProvider()->getClass($class);
+        self::assertEquals($result, $this->extension->hasMethod($reflection, $method));
+    }
+
+    public function dataHasMethod(): \Generator
+    {
+        // Technically it does not have this method. But we allow it for now.
+        yield 'field item list: referencedEntities' => [
+            FieldItemListInterface::class,
+            'referencedEntities',
+            true,
+        ];
+
+        // A content entity for sure does not have this method.
+        yield 'Content entity: referencedEntities' => [
+            // @phpstan-ignore-next-line
+            EntityTest::class,
+            'referencedEntities',
+            false,
+        ];
+    }
+
+}