[symfony] Add NoClassLevelRouteRule (#173)

Author: TomasVotruba

README.md

@@ -1325,6 +1325,48 @@ return static function (RoutingConfigurator $routingConfigurator): void {
 
 <br>
 
+### NoClassLevelRouteRule
+
+Avoid class-level route prefixing. Use method route to keep single source of truth and focus
+
+```yaml
+rules:
+    - Symplify\PHPStanRules\Rules\Symfony\NoClassLevelRouteRule
+```
+
+```php
+use Symfony\Component\Routing\Attribute\Route;
+
+#[Route('/some-prefix')]
+class SomeController
+{
+    #[Route('/some-action')]
+    public function someAction()
+    {
+    }
+}
+```
+
+:x:
+
+<br>
+
+```php
+use Symfony\Component\Routing\Attribute\Route;
+
+class SomeController
+{
+    #[Route('/some-prefix/some-action')]
+    public function someAction()
+    {
+    }
+}
+```
+
+:+1:
+
+<br>
+
 ### NoRequiredOutsideClassRule
 
 Symfony #[Require]/@required should be used only in classes to avoid misuse

config/symfony-rules.neon

@@ -9,6 +9,7 @@ rules:
 
     # routing
     - Symplify\PHPStanRules\Rules\Symfony\NoRoutingPrefixRule
+    - Symplify\PHPStanRules\Rules\Symfony\NoClassLevelRouteRule
 
     # dependency injection
     - Symplify\PHPStanRules\Rules\Symfony\NoGetDoctrineInControllerRule

src/Enum/ClassName.php

@@ -9,7 +9,13 @@ final class ClassName
     /**
      * @var string
      */
-    public const ROUTE_ATTRIBUTE = 'Symfony\Component\Routing\Annotation\Route';
+    public const ROUTE_ATTRIBUTE = 'Symfony\Component\Routing\Attribute\Route';
+
+    /**
+     * @api
+     * @var string
+     */
+    public const ROUTE_ANNOTATION = 'Symfony\Component\Routing\Annotation\Route';
 
     /**
      * @var string

src/Enum/SymfonyRuleIdentifier.php

@@ -31,4 +31,6 @@ final class SymfonyRuleIdentifier
     public const FORM_TYPE_CLASS_NAME = 'symfony.formTypeClassName';
 
     public const NO_ROUTING_PREFIX = 'symfony.noRoutingPrefix';
+
+    public const NO_CLASS_LEVEL_ROUTE = 'symfony.noClassLevelRoute';
 }

src/Rules/Symfony/NoClassLevelRouteRule.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symplify\PHPStanRules\Rules\Symfony;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Node\InClassNode;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleError;
+use PHPStan\Rules\RuleErrorBuilder;
+use Symplify\PHPStanRules\Enum\SymfonyRuleIdentifier;
+use Symplify\PHPStanRules\Symfony\NodeAnalyzer\SymfonyControllerAnalyzer;
+
+/**
+ * @implements Rule<InClassNode>
+ *
+ * @see \Symplify\PHPStanRules\Tests\Rules\Symfony\NoClassLevelRouteRule\NoClassLevelRouteRuleTest
+ */
+final class NoClassLevelRouteRule implements Rule
+{
+    /**
+     * @var string
+     */
+    public const ERROR_MESSAGE = 'Avoid class-level route prefixing. Use method route to keep single source of truth and focus';
+
+    public function getNodeType(): string
+    {
+        return InClassNode::class;
+    }
+
+    /**
+     * @param InClassNode $node
+     * @return RuleError[]
+     */
+    public function processNode(Node $node, Scope $scope): array
+    {
+        if (! SymfonyControllerAnalyzer::isControllerScope($scope)) {
+            return [];
+        }
+
+        $classLike = $node->getOriginalNode();
+        if (! SymfonyControllerAnalyzer::hasRouteAnnotationOrAttribute($classLike)) {
+            return [];
+        }
+
+        $ruleError = RuleErrorBuilder::message(self::ERROR_MESSAGE)
+            ->line($node->getStartLine())
+            ->identifier(SymfonyRuleIdentifier::NO_CLASS_LEVEL_ROUTE)
+            ->build();
+
+        return [$ruleError];
+    }
+}

src/Symfony/NodeAnalyzer/SymfonyControllerAnalyzer.php

@@ -5,6 +5,7 @@
 namespace Symplify\PHPStanRules\Symfony\NodeAnalyzer;
 
 use PhpParser\Comment\Doc;
+use PhpParser\Node\Stmt\ClassLike;
 use PhpParser\Node\Stmt\ClassMethod;
 use PHPStan\Analyser\Scope;
 use Symplify\PHPStanRules\Enum\ClassName;
@@ -38,17 +39,22 @@ public static function isControllerScope(Scope $scope): bool
 
     public static function isControllerActionMethod(ClassMethod $classMethod): bool
     {
-        $attributeFinder = new AttributeFinder();
+        return self::hasRouteAnnotationOrAttribute($classMethod);
+    }
 
-        if (! $classMethod->isPublic()) {
+    public static function hasRouteAnnotationOrAttribute(ClassLike | ClassMethod $node): bool
+    {
+        if ($node instanceof ClassMethod && ! $node->isPublic()) {
             return false;
         }
 
-        if ($attributeFinder->hasAttribute($classMethod, ClassName::ROUTE_ATTRIBUTE)) {
+        $attributeFinder = new AttributeFinder();
+
+        if ($attributeFinder->hasAttribute($node, ClassName::ROUTE_ATTRIBUTE)) {
             return true;
         }
 
-        $docComment = $classMethod->getDocComment();
+        $docComment = $node->getDocComment();
         if (! $docComment instanceof Doc) {
             return false;
         }

tests/Rules/Symfony/NoClassLevelRouteRule/Fixture/ControllerWithClassAttributeRoute.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Symplify\PHPStanRules\Tests\Rules\Symfony\NoClassLevelRouteRule\Fixture;
+
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\Routing\Attribute\Route;
+
+#[Route('/global-path')]
+class ControllerWithClassAttributeRoute extends AbstractController
+{
+
+}

tests/Rules/Symfony/NoClassLevelRouteRule/Fixture/ControllerWithClassRoute.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Symplify\PHPStanRules\Tests\Rules\Symfony\NoClassLevelRouteRule\Fixture;
+
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\Routing\Annotation\Route;
+
+/**
+ * @Route("/global-path")
+ */
+class ControllerWithClassRoute extends AbstractController
+{
+}

tests/Rules/Symfony/NoClassLevelRouteRule/Fixture/SkipControllerWithMethodRoute.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Symplify\PHPStanRules\Tests\Rules\Symfony\NoClassLevelRouteRule\Fixture;
+
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\Routing\Attribute\Route;
+
+class SkipControllerWithMethodRoute extends AbstractController
+{
+    #[Route('/global-path')]
+    public function someMethod()
+    {
+
+    }
+}

tests/Rules/Symfony/NoClassLevelRouteRule/NoClassLevelRouteRuleTest.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Symplify\PHPStanRules\Tests\Rules\Symfony\NoClassLevelRouteRule;
+
+use Iterator;
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Symplify\PHPStanRules\Rules\Symfony\NoClassLevelRouteRule;
+
+final class NoClassLevelRouteRuleTest extends RuleTestCase
+{
+    /**
+     * @param string[] $filePaths
+     */
+    #[DataProvider('provideData')]
+    public function testRule(array $filePaths, array $expectedErrorsWithLines): void
+    {
+        $this->analyse($filePaths, $expectedErrorsWithLines);
+    }
+
+    public static function provideData(): Iterator
+    {
+        yield [[
+            __DIR__ . '/Fixture/SkipControllerWithMethodRoute.php',
+        ], []];
+
+        yield [[
+            __DIR__ . '/Fixture/ControllerWithClassAttributeRoute.php',
+        ], [[NoClassLevelRouteRule::ERROR_MESSAGE, 8]]];
+
+        yield [[
+            __DIR__ . '/Fixture/ControllerWithClassRoute.php',
+        ], [[NoClassLevelRouteRule::ERROR_MESSAGE, 11]]];
+    }
+
+    protected function getRule(): Rule
+    {
+        return new NoClassLevelRouteRule();
+    }
+}