Add TwigComponent\ForbiddenAttributesPropertyRule

Author: Kocal

README.md

@@ -10,6 +10,72 @@ To install the PHPStan rules for Symfony UX, you can use Composer:
 composer require --dev kocal/phpstan-symfony-ux
 ```
 
-## Configuration
+## TwigComponent Rules
 
-TODO
+### ForbiddenAttributesPropertyRule
+
+Forbid the use of the `$attributes` property in Twig Components, which can lead to confusion when using `{{ attributes }}` (an instance of `ComponentAttributes` that is automatically injected) in Twig templates.
+
+```yaml
+rules:
+    - Kocal\PHPStanSymfonyUX\Rules\TwigComponent\ForbiddenAttributesPropertyRule
+```
+
+```php
+// src/Twig/Components/Alert.php
+namespace App\Twig\Components;
+
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+
+#[AsTwigComponent]
+final class Alert
+{
+    public $attributes;
+}
+```
+
+```php
+// src/Twig/Components/Alert.php
+namespace App\Twig\Components;
+
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+
+#[AsTwigComponent(attributesVar: 'customAttributes')]
+final class Alert
+{
+    public $customAttributes;
+}
+```
+
+:x:
+
+<br>
+
+```php
+// src/Twig/Components/Alert.php
+namespace App\Twig\Components;
+
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+
+#[AsTwigComponent]
+final class Alert
+{
+}
+```
+
+```php
+// src/Twig/Components/Alert.php
+namespace App\Twig\Components;
+
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+
+#[AsTwigComponent]
+final class Alert
+{
+    public $customAttributes;
+}
+```
+
+:+1:
+
+<br>

src/NodeAnalyzer/AttributeFinder.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kocal\PHPStanSymfonyUX\NodeAnalyzer;
+
+use PhpParser\Node\Attribute;
+use PhpParser\Node\Name\FullyQualified;
+use PhpParser\Node\Param;
+use PhpParser\Node\Stmt\ClassLike;
+use PhpParser\Node\Stmt\Property;
+use PHPStan\Node\ClassMethod;
+
+/**
+ * Heavily inspired by https://github.com/symplify/phpstan-rules/blob/main/src/NodeAnalyzer/AttributeFinder.php <3
+ */
+final class AttributeFinder
+{
+    /**
+     * @return Attribute[]
+     */
+    public static function findAttributes(ClassMethod | Property | ClassLike | Param $node): array
+    {
+        $attributes = [];
+
+        foreach ($node->attrGroups as $attrGroup) {
+            $attributes = array_merge($attributes, $attrGroup->attrs);
+        }
+
+        return $attributes;
+    }
+
+    public static function findAttribute(ClassMethod | Property | ClassLike | Param $node, string $desiredAttributeClass): ?Attribute
+    {
+        $attributes = self::findAttributes($node);
+
+        foreach ($attributes as $attribute) {
+            if (! $attribute->name instanceof FullyQualified) {
+                continue;
+            }
+
+            if ($attribute->name->toString() === $desiredAttributeClass) {
+                return $attribute;
+            }
+        }
+
+        return null;
+    }
+}

src/Rules/TwigComponent/ForbiddenAttributesPropertyRule.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kocal\PHPStanSymfonyUX\Rules\TwigComponent;
+
+use Kocal\PHPStanSymfonyUX\NodeAnalyzer\AttributeFinder;
+use PhpParser\Node;
+use PhpParser\Node\Stmt\Class_;
+use PHPStan\Analyser\Scope;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+
+/**
+ * @implements Rule<Class_>
+ */
+final class ForbiddenAttributesPropertyRule implements Rule
+{
+    public function getNodeType(): string
+    {
+        return Class_::class;
+    }
+
+    public function processNode(Node $node, Scope $scope): array
+    {
+        if (! $asTwigComponent = AttributeFinder::findAttribute($node, AsTwigComponent::class)) {
+            return [];
+        }
+
+        if (! $attributesVarName = $this->getAttributesVarName($asTwigComponent)) {
+            return [];
+        }
+
+        if ($propertyAttributes = $node->getProperty($attributesVarName['name'])) {
+            return [
+                RuleErrorBuilder::message(
+                    $attributesVarName['custom']
+                        ? sprintf('Using property "%s" in a Twig component is forbidden, it may lead to confusion with the "%s" attribute defined in #[AsTwigComponent].', $attributesVarName['name'], $attributesVarName['name'])
+                        : sprintf('Using property "%s" in a Twig component is forbidden, it may lead to confusion with the default "attributes" Twig variable.', $attributesVarName['name'])
+                )
+                    ->identifier('SymfonyUX.TwigComponent.forbiddenAttributesProperty')
+                    ->line($propertyAttributes->getLine())
+                    ->tip('Consider renaming or removing this property to avoid conflicts with the Twig component attributes.')
+                    ->build(),
+
+            ];
+        }
+
+        return [];
+    }
+
+    /**
+     * @return {name: string, custom: false}|null
+     */
+    private function getAttributesVarName(Node\Attribute $attribute): ?array
+    {
+        foreach ($attribute->args as $arg) {
+            if ($arg->name && $arg->name->toString() === 'attributesVar') {
+                if ($arg->value instanceof Node\Scalar\String_) {
+                    return [
+                        'name' => $arg->value->value,
+                        'custom' => true,
+                    ];
+                }
+            }
+        }
+
+        $reflAttribute = new \ReflectionClass(AsTwigComponent::class);
+        foreach ($reflAttribute->getConstructor()->getParameters() as $reflParameter) {
+            if ($reflParameter->getName() === 'attributesVar' && $reflParameter->isDefaultValueAvailable()) {
+                return [
+                    'name' => $reflParameter->getDefaultValue(),
+                    'custom' => false,
+                ];
+            }
+        }
+
+        return null;
+    }
+}

tests/Rules/TwigComponent/ForbiddenAttributesPropertyRule/Fixture/ComponentWithAttributesProperty.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kocal\PHPStanSymfonyUX\Tests\Rules\TwigComponent\ForbiddenAttributesPropertyRule\Fixture;
+
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+
+#[AsTwigComponent]
+final class ComponentWithAttributesProperty
+{
+    public $attributes;
+}

tests/Rules/TwigComponent/ForbiddenAttributesPropertyRule/Fixture/ComponentWithCustomAttributesProperty.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kocal\PHPStanSymfonyUX\Tests\Rules\TwigComponent\ForbiddenAttributesPropertyRule\Fixture;
+
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+
+#[AsTwigComponent(attributesVar: 'customAttributes')]
+final class ComponentWithAttributesProperty
+{
+    public $customAttributes;
+}

tests/Rules/TwigComponent/ForbiddenAttributesPropertyRule/Fixture/ComponentWithNoAttributesProperty.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kocal\PHPStanSymfonyUX\Tests\Rules\TwigComponent\ForbiddenAttributesPropertyRule\Fixture;
+
+use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;
+
+#[AsTwigComponent]
+final class ComponentWithNoAttributesProperty
+{
+}

tests/Rules/TwigComponent/ForbiddenAttributesPropertyRule/Fixture/NotAComponent.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kocal\PHPStanSymfonyUX\Tests\Rules\TwigComponent\ForbiddenAttributesPropertyRule\Fixture;
+
+final class NotAComponent
+{
+    public $attributes;
+}

tests/Rules/TwigComponent/ForbiddenAttributesPropertyRule/ForbiddenAttributesPropertyRuleTest.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kocal\PHPStanSymfonyUX\Tests\Rules\TwigComponent\ForbiddenAttributesPropertyRule;
+
+use Kocal\PHPStanSymfonyUX\Rules\TwigComponent\ForbiddenAttributesPropertyRule;
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+
+final class ForbiddenAttributesPropertyRuleTest extends RuleTestCase
+{
+    public function testViolations(): void
+    {
+        $this->analyse(
+            [__DIR__ . '/Fixture/ComponentWithAttributesProperty.php'],
+            [
+                [
+                    'Using property "attributes" in a Twig component is forbidden, it may lead to confusion with the default "attributes" Twig variable.',
+                    12,
+                    'Consider renaming or removing this property to avoid conflicts with the Twig component attributes.',
+                ],
+            ]
+        );
+
+        $this->analyse(
+            [__DIR__ . '/Fixture/ComponentWithCustomAttributesProperty.php'],
+            [
+                [
+                    'Using property "customAttributes" in a Twig component is forbidden, it may lead to confusion with the "customAttributes" attribute defined in #[AsTwigComponent].',
+                    12,
+                    'Consider renaming or removing this property to avoid conflicts with the Twig component attributes.',
+                ],
+            ]
+        );
+    }
+
+    public function testNoViolations(): void
+    {
+        $this->analyse(
+            [__DIR__ . '/Fixture/NotAComponent.php'],
+            []
+        );
+        $this->analyse(
+            [__DIR__ . '/Fixture/ComponentWithNoAttributesProperty.php'],
+            []
+        );
+    }
+
+    protected function getRule(): Rule
+    {
+        return new ForbiddenAttributesPropertyRule();
+    }
+}