DeclarationDependencyTracker for extensions describing a class

Class reflection extensions and other extensions describing a class get no
Scope, and what they declare is remembered and reused by every file analysed
after it without asking the extension again. So it's the class that depends
on what the extension read, not the file being analysed.

DeclarationDependencyTracker, injected into such an extension, records the
value, file, directory or class dependency for the class. The values are
kept for the whole process, and every file depending on the class - or on a
class extending or implementing it - gets them as its own dependencies when
its analysis finishes. When one changes, all those files are analysed again.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GdwtgiEHwkF5BTz73jgHQQ

Author: ondrejmirtes

.github/workflows/e2e-tests.yml

@@ -579,6 +579,16 @@ jobs:
               OUTPUT=$(../bashunit -a exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
               echo "$OUTPUT"
               ../bashunit -a contains 'UsesMake.php:7:Function ResultCacheE2EValueDependency\usesMake() should return int but returns string.' "$OUTPUT"
+              # A class reflection extension tracking on the class: every file using the class is analysed again,
+              # also one that got the magic method from the reflection cache without asking the extension.
+              php -r '$c = json_decode(file_get_contents("container.json"), true); $c["parameters"]["greeting"] = "1"; file_put_contents("container.json", json_encode($c, JSON_PRETTY_PRINT));'
+              INFO=$(../../bin/phpstan result-cache-info --json)
+              echo "$INFO"
+              ../bashunit -a equals '3' "$(echo "$INFO" | jq --raw-output '.filesToAnalyseCount')"
+              OUTPUT=$(../bashunit -a exit_code "1" "../../bin/phpstan analyse -vv --error-format raw")
+              echo "$OUTPUT"
+              ../bashunit -a contains 'UsesMagic.php:7:Function ResultCacheE2EValueDependency\usesMagic() should return string but returns int.' "$OUTPUT"
+              ../bashunit -a contains 'UsesMagicToo.php:7:Function ResultCacheE2EValueDependency\usesMagicToo() should return string but returns int.' "$OUTPUT"
           - script: |
               cd e2e/result-cache-file-dependency
               composer install

e2e/result-cache-value-dependency/container.json

@@ -10,6 +10,7 @@
 		"throwing": "no",
 		"region": "eu",
 		"closureThis": "ResultCacheE2EValueDependency\\Mailer",
-		"allowedClass": "ResultCacheE2EValueDependency\\Mailer"
+		"allowedClass": "ResultCacheE2EValueDependency\\Mailer",
+		"greeting": "hello"
 	}
 }

e2e/result-cache-value-dependency/extension/MagicMethodReflection.php

@@ -0,0 +1,90 @@
+<?php declare(strict_types = 1);
+
+namespace ResultCacheE2EValueDependency;
+
+use PHPStan\Reflection\ClassMemberReflection;
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\FunctionVariant;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\TrinaryLogic;
+use PHPStan\Type\Generic\TemplateTypeMap;
+use PHPStan\Type\Type;
+
+final class MagicMethodReflection implements MethodReflection
+{
+
+	public function __construct(private ClassReflection $declaringClass, private string $name, private Type $returnType)
+	{
+	}
+
+	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->name;
+	}
+
+	public function getPrototype(): ClassMemberReflection
+	{
+		return $this;
+	}
+
+	public function getVariants(): array
+	{
+		return [new FunctionVariant(TemplateTypeMap::createEmpty(), null, [], false, $this->returnType)];
+	}
+
+	public function isDeprecated(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
+	public function getDeprecatedDescription(): ?string
+	{
+		return null;
+	}
+
+	public function isFinal(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
+	public function isInternal(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
+	public function getThrowType(): ?Type
+	{
+		return null;
+	}
+
+	public function hasSideEffects(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
+}

e2e/result-cache-value-dependency/extension/MagicMethodsExtension.php

@@ -0,0 +1,41 @@
+<?php declare(strict_types = 1);
+
+namespace ResultCacheE2EValueDependency;
+
+use PHPStan\Analyser\DeclarationDependencyTracker;
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\MethodsClassReflectionExtension;
+use PHPStan\Type\Constant\ConstantIntegerType;
+use PHPStan\Type\Constant\ConstantStringType;
+
+/**
+ * Magic::greet() returns the "greeting" parameter - an int when it's numeric. A class reflection
+ * extension gets no Scope, and what it declares is reused by every file using the class, so it
+ * tracks the parameter on the class.
+ */
+final class MagicMethodsExtension implements MethodsClassReflectionExtension
+{
+
+	public function __construct(private DeclarationDependencyTracker $declarationDependencyTracker)
+	{
+	}
+
+	public function hasMethod(ClassReflection $classReflection, string $methodName): bool
+	{
+		return $classReflection->getName() === Magic::class && $methodName === 'greet';
+	}
+
+	public function getMethod(ClassReflection $classReflection, string $methodName): MethodReflection
+	{
+		$this->declarationDependencyTracker->trackValueDependency($classReflection, ParameterValueExtension::class, 'greeting');
+		$greeting = Container::getParameter('greeting') ?? '';
+
+		return new MagicMethodReflection(
+			$classReflection,
+			$methodName,
+			is_numeric($greeting) ? new ConstantIntegerType((int) $greeting) : new ConstantStringType($greeting),
+		);
+	}
+
+}

e2e/result-cache-value-dependency/phpstan.neon

@@ -54,3 +54,7 @@ services:
 		class: ResultCacheE2EValueDependency\MakeReturnTypeExtension
 		tags:
 			- phpstan.broker.dynamicFunctionReturnTypeExtension
+	-
+		class: ResultCacheE2EValueDependency\MagicMethodsExtension
+		tags:
+			- phpstan.broker.methodsClassReflectionExtension

e2e/result-cache-value-dependency/src/Magic.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace ResultCacheE2EValueDependency;
+
+/**
+ * greet() comes from MagicMethodsExtension.
+ */
+class Magic
+{
+
+}

e2e/result-cache-value-dependency/src/UsesMagic.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace ResultCacheE2EValueDependency;
+
+function usesMagic(Magic $magic): string
+{
+	return $magic->greet();
+}

e2e/result-cache-value-dependency/src/UsesMagicToo.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace ResultCacheE2EValueDependency;
+
+function usesMagicToo(Magic $magic): string
+{
+	return $magic->greet();
+}

src/Analyser/DeclarationDependencyTracker.php

@@ -0,0 +1,49 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Analyser;
+
+use PHPStan\Analyser\ResultCache\ResultCacheValueExtension;
+use PHPStan\Reflection\ClassReflection;
+
+/**
+ * DependencyTracker for extensions that get no Scope because they describe a class rather than
+ * analyse code - class reflection extensions adding magic methods and properties, for example. Inject
+ * it into the extension's constructor.
+ *
+ * What PHPStan learns about a class this way is remembered and reused by every file analysed after
+ * it, so it's the class that depends on what the extension read, not the file being analysed: each
+ * method declares the dependency of $classReflection. When it changes, every file depending on the
+ * class - referencing it, calling its methods, reading its properties - is analysed again.
+ *
+ * @api
+ */
+interface DeclarationDependencyTracker
+{
+
+	/**
+	 * What $classReflection declares depends on the value $extensionClass gives for $key - see
+	 * DependencyTracker::trackValueDependency().
+	 *
+	 * @param class-string<ResultCacheValueExtension> $extensionClass
+	 */
+	public function trackValueDependency(ClassReflection $classReflection, string $extensionClass, string $key): void;
+
+	/**
+	 * What $classReflection declares depends on the contents of $file - see
+	 * DependencyTracker::trackFileDependency().
+	 */
+	public function trackFileDependency(ClassReflection $classReflection, string $file): void;
+
+	/**
+	 * What $classReflection declares depends on which files there are in $directory - see
+	 * DependencyTracker::trackDirectoryDependency().
+	 */
+	public function trackDirectoryDependency(ClassReflection $classReflection, string $directory, string $pattern = '*'): void;
+
+	/**
+	 * What $classReflection declares depends on what the class $className declares - see
+	 * DependencyTracker::trackClassDependency().
+	 */
+	public function trackClassDependency(ClassReflection $classReflection, string $className): void;
+
+}

src/Analyser/DependencyTracker.php

@@ -24,6 +24,9 @@
  * It tracks what the analysis of the current file depends on besides the analysed code, so that
  * the result cache re-analyses the file when that changes - see ResultCacheValueExtension.
  *
+ * Extensions that get no Scope because they describe a class - class reflection extensions - use
+ * DeclarationDependencyTracker instead.
+ *
  * @api
  */
 interface DependencyTracker