added Html::getXxx(), setXxx(), addXxx() magic method resolution

Author: dg

CLAUDE.md

@@ -69,6 +69,10 @@ Extensions for specific Nette packages use dedicated namespaces: `Nette\PHPStan\
 
 `ArraysInvokeTypeExtension` (`DynamicStaticMethodReturnTypeExtension`) narrows return types of `Arrays::invoke()` and `Arrays::invokeMethod()` from `array`. For `invoke()`, it extracts the callable return type from the iterable value type and forwards `...$args` via `ParametersAcceptorSelector::selectFromArgs()` to resolve the correct overload. For `invokeMethod()`, it resolves constant method names on the object type, gets method reflection, and forwards remaining args. Handles `callable(): void` by converting void to null. Falls back to declared return type when callbacks are not callable, method names are not constant strings, or methods don't exist on the object type. Config: `extension-nette.neon`.
 
+### HtmlMethodsClassReflectionExtension
+
+`HtmlMethodsClassReflectionExtension` (`MethodsClassReflectionExtension`) resolves `getXxx()`, `setXxx()`, and `addXxx()` magic methods on `Nette\Utils\Html` that go through `__call()` but aren't declared via `@method` annotations. `getXxx()` returns `mixed`, `setXxx()` and `addXxx()` return `static`. Config: `extension-nette.neon`.
+
 ### GetComponentReturnTypeExtension
 
 `GetComponentReturnTypeExtension` (`DynamicMethodReturnTypeExtension`) narrows return types of `Container::getComponent()` and `Container::offsetGet()` (i.e. `$this['xxx']`). When the component name is a constant string, it looks for a `createComponent<Name>()` factory method on the caller type and returns its return type — e.g. `$this->getComponent('poll')` returns `PollControl` if `createComponentPoll(): PollControl` exists. Falls back to the declared return type when no factory method is found. Config: `extension-nette.neon`.

extension-nette.neon

@@ -49,3 +49,6 @@ services:
 	-
 		class: Nette\PHPStan\Utils\ArraysInvokeTypeExtension
 		tags: [phpstan.broker.dynamicStaticMethodReturnTypeExtension]
+	-
+		class: Nette\PHPStan\Utils\HtmlMethodsClassReflectionExtension
+		tags: [phpstan.broker.methodsClassReflectionExtension]

readme.md

@@ -43,6 +43,8 @@ includes:
 
 **Precise return types** — narrows return types of `Strings::match()`, `matchAll()`, `split()`, `Helpers::falseToNull()`, `Expect::array()`, `Arrays::invoke()`, and `Arrays::invokeMethod()` based on the arguments you pass. Also narrows `Container::getComponent()` and `$container['...']` to match the corresponding `createComponent*()` factory return type. For forms, `$form['name']` returns the specific control type (e.g. `TextInput`, `SelectBox`) based on the `addText()`, `addSelect()`, etc. call in the same function.
 
+**Html magic methods** — resolves `$html->getXxx()`, `setXxx()`, and `addXxx()` calls on `Nette\Utils\Html` that go through `__call()` but aren't declared via `@method` annotations.
+
 **Removes `|false` and `|null` from PHP functions** — many native functions like `getcwd`, `json_encode`, `preg_split`, `preg_replace`, and [many more](extension-php.neon) include `false` or `null` in their return type even though these error values are unrealistic on modern systems.
 
 **Assert type narrowing** — PHPStan understands type guarantees after `Tester\Assert` calls like `notNull()`, `type()`, `true()`, etc.

src/Utils/HtmlMethodsClassReflectionExtension.php

@@ -0,0 +1,160 @@
+<?php declare(strict_types=1);
+
+namespace Nette\PHPStan\Utils;
+
+use PHPStan\Reflection\ClassMemberReflection;
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\FunctionVariant;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\MethodsClassReflectionExtension;
+use PHPStan\TrinaryLogic;
+use PHPStan\Type\Generic\TemplateTypeMap;
+use PHPStan\Type\MixedType;
+use PHPStan\Type\StaticType;
+use PHPStan\Type\Type;
+use function in_array, strlen, substr;
+
+
+/**
+ * Resolves getXxx(), setXxx(), addXxx() magic methods on Nette\Utils\Html
+ * that are handled by __call() but not declared via @method annotations.
+ */
+final class HtmlMethodsClassReflectionExtension implements MethodsClassReflectionExtension
+{
+	public function hasMethod(ClassReflection $classReflection, string $methodName): bool
+	{
+		if (!$classReflection->is('Nette\Utils\Html')) {
+			return false;
+		}
+
+		return strlen($methodName) > 3
+			&& in_array(substr($methodName, 0, 3), ['get', 'set', 'add'], true);
+	}
+
+
+	public function getMethod(ClassReflection $classReflection, string $methodName): MethodReflection
+	{
+		$prefix = substr($methodName, 0, 3);
+		return new HtmlCallMethodReflection($classReflection, $methodName, $prefix);
+	}
+}
+
+
+/**
+ * @internal
+ */
+final class HtmlCallMethodReflection implements MethodReflection
+{
+	public function __construct(
+		private ClassReflection $declaringClass,
+		private string $name,
+		private string $prefix,
+	) {
+	}
+
+
+	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
+	{
+		if ($this->prefix === 'get') {
+			return [
+				new FunctionVariant(
+					TemplateTypeMap::createEmpty(),
+					TemplateTypeMap::createEmpty(),
+					[],
+					false,
+					new MixedType,
+				),
+			];
+		}
+
+		return [
+			new FunctionVariant(
+				TemplateTypeMap::createEmpty(),
+				TemplateTypeMap::createEmpty(),
+				[],
+				true,
+				new StaticType($this->declaringClass),
+			),
+		];
+	}
+
+
+	public function isDeprecated(): TrinaryLogic
+	{
+		return TrinaryLogic::createNo();
+	}
+
+
+	public function getDeprecatedDescription(): ?string
+	{
+		return null;
+	}
+
+
+	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 $this->prefix === 'get'
+			? TrinaryLogic::createNo()
+			: TrinaryLogic::createYes();
+	}
+}

tests/Utils/html-virtual-members.php

@@ -0,0 +1,34 @@
+<?php declare(strict_types=1);
+
+use Nette\Utils\Html;
+use function PHPStan\Testing\assertType;
+
+$html = Html::el('div');
+
+// @property — string, bool, int, float
+assertType('string|null', $html->class);
+assertType('bool|null', $html->checked);
+assertType('int|null', $html->cols);
+assertType('float|null', $html->high);
+assertType('string|null', $html->id);
+
+// universalObjectCratesClasses — undeclared property
+assertType('mixed', $html->nonExistent);
+
+// @method — fluent setters
+assertType('Nette\Utils\Html', $html->class('foo'));
+assertType('Nette\Utils\Html', $html->checked(true));
+assertType('Nette\Utils\Html', $html->cols(80));
+assertType('Nette\Utils\Html', $html->high(1.0));
+
+// @method — with second argument (appendAttribute)
+assertType('Nette\Utils\Html', $html->class('foo', true));
+
+// __call — getXxx(), setXxx(), addXxx()
+assertType('mixed', $html->getClass());
+assertType('Nette\Utils\Html', $html->setClass('foo'));
+assertType('Nette\Utils\Html', $html->addClass('bar'));
+
+// real methods — return static
+assertType('Nette\Utils\Html', $html->href('/path'));
+assertType('Nette\Utils\Html', $html->data('key', 'value'));

tests/extensions.phpt

@@ -27,3 +27,4 @@ TypeAssert::assertTypes(__DIR__ . '/Forms/form-component-return-type.php');
 TypeAssert::assertTypes(__DIR__ . '/Utils/false-to-null-return-type.php');
 TypeAssert::assertTypes(__DIR__ . '/Utils/strings-return-type.php');
 TypeAssert::assertTypes(__DIR__ . '/Utils/arrays-invoke-return-type.php');
+TypeAssert::assertTypes(__DIR__ . '/Utils/html-virtual-members.php');