Support for @final PHPDoc tag above properties

lpd-au · web-flow · commit 2fb3dbe48236 · 2025-05-14T15:00:58.000+02:00
diff --git a/src/Reflection/Annotations/AnnotationPropertyReflection.php b/src/Reflection/Annotations/AnnotationPropertyReflection.php
@@ -119,6 +119,11 @@ public function isAbstract(): TrinaryLogic
 		return TrinaryLogic::createNo();
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return TrinaryLogic::createNo();
diff --git a/src/Reflection/Dummy/ChangedTypePropertyReflection.php b/src/Reflection/Dummy/ChangedTypePropertyReflection.php
@@ -116,6 +116,11 @@ public function isAbstract(): TrinaryLogic
 		return $this->reflection->isAbstract();
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return $this->reflection->isFinalByKeyword();
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return $this->reflection->isFinal();
diff --git a/src/Reflection/Dummy/DummyPropertyReflection.php b/src/Reflection/Dummy/DummyPropertyReflection.php
@@ -116,6 +116,11 @@ public function isAbstract(): TrinaryLogic
 		return TrinaryLogic::createNo();
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return TrinaryLogic::createNo();
diff --git a/src/Reflection/ExtendedPropertyReflection.php b/src/Reflection/ExtendedPropertyReflection.php
@@ -38,6 +38,8 @@ public function getNativeType(): Type;
 
 	public function isAbstract(): TrinaryLogic;
 
+	public function isFinalByKeyword(): TrinaryLogic;
+
 	public function isFinal(): TrinaryLogic;
 
 	public function isVirtual(): TrinaryLogic;
diff --git a/src/Reflection/Php/EnumPropertyReflection.php b/src/Reflection/Php/EnumPropertyReflection.php
@@ -112,6 +112,11 @@ public function isAbstract(): TrinaryLogic
 		return TrinaryLogic::createNo();
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return TrinaryLogic::createNo();
diff --git a/src/Reflection/Php/PhpClassReflectionExtension.php b/src/Reflection/Php/PhpClassReflectionExtension.php
@@ -218,7 +218,7 @@ private function createProperty(
 					$types[] = $value;
 				}
 
-				return new PhpPropertyReflection($declaringClassReflection, null, null, TypeCombinator::union(...$types), $classReflection->getNativeReflection()->getProperty($propertyName), null, null, null, false, false, false, false, []);
+				return new PhpPropertyReflection($declaringClassReflection, null, null, TypeCombinator::union(...$types), $classReflection->getNativeReflection()->getProperty($propertyName), null, null, null, false, false, false, false, [], false);
 			}
 		}
 
@@ -227,6 +227,7 @@ private function createProperty(
 		$isDeprecated = $deprecation !== null;
 		$isInternal = false;
 		$isReadOnlyByPhpDoc = $classReflection->isImmutable();
+		$isFinal = $classReflection->isFinal() || $propertyReflection->isFinal();
 		$isAllowedPrivateMutation = false;
 
 		if (
@@ -308,6 +309,7 @@ private function createProperty(
 			}
 			$isInternal = $resolvedPhpDoc->isInternal();
 			$isReadOnlyByPhpDoc = $isReadOnlyByPhpDoc || $resolvedPhpDoc->isReadOnly();
+			$isFinal = $isFinal || $resolvedPhpDoc->isFinal();
 			$isAllowedPrivateMutation = $resolvedPhpDoc->isAllowedPrivateMutation();
 		}
 
@@ -435,6 +437,7 @@ private function createProperty(
 			$isReadOnlyByPhpDoc,
 			$isAllowedPrivateMutation,
 			$this->attributeReflectionFactory->fromNativeReflection($propertyReflection->getAttributes(), InitializerExprContext::fromClass($declaringClassReflection->getName(), $declaringClassReflection->getFileName())),
+			$isFinal,
 		);
 	}
 
diff --git a/src/Reflection/Php/PhpPropertyReflection.php b/src/Reflection/Php/PhpPropertyReflection.php
@@ -44,6 +44,7 @@ public function __construct(
 		private bool $isReadOnlyByPhpDoc,
 		private bool $isAllowedPrivateMutation,
 		private array $attributes,
+		private bool $isFinal,
 	)
 	{
 	}
@@ -242,11 +243,16 @@ public function isAbstract(): TrinaryLogic
 		return TrinaryLogic::createFromBoolean($this->reflection->isAbstract());
 	}
 
-	public function isFinal(): TrinaryLogic
+	public function isFinalByKeyword(): TrinaryLogic
 	{
 		return TrinaryLogic::createFromBoolean($this->reflection->isFinal());
 	}
 
+	public function isFinal(): TrinaryLogic
+	{
+		return TrinaryLogic::createFromBoolean($this->isFinal);
+	}
+
 	public function isVirtual(): TrinaryLogic
 	{
 		return TrinaryLogic::createFromBoolean($this->reflection->isVirtual());
diff --git a/src/Reflection/Php/SimpleXMLElementProperty.php b/src/Reflection/Php/SimpleXMLElementProperty.php
@@ -127,6 +127,11 @@ public function isAbstract(): TrinaryLogic
 		return TrinaryLogic::createNo();
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return TrinaryLogic::createNo();
diff --git a/src/Reflection/Php/UniversalObjectCrateProperty.php b/src/Reflection/Php/UniversalObjectCrateProperty.php
@@ -117,6 +117,11 @@ public function isAbstract(): TrinaryLogic
 		return TrinaryLogic::createNo();
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return TrinaryLogic::createNo();
diff --git a/src/Reflection/ResolvedPropertyReflection.php b/src/Reflection/ResolvedPropertyReflection.php
@@ -174,6 +174,11 @@ public function isAbstract(): TrinaryLogic
 		return $this->reflection->isAbstract();
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return $this->reflection->isFinalByKeyword();
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return $this->reflection->isFinal();
diff --git a/src/Reflection/Type/IntersectionTypePropertyReflection.php b/src/Reflection/Type/IntersectionTypePropertyReflection.php
@@ -148,6 +148,11 @@ public function isAbstract(): TrinaryLogic
 		return TrinaryLogic::lazyMaxMin($this->properties, static fn (ExtendedPropertyReflection $propertyReflection): TrinaryLogic => $propertyReflection->isAbstract());
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return TrinaryLogic::lazyMaxMin($this->properties, static fn (ExtendedPropertyReflection $propertyReflection): TrinaryLogic => $propertyReflection->isFinalByKeyword());
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return TrinaryLogic::lazyMaxMin($this->properties, static fn (ExtendedPropertyReflection $propertyReflection): TrinaryLogic => $propertyReflection->isFinal());
diff --git a/src/Reflection/Type/UnionTypePropertyReflection.php b/src/Reflection/Type/UnionTypePropertyReflection.php
@@ -148,6 +148,11 @@ public function isAbstract(): TrinaryLogic
 		return TrinaryLogic::lazyExtremeIdentity($this->properties, static fn (ExtendedPropertyReflection $propertyReflection): TrinaryLogic => $propertyReflection->isAbstract());
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return TrinaryLogic::lazyExtremeIdentity($this->properties, static fn (ExtendedPropertyReflection $propertyReflection): TrinaryLogic => $propertyReflection->isFinalByKeyword());
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return TrinaryLogic::lazyExtremeIdentity($this->properties, static fn (ExtendedPropertyReflection $propertyReflection): TrinaryLogic => $propertyReflection->isFinal());
diff --git a/src/Reflection/WrappedExtendedPropertyReflection.php b/src/Reflection/WrappedExtendedPropertyReflection.php
@@ -109,6 +109,11 @@ public function isAbstract(): TrinaryLogic
 		return TrinaryLogic::createNo();
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return TrinaryLogic::createNo();
diff --git a/src/Rules/Properties/FoundPropertyReflection.php b/src/Rules/Properties/FoundPropertyReflection.php
@@ -143,6 +143,11 @@ public function isAbstract(): TrinaryLogic
 		return $this->originalPropertyReflection->isAbstract();
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return $this->originalPropertyReflection->isFinalByKeyword();
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return $this->originalPropertyReflection->isFinal();
diff --git a/src/Rules/Properties/OverridingPropertyRule.php b/src/Rules/Properties/OverridingPropertyRule.php
@@ -135,7 +135,7 @@ public function processNode(Node $node, Scope $scope): array
 			))->identifier('property.visibility')->nonIgnorable()->build();
 		}
 
-		if ($prototype->isFinal()->yes()) {
+		if ($prototype->isFinalByKeyword()->yes()) {
 			$errors[] = RuleErrorBuilder::message(sprintf(
 				'Property %s::$%s overrides final property %s::$%s.',
 				$classReflection->getDisplayName(),
@@ -145,6 +145,15 @@ public function processNode(Node $node, Scope $scope): array
 			))->identifier('property.parentPropertyFinal')
 				->nonIgnorable()
 				->build();
+		} elseif ($prototype->isFinal()->yes()) {
+			$errors[] = RuleErrorBuilder::message(sprintf(
+				'Property %s::$%s overrides @final property %s::$%s.',
+				$classReflection->getDisplayName(),
+				$node->getName(),
+				$prototype->getDeclaringClass()->getDisplayName(),
+				$node->getName(),
+			))->identifier('property.parentPropertyFinalByPhpDoc')
+				->build();
 		}
 
 		$typeErrors = [];
diff --git a/src/Rules/RestrictedUsage/RewrittenDeclaringClassPropertyReflection.php b/src/Rules/RestrictedUsage/RewrittenDeclaringClassPropertyReflection.php
@@ -73,6 +73,11 @@ public function isAbstract(): TrinaryLogic
 		return $this->propertyReflection->isAbstract();
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return $this->propertyReflection->isFinalByKeyword();
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return $this->propertyReflection->isFinal();
diff --git a/src/Type/ObjectShapePropertyReflection.php b/src/Type/ObjectShapePropertyReflection.php
@@ -114,6 +114,11 @@ public function isAbstract(): TrinaryLogic
 		return TrinaryLogic::createNo();
 	}
 
+	public function isFinalByKeyword(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
 	public function isFinal(): TrinaryLogic
 	{
 		return TrinaryLogic::createNo();
diff --git a/tests/PHPStan/Rules/Properties/OverridingPropertyRuleTest.php b/tests/PHPStan/Rules/Properties/OverridingPropertyRuleTest.php
@@ -187,19 +187,27 @@ public function testFinal(): void
 		$this->analyse([__DIR__ . '/data/overriding-final-property.php'], [
 			[
 				'Property OverridingFinalProperty\Bar::$a overrides final property OverridingFinalProperty\Foo::$a.',
-				21,
+				27,
 			],
 			[
 				'Property OverridingFinalProperty\Bar::$b overrides final property OverridingFinalProperty\Foo::$b.',
-				23,
+				29,
 			],
 			[
 				'Property OverridingFinalProperty\Bar::$c overrides final property OverridingFinalProperty\Foo::$c.',
-				25,
+				31,
 			],
 			[
 				'Property OverridingFinalProperty\Bar::$d overrides final property OverridingFinalProperty\Foo::$d.',
-				27,
+				33,
+			],
+			[
+				'Property OverridingFinalProperty\Bar::$e overrides @final property OverridingFinalProperty\Foo::$e.',
+				35,
+			],
+			[
+				'Property OverridingFinalProperty\Bar::$f overrides @final property OverridingFinalProperty\Foo::$f.',
+				37,
 			],
 		]);
 	}
diff --git a/tests/PHPStan/Rules/Properties/data/overriding-final-property.php b/tests/PHPStan/Rules/Properties/data/overriding-final-property.php
@@ -13,6 +13,12 @@ class Foo
 
 	protected private(set) int $d;
 
+	/** @final */
+	public $e;
+
+	/** @final */
+	protected $f;
+
 }
 
 class Bar extends Foo
@@ -26,4 +32,8 @@ class Bar extends Foo
 
 	public int $d;
 
+	public $e;
+
+	protected $f;
+
 }
diff --git a/tests/PHPStan/Rules/Variables/UnsetRuleTest.php b/tests/PHPStan/Rules/Variables/UnsetRuleTest.php
@@ -167,55 +167,55 @@ public function testUnsetHookedProperty(): void
 			],
 			[
 				'Cannot unset property UnsetHookedProperty\NonFinalClass::$publicProperty because it might have hooks in a subclass.',
-				13,
+				14,
 			],
 			[
 				'Cannot unset property UnsetHookedProperty\ContainerClass::$finalClass because it might have hooks in a subclass.',
-				83,
+				86,
 			],
 			[
 				'Cannot unset property UnsetHookedProperty\ContainerClass::$nonFinalClass because it might have hooks in a subclass.',
-				87,
+				91,
 			],
 			[
 				'Cannot unset hooked UnsetHookedProperty\Foo::$iii property.',
-				89,
+				93,
 			],
 			[
 				'Cannot unset property UnsetHookedProperty\ContainerClass::$foo because it might have hooks in a subclass.',
-				90,
+				94,
 			],
 			[
 				'Cannot unset hooked UnsetHookedProperty\User::$name property.',
-				92,
+				96,
 			],
 			[
 				'Cannot unset hooked UnsetHookedProperty\User::$fullName property.',
-				93,
+				97,
 			],
 			[
 				'Cannot unset property UnsetHookedProperty\ContainerClass::$user because it might have hooks in a subclass.',
-				94,
+				98,
 			],
 			[
 				'Cannot unset hooked UnsetHookedProperty\User::$name property.',
-				96,
+				100,
 			],
 			[
 				'Cannot unset hooked UnsetHookedProperty\User::$name property.',
-				97,
+				101,
 			],
 			[
 				'Cannot unset hooked UnsetHookedProperty\User::$fullName property.',
-				98,
+				102,
 			],
 			[
 				'Cannot unset hooked UnsetHookedProperty\User::$fullName property.',
-				99,
+				103,
 			],
 			[
 				'Cannot unset property UnsetHookedProperty\ContainerClass::$arrayOfUsers because it might have hooks in a subclass.',
-				100,
+				104,
 			],
 		]);
 	}
diff --git a/tests/PHPStan/Rules/Variables/data/unset-hooked-property.php b/tests/PHPStan/Rules/Variables/data/unset-hooked-property.php
@@ -9,6 +9,7 @@ function doUnset(Foo $foo, User $user, NonFinalClass $nonFinalClass, FinalClass
 	unset($foo->ii);
 	unset($foo->iii);
 
+	unset($nonFinalClass->publicAnnotatedFinalProperty);
 	unset($nonFinalClass->publicFinalProperty);
 	unset($nonFinalClass->publicProperty);
 
@@ -49,6 +50,8 @@ class NonFinalClass {
 	private string $privateProperty;
 	public string $publicProperty;
 	final public string $publicFinalProperty;
+	/** @final */
+	public string $publicAnnotatedFinalProperty;
 
 	function doFoo() {
 		unset($this->privateProperty);
@@ -82,6 +85,7 @@ function dooNestedUnset(ContainerClass $containerClass) {
 	unset($containerClass->finalClass->publicProperty);
 	unset($containerClass->finalClass);
 
+	unset($containerClass->nonFinalClass->publicAnnotatedFinalProperty);
 	unset($containerClass->nonFinalClass->publicFinalProperty);
 	unset($containerClass->nonFinalClass->publicProperty);
 	unset($containerClass->nonFinalClass);

Original file line number	Diff line number	Diff line change
`@@ -119,6 +119,11 @@ public function isAbstract(): TrinaryLogic`
`119`	`119`	`return TrinaryLogic::createNo();`
`120`	`120`	`}`
`121`	`121`
	`122`	`+ public function isFinalByKeyword(): TrinaryLogic`
	`123`	`+ {`
	`124`	`+ return TrinaryLogic::createNo();`
	`125`	`+ }`
	`126`	`+`
`122`	`127`	`public function isFinal(): TrinaryLogic`
`123`	`128`	`{`
`124`	`129`	`return TrinaryLogic::createNo();`
Original file line number	Diff line number	Diff line change
`@@ -116,6 +116,11 @@ public function isAbstract(): TrinaryLogic`
`116`	`116`	`return $this->reflection->isAbstract();`
`117`	`117`	`}`
`118`	`118`
	`119`	`+ public function isFinalByKeyword(): TrinaryLogic`
	`120`	`+ {`
	`121`	`+ return $this->reflection->isFinalByKeyword();`
	`122`	`+ }`
	`123`	`+`
`119`	`124`	`public function isFinal(): TrinaryLogic`
`120`	`125`	`{`
`121`	`126`	`return $this->reflection->isFinal();`
Original file line number	Diff line number	Diff line change
`@@ -112,6 +112,11 @@ public function isAbstract(): TrinaryLogic`
`112`	`112`	`return TrinaryLogic::createNo();`
`113`	`113`	`}`
`114`	`114`
	`115`	`+ public function isFinalByKeyword(): TrinaryLogic`
	`116`	`+ {`
	`117`	`+ return TrinaryLogic::createNo();`
	`118`	`+ }`
	`119`	`+`
`115`	`120`	`public function isFinal(): TrinaryLogic`
`116`	`121`	`{`
`117`	`122`	`return TrinaryLogic::createNo();`
Original file line number	Diff line number	Diff line change
`@@ -218,7 +218,7 @@ private function createProperty(`
`218`	`218`	`$types[] = $value;`
`219`	`219`	`}`
`220`	`220`
`221`		`- return new PhpPropertyReflection($declaringClassReflection, null, null, TypeCombinator::union(...$types), $classReflection->getNativeReflection()->getProperty($propertyName), null, null, null, false, false, false, false, []);`
	`221`	`+ return new PhpPropertyReflection($declaringClassReflection, null, null, TypeCombinator::union(...$types), $classReflection->getNativeReflection()->getProperty($propertyName), null, null, null, false, false, false, false, [], false);`
`222`	`222`	`}`
`223`	`223`	`}`
`224`	`224`
`@@ -227,6 +227,7 @@ private function createProperty(`
`227`	`227`	`$isDeprecated = $deprecation !== null;`
`228`	`228`	`$isInternal = false;`
`229`	`229`	`$isReadOnlyByPhpDoc = $classReflection->isImmutable();`
	`230`	`+ $isFinal = $classReflection->isFinal() \|\| $propertyReflection->isFinal();`
`230`	`231`	`$isAllowedPrivateMutation = false;`
`231`	`232`
`232`	`233`	`if (`
`@@ -308,6 +309,7 @@ private function createProperty(`
`308`	`309`	`}`
`309`	`310`	`$isInternal = $resolvedPhpDoc->isInternal();`
`310`	`311`	`$isReadOnlyByPhpDoc = $isReadOnlyByPhpDoc \|\| $resolvedPhpDoc->isReadOnly();`
	`312`	`+ $isFinal = $isFinal \|\| $resolvedPhpDoc->isFinal();`
`311`	`313`	`$isAllowedPrivateMutation = $resolvedPhpDoc->isAllowedPrivateMutation();`
`312`	`314`	`}`
`313`	`315`
`@@ -435,6 +437,7 @@ private function createProperty(`
`435`	`437`	`$isReadOnlyByPhpDoc,`
`436`	`438`	`$isAllowedPrivateMutation,`
`437`	`439`	`$this->attributeReflectionFactory->fromNativeReflection($propertyReflection->getAttributes(), InitializerExprContext::fromClass($declaringClassReflection->getName(), $declaringClassReflection->getFileName())),`
	`440`	`+ $isFinal,`
`438`	`441`	`);`
`439`	`442`	`}`
`440`	`443`
Original file line number	Diff line number	Diff line change
`@@ -44,6 +44,7 @@ public function __construct(`
`44`	`44`	`private bool $isReadOnlyByPhpDoc,`
`45`	`45`	`private bool $isAllowedPrivateMutation,`
`46`	`46`	`private array $attributes,`
	`47`	`+ private bool $isFinal,`
`47`	`48`	`)`
`48`	`49`	`{`
`49`	`50`	`}`
`@@ -242,11 +243,16 @@ public function isAbstract(): TrinaryLogic`
`242`	`243`	`return TrinaryLogic::createFromBoolean($this->reflection->isAbstract());`
`243`	`244`	`}`
`244`	`245`
`245`		`- public function isFinal(): TrinaryLogic`
	`246`	`+ public function isFinalByKeyword(): TrinaryLogic`
`246`	`247`	`{`
`247`	`248`	`return TrinaryLogic::createFromBoolean($this->reflection->isFinal());`
`248`	`249`	`}`
`249`	`250`
	`251`	`+ public function isFinal(): TrinaryLogic`
	`252`	`+ {`
	`253`	`+ return TrinaryLogic::createFromBoolean($this->isFinal);`
	`254`	`+ }`
	`255`	`+`
`250`	`256`	`public function isVirtual(): TrinaryLogic`
`251`	`257`	`{`
`252`	`258`	`return TrinaryLogic::createFromBoolean($this->reflection->isVirtual());`
Original file line number	Diff line number	Diff line change
`@@ -127,6 +127,11 @@ public function isAbstract(): TrinaryLogic`
`127`	`127`	`return TrinaryLogic::createNo();`
`128`	`128`	`}`
`129`	`129`
	`130`	`+ public function isFinalByKeyword(): TrinaryLogic`
	`131`	`+ {`
	`132`	`+ return TrinaryLogic::createNo();`
	`133`	`+ }`
	`134`	`+`
`130`	`135`	`public function isFinal(): TrinaryLogic`
`131`	`136`	`{`
`132`	`137`	`return TrinaryLogic::createNo();`
Original file line number	Diff line number	Diff line change
`@@ -117,6 +117,11 @@ public function isAbstract(): TrinaryLogic`
`117`	`117`	`return TrinaryLogic::createNo();`
`118`	`118`	`}`
`119`	`119`
	`120`	`+ public function isFinalByKeyword(): TrinaryLogic`
	`121`	`+ {`
	`122`	`+ return TrinaryLogic::createNo();`
	`123`	`+ }`
	`124`	`+`
`120`	`125`	`public function isFinal(): TrinaryLogic`
`121`	`126`	`{`
`122`	`127`	`return TrinaryLogic::createNo();`
Original file line number	Diff line number	Diff line change
`@@ -174,6 +174,11 @@ public function isAbstract(): TrinaryLogic`
`174`	`174`	`return $this->reflection->isAbstract();`
`175`	`175`	`}`
`176`	`176`
	`177`	`+ public function isFinalByKeyword(): TrinaryLogic`
	`178`	`+ {`
	`179`	`+ return $this->reflection->isFinalByKeyword();`
	`180`	`+ }`
	`181`	`+`
`177`	`182`	`public function isFinal(): TrinaryLogic`
`178`	`183`	`{`
`179`	`184`	`return $this->reflection->isFinal();`