Hook docs rule (#78)

Author: johnbillion

README.md

@@ -67,7 +67,7 @@ Please see [WooCommerce Stubs](https://github.com/php-stubs/woocommerce-stubs)
 - Provides dynamic return type extensions for many core functions
 - Defines some core constants
 - Handles special functions and classes e.g. `is_wp_error()`
-- Uses the optional docblock that precedes a call to `apply_filters()` to treat its return type as certain
+- Validates the optional docblock that precedes a call to `apply_filters()` and treats the type of its first `@param` as certain
 
 ### Usage of an `apply_filters()` docblock
 

extension.neon

@@ -59,6 +59,8 @@ services:
         class: SzepeViktor\PHPStan\WordPress\WPErrorParameterDynamicFunctionReturnTypeExtension
         tags:
             - phpstan.broker.dynamicFunctionReturnTypeExtension
+rules:
+    - SzepeViktor\PHPStan\WordPress\HookDocsRule
 parameters:
     bootstrapFiles:
         - %rootDir%/../../php-stubs/wordpress-stubs/wordpress-stubs.php

phpcs.xml.dist

@@ -4,6 +4,9 @@
 	<file>src/</file>
 	<file>tests/</file>
 
+	<exclude-pattern>tests/data</exclude-pattern>
+	<exclude-pattern>tests/functions.php</exclude-pattern>
+
 	<rule ref="PSR12NeutronRuleset">
 		<exclude name="Generic.Files.LineLength"/>
 		<exclude name="PEAR.Commenting.ClassComment"/>

src/ApplyFiltersDynamicFunctionReturnTypeExtension.php

@@ -17,12 +17,12 @@
 
 class ApplyFiltersDynamicFunctionReturnTypeExtension implements \PHPStan\Type\DynamicFunctionReturnTypeExtension
 {
-    /** @var \PHPStan\Type\FileTypeMapper */
-    protected $fileTypeMapper;
+    /** @var \SzepeViktor\PHPStan\WordPress\HookDocBlock */
+    protected $hookDocBlock;
 
     public function __construct(FileTypeMapper $fileTypeMapper)
     {
-        $this->fileTypeMapper = $fileTypeMapper;
+        $this->hookDocBlock = new HookDocBlock($fileTypeMapper);
     }
 
     public function isFunctionSupported(FunctionReflection $functionReflection): bool
@@ -42,26 +42,12 @@ public function isFunctionSupported(FunctionReflection $functionReflection): boo
     public function getTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $functionCall, Scope $scope): Type
     {
         $default = new MixedType();
-        $comment = self::getNullableNodeComment($functionCall);
+        $resolvedPhpDoc = $this->hookDocBlock->getNullableHookDocBlock($functionCall, $scope);
 
-        if ($comment === null) {
+        if ($resolvedPhpDoc === null) {
             return $default;
         }
 
-        // Fetch the docblock contents.
-        $code = $comment->getText();
-
-        // Resolve the docblock in scope.
-        $classReflection = $scope->getClassReflection();
-        $traitReflection = $scope->getTraitReflection();
-        $resolvedPhpDoc = $this->fileTypeMapper->getResolvedPhpDoc(
-            $scope->getFile(),
-            ($scope->isInClass() && $classReflection !== null) ? $classReflection->getName() : null,
-            ($scope->isInTrait() && $traitReflection !== null) ? $traitReflection->getName() : null,
-            $scope->getFunctionName(),
-            $code
-        );
-
         // Fetch the `@param` values from the docblock.
         $params = $resolvedPhpDoc->getParamTags();
 
@@ -71,23 +57,4 @@ public function getTypeFromFunctionCall(FunctionReflection $functionReflection,
 
         return $default;
     }
-
-    private static function getNullableNodeComment(FuncCall $node): ?\PhpParser\Comment\Doc
-    {
-        $startLine = $node->getStartLine();
-
-        while ($node !== null && $node->getStartLine() === $startLine) {
-            // Fetch the docblock from the node.
-            $comment = $node->getDocComment();
-
-            if ($comment !== null) {
-                return $comment;
-            }
-
-            /** @var \PhpParser\Node|null */
-            $node = $node->getAttribute('parent');
-        }
-
-        return null;
-    }
 }

src/HookDocBlock.php

@@ -0,0 +1,69 @@
+<?php
+
+/**
+ * Set return type of apply_filters() based on its optional preceding docblock.
+ */
+
+declare(strict_types=1);
+
+namespace SzepeViktor\PHPStan\WordPress;
+
+use PhpParser\Node\Expr\FuncCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\PhpDoc\ResolvedPhpDocBlock;
+use PHPStan\Type\FileTypeMapper;
+
+class HookDocBlock
+{
+
+    /** @var \PHPStan\Type\FileTypeMapper */
+    protected $fileTypeMapper;
+
+    public function __construct(FileTypeMapper $fileTypeMapper)
+    {
+        $this->fileTypeMapper = $fileTypeMapper;
+    }
+
+    public function getNullableHookDocBlock(FuncCall $functionCall, Scope $scope): ?ResolvedPhpDocBlock
+    {
+        $comment = self::getNullableNodeComment($functionCall);
+
+        if ($comment === null) {
+            return null;
+        }
+
+        // Fetch the docblock contents.
+        $code = $comment->getText();
+
+        // Resolve the docblock in scope.
+        $classReflection = $scope->getClassReflection();
+        $traitReflection = $scope->getTraitReflection();
+
+        return $this->fileTypeMapper->getResolvedPhpDoc(
+            $scope->getFile(),
+            ($scope->isInClass() && $classReflection !== null) ? $classReflection->getName() : null,
+            ($scope->isInTrait() && $traitReflection !== null) ? $traitReflection->getName() : null,
+            $scope->getFunctionName(),
+            $code
+        );
+    }
+
+    private static function getNullableNodeComment(FuncCall $node): ?\PhpParser\Comment\Doc
+    {
+        $startLine = $node->getStartLine();
+
+        while ($node !== null && $node->getStartLine() === $startLine) {
+            // Fetch the docblock from the node.
+            $comment = $node->getDocComment();
+
+            if ($comment !== null) {
+                return $comment;
+            }
+
+            /** @var \PhpParser\Node|null */
+            $node = $node->getAttribute('parent');
+        }
+
+        return null;
+    }
+}

src/HookDocsParamException.php

@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * Exception thrown when validating a PHPDoc docblock that precedes a hook.
+ */
+
+declare(strict_types=1);
+
+namespace SzepeViktor\PHPStan\WordPress;
+
+// phpcs:ignore SlevomatCodingStandard.Classes.SuperfluousExceptionNaming.SuperfluousSuffix
+class HookDocsParamException extends \DomainException
+{
+}