Changeset 62939 for trunk/tests/phpstan/base.neon

Timestamp:

07/30/2026 04:45:34 AM (3 months ago)

Author:

westonruter

Message:

Build/Test Tools: Verify hook docblocks statically.

Add PHPStan extensions that read the docblock documenting each hook where the hook is fired. The value apply_filters() returns is typed from the first @param that docblock documents rather than mixed; core's /** This filter is documented in <file> */ convention is resolved, so a hook documented elsewhere is analyzed against its canonical docblock, including a dynamic canonical name such as "{$type}_template_hierarchy"; and two rules require every hook invocation to be documented, and to pass as many arguments as its documentation describes.

These conventions were previously enforced by review alone. A reference comment could name a file that no longer documents the hook, and a call site could pass fewer arguments than documented, which raises an ArgumentCountError in a callback registered for the documented count, or more, which drops the extra argument and leaves the documentation wrong. Both are now reported where they occur. The hook issues this surfaced in core were fixed in preceding commits.

The generated src/wp-includes/build tree is excluded from analysis, as its sources live in the Gutenberg plugin.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12022.
Follow-up to r61699, r62292, r62893, r62894, r62925, r62926, r62927, r62928, r62930, r62931, r62932, r62933, r62934, r62935.

Props westonruter, szepeviktor, khokansardar.
See #64898.
Fixes #65376.

File:

• trunk/tests/phpstan/base.neon (modified) (3 diffs)

trunk/tests/phpstan/base.neon

@@ -12 +12 @@
                 tags:
                         - phpstan.parser.richParserNodeVisitor
+
+        # Attaches the docblock documenting a hook to the hook's call, so that the return
+        # type extension and the rules below can all read it.
+        -
+                class: WordPress\PHPStan\HookDocsVisitor
+                tags:
+                        - phpstan.parser.richParserNodeVisitor
+
+        # Resolves a hook call's documentation, whether written at the call or inherited
+        # through the "This filter is documented in <file>" convention.
+        -
+                class: WordPress\PHPStan\HookDocBlock
+
+        # Types the return value of apply_filters() (and variants) from the `@param` type
+        # documented for the value being filtered. Adapted from szepeviktor/phpstan-wordpress.
+        -
+                class: WordPress\PHPStan\ApplyFiltersDynamicFunctionReturnTypeExtension
+                tags:
+                        - phpstan.broker.dynamicFunctionReturnTypeExtension
+
+        # Enforces that every hook invocation is preceded by a documenting docblock or
+        # a valid "This filter is documented in <file>" reference comment.
+        -
+                class: WordPress\PHPStan\HookDocumentationRule
+                tags:
+                        - phpstan.rules.rule
+
+        # Enforces that a hook invocation passes as many arguments as its documentation
+        # (inline or referenced) describes.
+        -
+                class: WordPress\PHPStan\HookParamCountRule
+                tags:
+                        - phpstan.rules.rule
+
+        # Docblocks inherited from another file, and the sources above that read them,
+        # are invisible to PHPStan's dependency graph, so both are folded into the result
+        # cache key. Without this, editing a canonical hook docblock leaves the cached
+        # results of every call site inheriting it in place.
+        -
+                class: WordPress\PHPStan\HookDocsResultCacheMetaExtension
+                tags:
+                        - phpstan.resultCacheMetaExtension
 
 parameters:
@@ -100 +142 @@
                 - ../../src/xmlrpc.php
                 - GlobalDocBlockVisitor.php
+                - HookDocsVisitor.php
+                - HookDocBlock.php
+                - ApplyFiltersDynamicFunctionReturnTypeExtension.php
+                - HookDocumentationRule.php
+                - HookParamCountRule.php
+                - HookDocsResultCacheMetaExtension.php
         bootstrapFiles:
                 - bootstrap.php
@@ -120 +168 @@
                         # These files are autogenerated by tools/gutenberg/copy.js.
                         - ../../src/wp-includes/blocks
+                        # Generated output from the Gutenberg plugin's wp-build templates.
+                        - ../../src/wp-includes/build
                         # Third-party libraries.
                         - ../../src/wp-admin/includes/class-ftp-pure.php