Merge branch 'master' of github.com:Phauthentic/phpstan-rules

Author: Florian Krämer

README.md

@@ -22,10 +22,25 @@ See [Rules documentation](docs/Rules.md) for a list of available rules and confi
 
 ### Using Regex in Rules
 
-A lot of the rules use regex patterns to match things. Many people are not good in writing them but thankfully there is AI today.
+A lot of the rules use regex patterns to match things. Many people are not good at writing them but thankfully there is AI today.
 
 If you struggle to write the regex patterns you need, you can use AI tools like [ChatGPT](https://chat.openai.com/) to help you generate them. Just describe what you want to match, and it can provide you with a regex pattern that fits your needs.  The regex can be tested using online tools like [regex101](https://regex101.com/).
 
+## Why PHPStan to enforce Architectural Rules?
+
+Because PHPStan is a widely used static analysis tool in the PHP community. It already provides a solid foundation for code quality checks, and adding custom rules allows you to enforce specific coding standards and architectural constraints is just a logical choice. You won't need more 3rd party tools to enforce your architectural constraints.
+
+It is also more or less easy to write your own rules if you need to enforce something specific that is not covered by the existing rules.
+
+### Alternative Tools
+
+If you don't like this library, you can also check out other tools. Some of them provide a fluent interface instead of a Regex. If this feels more comfortable for you, you might want to check them out:
+
+* [Deptrac](https://github.com/deptrac/deptrac) - Checks dependencies between namespaces and classes.
+* [PHP Architecture Tester](https://www.phpat.dev/) - A tool to enforce architectural rules in PHP applications.
+* [PHPArkitect](https://github.com/phparkitect/arkitect) - A tool to enforce architectural rules in PHP applications.
+* [PHPMD](https://phpmd.org/) - A tool that scans PHP source code and looks for potential problems.
+
 ## License
 
 This library is under the MIT license.

composer.json

@@ -8,7 +8,12 @@
     },
     "autoload": {
         "psr-4": {
-            "Phauthentic\\PhpstanRules\\": "src/"
+            "Phauthentic\\PHPStanRules\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Phauthentic\\PHPStanRules\\Tests\\": "tests/"
         }
     },
     "authors": [

docs/Rules.md

@@ -3,56 +3,48 @@
 
 Add them to your `phpstan.neon` configuration file under the section `services`.
 
----
-
 ## Control Structure Nesting Rule
 
 Ensures that the nesting level of `if` and `try-catch` statements does not exceed a specified limit.
 
 **Configuration Example:**
 ```neon
     -
-        class: Phauthentic\PhpstanRules\ControlStructureNestingRule
+        class: Phauthentic\PhpstanRules\CleanCode\ControlStructureNestingRule
         arguments:
             maxNestingLevel: 2
         tags:
             - phpstan.rules.rule
 ```
 
----
-
 ## Too Many Arguments Rule
 
 Checks that methods do not have more than a specified number of arguments.
 
 **Configuration Example:**
 ```neon
     -
-        class: Phauthentic\PhpstanRules\TooManyArgumentsRule
+        class: Phauthentic\PhpstanRules\CleanCode\TooManyArgumentsRule
         arguments:
             maxArguments: 3
         tags:
             - phpstan.rules.rule
 ```
 
----
-
 ## Readonly Class Rule
 
 Ensures that classes matching specified patterns are declared as `readonly`.
 
 **Configuration Example:**
 ```neon
     -
-        class: Phauthentic\PhpstanRules\ReadonlyClassRule
+        class: Phauthentic\PhpstanRules\Architecture\ReadonlyClassRule
         arguments:
             patterns: ['/^App\\Controller\\/']
         tags:
             - phpstan.rules.rule
 ```
 
----
-
 ## Dependency Constraints Rule
 
 Enforces dependency constraints between namespaces by checking `use` statements.
@@ -64,7 +56,7 @@ In the example below nothing from `App\Domain` can depend on anything from `App\
 **Configuration Example:**
 ```neon
     -
-        class: Phauthentic\PhpstanRules\DependencyConstraintsRule
+        class: Phauthentic\PhpstanRules\Architecture\DependencyConstraintsRule
         arguments:
             forbiddenDependencies: [
                 '/^App\\Domain(?:\\\w+)*$/': ['/^App\\Controller\\/']
@@ -73,37 +65,35 @@ In the example below nothing from `App\Domain` can depend on anything from `App\
             - phpstan.rules.rule
 ```
 
----
-
 ## Final Class Rule
 
 Ensures that classes matching specified patterns are declared as `final`.
 
 **Configuration Example:**
 ```neon
     -
-        class: Phauthentic\PhpstanRules\FinalClassRule
+        class: Phauthentic\PhpstanRules\Architecture\FinalClassRule
         arguments:
             patterns: ['/^App\\Service\\/']
         tags:
             - phpstan.rules.rule
 ```
 
----
-
 ## Namespace Class Pattern Rule
 
 Ensures that classes inside namespaces matching a given regex must have names matching at least one of the provided patterns.
 
 **Configuration Example:**
 ```neon
     -
-        class: Phauthentic\PhpstanRules\NamespaceClassPatternRule
+        class: Phauthentic\PhpstanRules\Architecture\NamespaceClassPatternRule
         arguments:
             namespaceClassPatterns: [
                 [
                     namespace: '/^App\\Service$/',
-                    classPatterns: ['/Class$/']
+                    classPatterns: [
+                        '/Class$/'
+                    ]
                 ]
             ]
         tags:

phpstan.neon

@@ -7,39 +7,39 @@ parameters:
 
 services:
     -
-        class: Phauthentic\PhpstanRules\ControlStructureNestingRule
+        class: Phauthentic\PhpstanRules\CleanCode\ControlStructureNestingRule
         arguments:
             maxNestingLevel: 2
         tags:
             - phpstan.rules.rule
     -
-        class: Phauthentic\PhpstanRules\TooManyArgumentsRule
+        class: Phauthentic\PhpstanRules\CleanCode\TooManyArgumentsRule
         arguments:
             maxArguments: 3
         tags:
             - phpstan.rules.rule
     -
-        class: Phauthentic\PhpstanRules\ReadonlyClassRule
+        class: Phauthentic\PhpstanRules\Architecture\ReadonlyClassRule
         arguments:
             patterns: ['/^App\\Controller\\/']
         tags:
             - phpstan.rules.rule
     -
-        class: Phauthentic\PhpstanRules\DependencyConstraintsRule
+        class: Phauthentic\PhpstanRules\Architecture\DependencyConstraintsRule
         arguments:
             forbiddenDependencies: [
                 '/^App\\Domain(?:\\\w+)*$/': ['/^App\\Controller\\/']
             ]
         tags:
             - phpstan.rules.rule
     -
-        class: Phauthentic\PhpstanRules\FinalClassRule
+        class: Phauthentic\PhpstanRules\Architecture\FinalClassRule
         arguments:
             patterns: ['/^App\\Service\\/']
         tags:
             - phpstan.rules.rule
     -
-        class: Phauthentic\PhpstanRules\NamespaceClassPatternRule
+        class: Phauthentic\PhpstanRules\Architecture\NamespaceClassPatternRule
         arguments:
             namespaceClassPatterns: [
                 [

src/FinalClassRule.php renamed to src/Architecture/ClassMustBeFinalRule.php

@@ -2,21 +2,24 @@
 
 declare(strict_types=1);
 
-namespace Phauthentic\PhpstanRules;
+namespace Phauthentic\PHPStanRules\Architecture;
 
 use PhpParser\Node;
 use PhpParser\Node\Stmt\Class_;
 use PHPStan\Analyser\Scope;
 use PHPStan\Rules\Rule;
 use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\ShouldNotHappenException;
 
 /**
  * @implements Rule<Class_>
  */
-class FinalClassRule implements Rule
+class ClassMustBeFinalRule implements Rule
 {
     private const ERROR_MESSAGE = 'Class %s must be final.';
 
+    private const IDENTIFIER = 'phauthentic.architecture.classMustBeFinal';
+
     /**
      * @var array<string> An array of regex patterns to match against class names.
      * e.g., ['#^App\\Domain\\.*#', '#^App\\Service\\.*#']
@@ -37,6 +40,9 @@ public function getNodeType(): string
         return Class_::class;
     }
 
+    /**
+     * @throws ShouldNotHappenException
+     */
     public function processNode(Node $node, Scope $scope): array
     {
         if (!$node instanceof Class_ || !isset($node->name)) {
@@ -51,6 +57,7 @@ public function processNode(Node $node, Scope $scope): array
             if (preg_match($pattern, $fullClassName) && !$node->isFinal()) {
                 return [
                     RuleErrorBuilder::message(sprintf(self::ERROR_MESSAGE, $fullClassName))
+                        ->identifier(self::IDENTIFIER)
                         ->build(),
                 ];
             }

src/ReadonlyClassRule.php renamed to src/Architecture/ClassMustBeReadonlyRule.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Phauthentic\PhpstanRules;
+namespace Phauthentic\PHPStanRules\Architecture;
 
 use PhpParser\Node;
 use PhpParser\Node\Stmt\Class_;
@@ -13,10 +13,12 @@
 /**
  * @implements Rule<Class_>
  */
-class ReadonlyClassRule implements Rule
+class ClassMustBeReadonlyRule implements Rule
 {
     private const ERROR_MESSAGE = 'Class %s must be readonly.';
 
+    private const IDENTIFIER = 'phauthentic.architecture.classMustBeReadonly';
+
     /**
      * @var string[]
      */
@@ -49,6 +51,7 @@ public function processNode(Node $node, Scope $scope): array
             if (preg_match($pattern, $fullClassName) && !$node->isReadonly()) {
                 return [
                     RuleErrorBuilder::message(sprintf(self::ERROR_MESSAGE, $fullClassName))
+                        ->identifier(self::IDENTIFIER)
                         ->build(),
                 ];
             }

src/NamespaceClassPatternRule.php renamed to src/Architecture/ClassnameMustMatchPatternRule.php

@@ -2,23 +2,28 @@
 
 declare(strict_types=1);
 
-namespace Phauthentic\PhpstanRules;
+namespace Phauthentic\PHPStanRules\Architecture;
 
 use PhpParser\Node;
-use PhpParser\Node\Stmt\Namespace_;
 use PhpParser\Node\Stmt\Class_;
+use PhpParser\Node\Stmt\Namespace_;
 use PHPStan\Analyser\Scope;
 use PHPStan\Rules\Rule;
 use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\ShouldNotHappenException;
 
 /**
  * PHPStan rule to ensure that classes inside namespaces matching a given regex
  * must have names matching at least one of the provided patterns.
  *
  * @implements Rule<Namespace_>
  */
-class NamespaceClassPatternRule implements Rule
+class ClassnameMustMatchPatternRule implements Rule
 {
+    private const ERROR_MESSAGE = 'Class %s in namespace %s does not match any of the required patterns:';
+
+    private const IDENTIFIER = 'phauthentic.architecture.classnameMustMatchPattern';
+
     /**
      * @var array{namespace: string, classPatterns: string[]}[]
      */
@@ -91,7 +96,7 @@ private function classNameMatches(string $className, array $classPatterns): bool
     private function buildErrorMessage(string $fqcn, string $namespace, array $patterns): string
     {
         $lines = [
-            sprintf('Class %s in namespace %s does not match any of the required patterns:', $fqcn, $namespace),
+            sprintf(self::ERROR_MESSAGE, $fqcn, $namespace),
         ];
 
         foreach ($patterns as $pattern) {
@@ -108,13 +113,22 @@ private function buildErrorMessage(string $fqcn, string $namespace, array $patte
      * @param Class_ $stmt
      * @param array $errors
      * @return array
+     * @throws ShouldNotHappenException
      */
-    public function buildRuleError(string $namespaceName, string $className, $classPatterns, Class_ $stmt, array $errors): array
-    {
+    public function buildRuleError(
+        string $namespaceName,
+        string $className,
+        $classPatterns,
+        Class_ $stmt,
+        array $errors
+    ): array {
         $fqcn = $namespaceName ? $namespaceName . '\\' . $className : $className;
         $errors[] = RuleErrorBuilder::message(
-            $this->buildErrorMessage($fqcn, $namespaceName, $classPatterns)
-        )->line($stmt->getLine())->build();
+                $this->buildErrorMessage($fqcn, $namespaceName, $classPatterns)
+            )
+            ->line($stmt->getLine())
+            ->identifier(self::IDENTIFIER)
+            ->build();
 
         return $errors;
     }

src/DependencyConstraintsRule.php renamed to src/Architecture/DependencyConstraintsRule.php

@@ -2,14 +2,15 @@
 
 declare(strict_types=1);
 
-namespace Phauthentic\PhpstanRules;
+namespace Phauthentic\PHPStanRules\Architecture;
 
 use PhpParser\Node;
 use PhpParser\Node\Stmt\Use_;
 use PHPStan\Analyser\Scope;
 use PHPStan\Rules\Rule;
 use PHPStan\Rules\RuleError;
 use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\ShouldNotHappenException;
 
 /**
  * A PHPStan rule to enforce dependency constraints between namespaces.
@@ -22,6 +23,8 @@ class DependencyConstraintsRule implements Rule
 {
     private const ERROR_MESSAGE = 'Dependency violation: A class in namespace `%s` is not allowed to depend on `%s`.';
 
+    private const IDENTIFIER = 'phauthentic.architecture.dependencyConstraints';
+
     /**
      * @var array<string, array<string>>
      * An array where the key is a regex for the source namespace and the value is
@@ -43,6 +46,9 @@ public function getNodeType(): string
         return Use_::class;
     }
 
+    /**
+     * @throws ShouldNotHappenException
+     */
     public function processNode(Node $node, Scope $scope): array
     {
         $currentNamespace = $scope->getNamespace();
@@ -69,7 +75,7 @@ public function processNode(Node $node, Scope $scope): array
      * @param string $currentNamespace
      * @param array<RuleError> $errors
      * @return array<RuleError>
-     * @throws \PHPStan\ShouldNotHappenException
+     * @throws ShouldNotHappenException
      */
     public function validateUseStatements(Node $node, array $disallowedDependencyPatterns, string $currentNamespace, array $errors): array
     {
@@ -82,6 +88,7 @@ public function validateUseStatements(Node $node, array $disallowedDependencyPat
                         $currentNamespace,
                         $usedClassName
                     ))
+                    ->identifier(self::IDENTIFIER)
                     ->line($use->getStartLine())
                     ->build();
                 }