Implement a rule to check deprecated hook implementations (#634)

This will analyse hook implementations in `.inc` and `.module` files. It
detects a hook by looking at the pattern `mymodule_[hook]` which is
detected from the file-name the function is in.

It will replace `mymodule` with `hook` and then try to find a function
with that name. For this to work PHPStan Drupal's `DrupalAutoloader`
class must be adjusted to load `.api.php` files as well so that the
hooks can be discovered. In testing on the Open Social code-base
this did not cause any issues.

The rule will provide the deprecation message in the error if it's
provided, if no deprecation message was provided (i.e. a lonesome
`@deprecated` tag) then the hook will simply be shown as deprecated
without advice.

Author: Kingdutch

src/Drupal/DrupalAutoloader.php

@@ -111,6 +111,10 @@ public function register(Container $container): void
             if (file_exists($module_dir . '/' . $module_name . '.post_update.php')) {
                 $this->loadAndCatchErrors($module_dir . '/' . $module_name . '.post_update.php');
             }
+            // Add .api.php
+            if (file_exists($module_dir . '/' . $module_name . '.api.php')) {
+                $this->loadAndCatchErrors($module_dir . '/' . $module_name . '.api.php');
+            }
             // Add misc .inc that are magically allowed via hook_hook_info.
             $magic_hook_info_includes = [
                 'views',

src/Rules/Deprecations/DeprecatedHookImplementation.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace mglaman\PHPStanDrupal\Rules\Deprecations;
+
+use PhpParser\Node;
+use PhpParser\Node\Name;
+use PhpParser\Node\Stmt\Function_;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+
+class DeprecatedHookImplementation implements Rule
+{
+
+    /**
+     * @var \PHPStan\Reflection\ReflectionProvider
+     */
+    protected $reflectionProvider;
+
+    public function __construct(ReflectionProvider $reflectionProvider)
+    {
+        $this->reflectionProvider = $reflectionProvider;
+    }
+
+    public function getNodeType(): string
+    {
+        return Function_::class;
+    }
+
+    public function processNode(Node $node, Scope $scope) : array
+    {
+        assert($node instanceof Function_);
+        if (!str_ends_with($scope->getFile(), ".module") && !str_ends_with($scope->getFile(), ".inc")) {
+            return [];
+        }
+
+        // We want both name.module and name.views.inc, to resolve to name.
+        $module_name = explode(".", basename($scope->getFile()))[0];
+
+        // Hooks start with their own module's name.
+        if (!str_starts_with($node->name->toString(), "{$module_name}_")) {
+            return [];
+        }
+
+        $function_name = $node->name->toString();
+        $hook_name = substr_replace($function_name, "hook", 0, strlen($module_name));
+
+        $hook_name_node = new Name($hook_name);
+        if (!$this->reflectionProvider->hasFunction($hook_name_node, $scope)) {
+            return [];
+        }
+
+        $reflection = $this->reflectionProvider->getFunction($hook_name_node, $scope);
+        if (!$reflection->isDeprecated()->yes()) {
+            return [];
+        }
+
+        $deprecation_description = $reflection->getDeprecatedDescription();
+        $deprecation_message = $deprecation_description !== null ? " $deprecation_description" : ".";
+
+        return [
+            RuleErrorBuilder::message(
+                "Function $function_name implements $hook_name which is deprecated$deprecation_message",
+            )->build()
+        ];
+    }
+}

tests/fixtures/drupal/modules/module_with_deprecated_hooks/module_with_deprecated_hooks.api.php

@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * A deprecated hook with a message.
+ *
+ * @deprecated in drupal:9.2.0 and is removed from drupal:10.0.0. Use hook_other_example instead.
+ */
+function hook_example() {}
+
+/**
+ * A deprecated hook without a message.
+ *
+ * @deprecated
+ */
+function hook_example2() {}

tests/fixtures/drupal/modules/module_with_deprecated_hooks/module_with_deprecated_hooks.info.yml

@@ -0,0 +1,3 @@
+name: module_with_deprecated_hooks
+type: module
+core_version_requirement: ^8 || ^9

tests/fixtures/drupal/modules/module_with_deprecated_hooks/module_with_deprecated_hooks.module

@@ -0,0 +1,5 @@
+<?php
+
+function module_with_deprecated_hooks_example() {}
+
+function module_with_deprecated_hooks_example2() {}

tests/src/Rules/DeprecatedHookImplementationTest.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace mglaman\PHPStanDrupal\Tests\Rules;
+
+use mglaman\PHPStanDrupal\Rules\Deprecations\DeprecatedHookImplementation;
+use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+
+/**
+ * Test the rule to detected deprecated hook implementations.
+ */
+class DeprecatedHookImplementationTest extends RuleTestCase {
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function getRule(): Rule {
+        return new DeprecatedHookImplementation(
+            self::getContainer()->getByType(ReflectionProvider::class)
+        );
+    }
+
+    /**
+     * Ensure hook deprecations are flagged with and without reason.
+     */
+    public function testRule() : void {
+        $this->analyse([__DIR__ . '/../../fixtures/drupal/modules/module_with_deprecated_hooks/module_with_deprecated_hooks.module'], [
+        [
+                'Function module_with_deprecated_hooks_example implements hook_example which is deprecated in drupal:9.2.0 and is removed from drupal:10.0.0. Use hook_other_example instead.',
+                3,
+            ],
+            [
+                'Function module_with_deprecated_hooks_example2 implements hook_example2 which is deprecated.',
+                5,
+            ],
+        ]);
+    }
+
+}