Making it possible to require methods in a class (#25)

Co-authored-by: Florian Krämer <[email protected]>

Author: floriankraemer

data/MethodSignatureMustMatch/RequiredMethodTestClass.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phauthentic\PHPStanRules\Tests\Data\MethodSignatureMustMatch;
+
+// This class is missing the required execute method
+class MyTestController
+{
+    public function index(): void
+    {
+    }
+}
+
+// This class implements the required method correctly
+class AnotherTestController
+{
+    public function execute(int $id): void
+    {
+    }
+}
+
+// This class is missing the required method
+class YetAnotherTestController
+{
+    public function something(): void
+    {
+    }
+}
+
+// This class should not be affected (doesn't match pattern)
+class NotAController
+{
+    public function execute(int $id): void
+    {
+    }
+}
+

docs/rules/Method-Signature-Must-Match-Rule.md

@@ -1,6 +1,6 @@
 # Method Signature Must Match Rule
 
-Ensures that methods matching a class and method name pattern have a specific signature, including parameter types, names, and count.
+Ensures that methods matching a class and method name pattern have a specific signature, including parameter types, names, and count. Optionally enforces that matching classes must implement the specified method.
 
 ## Configuration Example
 
@@ -30,4 +30,31 @@ Ensures that methods matching a class and method name pattern have a specific si
 - `minParameters`/`maxParameters`: Minimum/maximum number of parameters.
 - `signature`: List of expected parameter types and (optionally) name patterns.
 - `visibilityScope`: Optional visibility scope (e.g., `public`, `protected`, `private`).
+- `required`: Optional boolean (default: `false`). When `true`, enforces that any class matching the pattern must implement the method with the specified signature.
 
+## Required Methods
+
+When the `required` parameter is set to `true`, the rule will check if classes matching the pattern actually implement the specified method. If a matching class is missing the method, an error will be reported with details about the expected signature.
+
+### Example with Required Method
+
+```neon
+    -
+        class: Phauthentic\PHPStanRules\Architecture\MethodSignatureMustMatchRule
+        arguments:
+            signaturePatterns:
+                -
+                    pattern: '/^.*Controller::execute$/'
+                    minParameters: 1
+                    maxParameters: 1
+                    signature:
+                        -
+                            type: 'Request'
+                            pattern: '/^request$/'
+                    visibilityScope: 'public'
+                    required: true
+        tags:
+            - phpstan.rules.rule
+```
+
+In this example, any class ending with "Controller" must implement a public `execute` method that takes exactly one parameter of type `Request` named `request`.

src/Architecture/MethodSignatureMustMatchRule.php

@@ -33,6 +33,7 @@
  * - Checks if the types of the parameters match the expected types.
  * - Checks if the parameter names match the expected patterns.
  * - Checks if the method has the required visibility scope if specified (public, protected, private).
+ * - When required is set to true, enforces that matching classes must implement the method with the specified signature.
  */
 class MethodSignatureMustMatchRule implements Rule
 {
@@ -44,6 +45,7 @@ class MethodSignatureMustMatchRule implements Rule
     private const ERROR_MESSAGE_MIN_PARAMETERS = 'Method %s has %d parameters, but at least %d required.';
     private const ERROR_MESSAGE_MAX_PARAMETERS = 'Method %s has %d parameters, but at most %d allowed.';
     private const ERROR_MESSAGE_VISIBILITY_SCOPE = 'Method %s must be %s.';
+    private const ERROR_MESSAGE_REQUIRED_METHOD = 'Class %s must implement method %s with signature: %s.';
 
     /**
      * @param array<array{
@@ -54,7 +56,8 @@ class MethodSignatureMustMatchRule implements Rule
      *         type: string,
      *         pattern: string|null,
      *     }>,
-     *     visibilityScope?: string|null
+     *     visibilityScope?: string|null,
+     *     required?: bool|null
      * }> $signaturePatterns
      */
     public function __construct(
@@ -77,6 +80,12 @@ public function processNode(Node $node, Scope $scope): array
         $errors = [];
         $className = $node->name ? $node->name->toString() : '';
 
+        // Check for required methods first
+        $requiredMethodErrors = $this->checkRequiredMethods($node, $className);
+        foreach ($requiredMethodErrors as $error) {
+            $errors[] = $error;
+        }
+
         foreach ($node->getMethods() as $method) {
             $methodName = $method->name->toString();
             $fullName = $className . '::' . $methodName;
@@ -332,4 +341,140 @@ private function getTypeAsString(mixed $type): ?string
             default => null,
         };
     }
+
+    /**
+     * Extract class name pattern and method name from a regex pattern.
+     * Expected pattern format: '/^ClassName::methodName$/' or '/ClassName::methodName$/'
+     *
+     * @param string $pattern
+     * @return array|null Array with 'classPattern' and 'methodName', or null if parsing fails
+     */
+    private function extractClassAndMethodFromPattern(string $pattern): ?array
+    {
+        // Remove pattern delimiters and anchors
+        $cleaned = preg_replace('/^\/\^?/', '', $pattern);
+        $cleaned = preg_replace('/\$?\/$/', '', $cleaned);
+
+        if ($cleaned === null || !str_contains($cleaned, '::')) {
+            return null;
+        }
+
+        $parts = explode('::', $cleaned, 2);
+        if (count($parts) !== 2) {
+            return null;
+        }
+
+        return [
+            'classPattern' => $parts[0],
+            'methodName' => $parts[1],
+        ];
+    }
+
+    /**
+     * Check if a class name matches a pattern extracted from regex.
+     *
+     * @param string $className
+     * @param string $classPattern
+     * @return bool
+     */
+    private function classMatchesPattern(string $className, string $classPattern): bool
+    {
+        // Build a regex from the class pattern
+        $regex = '/^' . $classPattern . '$/';
+        return preg_match($regex, $className) === 1;
+    }
+
+    /**
+     * Format the expected method signature for error messages.
+     *
+     * @param array $patternConfig
+     * @return string
+     */
+    private function formatSignatureForError(array $patternConfig): string
+    {
+        $parts = [];
+
+        // Add visibility scope if specified
+        if (isset($patternConfig['visibilityScope']) && $patternConfig['visibilityScope'] !== null) {
+            $parts[] = $patternConfig['visibilityScope'];
+        }
+
+        $parts[] = 'function';
+
+        // Extract method name from pattern
+        $extracted = $this->extractClassAndMethodFromPattern($patternConfig['pattern']);
+        if ($extracted !== null) {
+            $parts[] = $extracted['methodName'];
+        }
+
+        // Build parameters
+        $params = [];
+        if (!empty($patternConfig['signature'])) {
+            foreach ($patternConfig['signature'] as $i => $sig) {
+                $paramParts = [];
+                if (isset($sig['type']) && $sig['type'] !== null) {
+                    $paramParts[] = $sig['type'];
+                }
+                $paramParts[] = '$param' . ($i + 1);
+                $params[] = implode(' ', $paramParts);
+            }
+        }
+
+        return implode(' ', $parts) . '(' . implode(', ', $params) . ')';
+    }
+
+    /**
+     * Check if required methods are implemented in the class.
+     *
+     * @param Class_ $node
+     * @param string $className
+     * @return array
+     */
+    private function checkRequiredMethods(Class_ $node, string $className): array
+    {
+        $errors = [];
+
+        // Get list of implemented methods
+        $implementedMethods = [];
+        foreach ($node->getMethods() as $method) {
+            $implementedMethods[] = $method->name->toString();
+        }
+
+        // Check each pattern with required flag
+        foreach ($this->signaturePatterns as $patternConfig) {
+            // Skip if not required
+            if (!isset($patternConfig['required']) || $patternConfig['required'] !== true) {
+                continue;
+            }
+
+            // Extract class and method patterns
+            $extracted = $this->extractClassAndMethodFromPattern($patternConfig['pattern']);
+            if ($extracted === null) {
+                continue;
+            }
+
+            // Check if class matches the pattern
+            if (!$this->classMatchesPattern($className, $extracted['classPattern'])) {
+                continue;
+            }
+
+            // Check if method is implemented
+            if (!in_array($extracted['methodName'], $implementedMethods, true)) {
+                $signature = $this->formatSignatureForError($patternConfig);
+                $errors[] = RuleErrorBuilder::message(
+                    sprintf(
+                        self::ERROR_MESSAGE_REQUIRED_METHOD,
+                        $className,
+                        $extracted['methodName'],
+                        $signature
+                    )
+                )
+                ->identifier(self::IDENTIFIER)
+                ->line($node->getLine())
+                ->build();
+            }
+        }
+
+        return $errors;
+    }
 }

tests/TestCases/Architecture/MethodSignatureMustMatchRuleRequiredTest.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phauthentic\PHPStanRules\Tests\TestCases\Architecture;
+
+use Phauthentic\PHPStanRules\Architecture\MethodSignatureMustMatchRule;
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+
+/**
+ * @extends RuleTestCase<MethodSignatureMustMatchRule>
+ */
+class MethodSignatureMustMatchRuleRequiredTest extends RuleTestCase
+{
+    protected function getRule(): Rule
+    {
+        return new MethodSignatureMustMatchRule([
+            [
+                'pattern' => '/^.*TestController::execute$/',
+                'minParameters' => 1,
+                'maxParameters' => 1,
+                'signature' => [
+                    ['type' => 'int', 'pattern' => '/^id$/'],
+                ],
+                'visibilityScope' => 'public',
+                'required' => true,
+            ],
+        ]);
+    }
+
+    public function testRequiredMethodRule(): void
+    {
+        $this->analyse([__DIR__ . '/../../../data/MethodSignatureMustMatch/RequiredMethodTestClass.php'], [
+            // MyTestController is missing the required execute method
+            [
+                'Class MyTestController must implement method execute with signature: public function execute(int $param1).',
+                8,
+            ],
+            // AnotherTestController implements the method correctly - no error expected
+
+            // YetAnotherTestController is missing the required execute method
+            [
+                'Class YetAnotherTestController must implement method execute with signature: public function execute(int $param1).',
+                24,
+            ],
+            // NotAController doesn't match the pattern - no error expected
+        ]);
+    }
+}