Make it possible to opt out of loading api.php files (#641)

* Make it possible to opt out of loading api.php files

* Do not use empty

* Refactor and rename logic

* add bleedingEdge config

* Rename bleeding edge toggle, hardcoded core deprecated hooks

* clean up logic for hardcoded hooks when miss on hook function reflection

* only check deprecated_field_widget_hooks on 9.x

---------

Co-authored-by: Matt Glaman <[email protected]>

Author: eiriksm

bleedingEdge.neon

@@ -0,0 +1,4 @@
+parameters:
+	drupal:
+		bleedingEdge:
+			checkDeprecatedHooksInApiFiles: true

extension.neon

@@ -17,6 +17,8 @@ parameters:
 		- stubs/Twig/functions.stub
 	drupal:
 		drupal_root: '%currentWorkingDirectory%'
+		bleedingEdge:
+			checkDeprecatedHooksInApiFiles: false
 		entityMapping:
 			aggregator_feed:
 				class: Drupal\aggregator\Entity\Feed
@@ -233,6 +235,9 @@ parameters:
 parametersSchema:
 	drupal: structure([
 		drupal_root: string()
+		bleedingEdge: structure([
+			checkDeprecatedHooksInApiFiles: boolean()
+		])
 		entityMapping: arrayOf(anyOf(
 			structure([
 				class: string()

src/Drupal/DrupalAutoloader.php

@@ -57,6 +57,9 @@ class DrupalAutoloader
 
     public function register(Container $container): void
     {
+        /**
+         * @var array{drupal_root: string, bleedingEdge: array{checkDeprecatedHooksInApiFiles: bool}} $drupalParams
+         */
         $drupalParams = $container->getParameter('drupal');
         $drupalRoot = realpath($drupalParams['drupal_root']);
         $finder = new DrupalFinder();
@@ -94,6 +97,7 @@ public function register(Container $container): void
         $this->addThemeNamespaces();
         $this->registerPs4Namespaces($this->namespaces);
         $this->loadLegacyIncludes();
+        $checkDeprecatedHooksInApiFiles =  $drupalParams['bleedingEdge']['checkDeprecatedHooksInApiFiles'];
 
         foreach ($this->moduleData as $extension) {
             $this->loadExtension($extension);
@@ -112,7 +116,7 @@ public function register(Container $container): void
                 $this->loadAndCatchErrors($module_dir . '/' . $module_name . '.post_update.php');
             }
             // Add .api.php
-            if (file_exists($module_dir . '/' . $module_name . '.api.php')) {
+            if ($checkDeprecatedHooksInApiFiles && 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.

src/Rules/Deprecations/DeprecatedHookImplementation.php

@@ -13,10 +13,7 @@
 class DeprecatedHookImplementation implements Rule
 {
 
-    /**
-     * @var \PHPStan\Reflection\ReflectionProvider
-     */
-    protected $reflectionProvider;
+    protected ReflectionProvider $reflectionProvider;
 
     public function __construct(ReflectionProvider $reflectionProvider)
     {
@@ -48,6 +45,36 @@ public function processNode(Node $node, Scope $scope) : array
 
         $hook_name_node = new Name($hook_name);
         if (!$this->reflectionProvider->hasFunction($hook_name_node, $scope)) {
+            // @todo replace this hardcoded logic with something more intelligent and extensible.
+            if ($hook_name === 'hook_field_widget_form_alter') {
+                return $this->buildError(
+                    $function_name,
+                    $hook_name,
+                    'in drupal:9.2.0 and is removed from drupal:10.0.0. Use hook_field_widget_single_element_form_alter instead.'
+                );
+            }
+            if (str_starts_with($hook_name, 'hook_field_widget_') && str_ends_with($hook_name, '_form_alter')) {
+                return $this->buildError(
+                    $function_name,
+                    'hook_field_widget_WIDGET_TYPE_form_alter',
+                    'in drupal:9.2.0 and is removed from drupal:10.0.0. Use hook_field_widget_single_element_WIDGET_TYPE_form_alter instead.'
+                );
+            }
+            if ($hook_name === 'hook_field_widget_multivalue_form_alter') {
+                return $this->buildError(
+                    $function_name,
+                    $hook_name,
+                    'in drupal:9.2.0 and is removed from drupal:10.0.0. Use hook_field_widget_complete_form_alter instead.'
+                );
+            }
+            if (str_starts_with($hook_name, 'hook_field_widget_multivalue_') && str_ends_with($hook_name, '_form_alter')) {
+                return $this->buildError(
+                    $function_name,
+                    'hook_field_widget_multivalue_WIDGET_TYPE_form_alter',
+                    'in drupal:9.2.0 and is removed from drupal:10.0.0. Use hook_field_widget_complete_WIDGET_TYPE_form_alter instead.'
+                );
+            }
+
             return [];
         }
 
@@ -56,12 +83,15 @@ public function processNode(Node $node, Scope $scope) : array
             return [];
         }
 
-        $deprecation_description = $reflection->getDeprecatedDescription();
-        $deprecation_message = $deprecation_description !== null ? " $deprecation_description" : ".";
+        return $this->buildError($function_name, $hook_name, $reflection->getDeprecatedDescription());
+    }
 
+    private function buildError(string $function_name, string $hook_name, ?string $deprecated_description): array
+    {
+        $deprecated_description = $deprecated_description !== null ? " $deprecated_description" : ".";
         return [
             RuleErrorBuilder::message(
-                "Function $function_name implements $hook_name which is deprecated$deprecation_message",
+                "Function $function_name implements $hook_name which is deprecated$deprecated_description",
             )->build()
         ];
     }

tests/fixtures/config/phpunit-drupal-phpstan.neon

@@ -16,4 +16,5 @@ parameters:
 includes:
 	- ../../../extension.neon
 	- ../../../rules.neon
+	- ../../../bleedingEdge.neon
 	- ../../../vendor/phpstan/phpstan-deprecation-rules/rules.neon

tests/src/Rules/DeprecatedHookImplementationTest.php

@@ -3,14 +3,14 @@
 namespace mglaman\PHPStanDrupal\Tests\Rules;
 
 use mglaman\PHPStanDrupal\Rules\Deprecations\DeprecatedHookImplementation;
+use mglaman\PHPStanDrupal\Tests\DrupalRuleTestCase;
 use PHPStan\Reflection\ReflectionProvider;
 use PHPStan\Rules\Rule;
-use PHPStan\Testing\RuleTestCase;
 
 /**
  * Test the rule to detected deprecated hook implementations.
  */
-class DeprecatedHookImplementationTest extends RuleTestCase {
+class DeprecatedHookImplementationTest extends DrupalRuleTestCase {
 
     /**
      * {@inheritdoc}
@@ -35,6 +35,21 @@ public function testRule() : void {
                 5,
             ],
         ]);
+        [$version] = explode('.', \Drupal::VERSION, 2);
+        if ($version === '9') {
+            $this->analyse([__DIR__ . '/data/deprecated_field_widget_hooks.module'],
+                [
+                    [
+                        'Function deprecated_field_widget_hooks_field_widget_form_alter implements hook_field_widget_form_alter which is deprecated in drupal:9.2.0 and is removed from drupal:10.0.0. Use
+  hook_field_widget_single_element_form_alter instead.',
+                        5
+                    ],
+                    [
+                        'Function deprecated_field_widget_hooks_field_widget_textfield_form_alter implements hook_field_widget_WIDGET_TYPE_form_alter which is deprecated in drupal:9.2.0 and is removed from drupal:10.0.0. Use hook_field_widget_single_element_WIDGET_TYPE_form_alter instead.',
+                        9
+                    ]
+                ]);
+        }
     }
 
 }

tests/src/Rules/data/deprecated_field_widget_hooks.module

@@ -0,0 +1,11 @@
+<?php
+
+namespace DerecatedFieldWidgetHooks;
+
+function deprecated_field_widget_hooks_field_widget_form_alter() {
+
+}
+
+function deprecated_field_widget_hooks_field_widget_textfield_form_alter() {
+
+}