Build/Test Tools: Statically verify that hook documentation and arguments stay in sync

[westonruter]

Teaches PHPStan to read WordPress's existing hook docblocks so that hook documentation, "documented elsewhere" references, and the arguments passed to hooks are verified automatically instead of by manual review — then fixes the issues this surfaces in core.

See the Trac ticket for the full problem framing. In short:

• The value returned from apply_filters() was typed as mixed, discarding the type already declared in the hook's docblock.
• /** This filter is documented in <file> */ reference comments were never verified, so they could point at a missing file or a file that no longer documents the hook.
• Nothing checked that a hook is fired with the number of arguments its docblock describes. Passing too few risks an ArgumentCountError (or a TypeError for a typed parameter) in a callback registered for the documented count; passing too many silently drops the extra argument and misleads the documentation.
• Undocumented hooks and malformed @param tags went unflagged.

What's in this PR

Tooling (in tests/phpstan/, wired in via base.neon so it applies to both the level‑0 phpstan.neon.dist and the local level‑10 config):

• A dynamic return-type extension that types apply_filters() from the first documented @param. Adapted from szepeviktor/phpstan-wordpress.
• Resolution of the "documented elsewhere" convention, including dynamic hook names (e.g. {$type}_template_hierarchy).
• A rule requiring every hook invocation to be documented (inline or via a valid reference).
• A rule requiring each invocation to pass the documented number of arguments.

Core fixes surfaced by the tooling:

• Hooks fired with fewer arguments than documented: edit_terms / edited_terms / edit_term_taxonomy / edited_term_taxonomy / term_id_filter, https_local_ssl_verify, wp_update_nav_menu, wp_creating_autosave, install_plugins_upload, activate_{$plugin}, the network handle_network_bulk_actions-{$screen} screens, and the XML‑RPC pre_option_enable_xmlrpc / option_enable_xmlrpc shim.
• Hooks fired with more arguments than documented: the_content in do_trackbacks() and the_excerpt in WP_REST_Revisions_Controller.
• Docblocks the tooling could not associate with their call: the editable_slug filter in get_inline_data() was buried inside a string concatenation, so its reference comment did not attach to the call; and the users_have_additional_content reference comment in confirm_delete_users() used a single-asterisk /* */ block — the only such instance in core, against 715 using the canonical /** */ form — which PhpParser does not expose as a docblock.
• Documentation fixes: malformed @param tags and a stale reference comment in bundled themes, the_permalink calls now passing the documented get_post() argument, and an accurate array<string, string> shape for wp_get_image_editor_output_format() and its image_editor_output_format filter.

All 40 PHPStan errors identified by the new extensions and fixed in this PR

Line numbers are omitted deliberately, so the table stays accurate as trunk moves.

File (under src/)	Hook	Issue	Rule
wp-admin/includes/class-wp-automatic-updater.php	https_local_ssl_verify	passes 1, documented 2	ParamCountMismatch
wp-admin/includes/class-wp-site-health.php ×3	https_local_ssl_verify	passes 1, documented 2	ParamCountMismatch
wp-admin/includes/file.php	https_local_ssl_verify	passes 1, documented 2	ParamCountMismatch
wp-admin/includes/ms.php	users_have_additional_content	no docblock or reference comment	DocMissing
wp-admin/includes/nav-menu.php	wp_update_nav_menu	passes 1, documented 2	ParamCountMismatch
wp-admin/includes/template.php	editable_slug	no docblock or reference comment	DocMissing
wp-admin/network/themes.php	(dynamic)	passes 3, documented 4	ParamCountMismatch
wp-admin/network/users.php	(dynamic)	passes 3, documented 4	ParamCountMismatch
wp-admin/plugin-install.php	install_plugins_upload	passes 0, documented 1	ParamCountMismatch
wp-admin/plugins.php	(dynamic)	passes 0, documented 1	ParamCountMismatch
wp-content/themes/twentyeleven/author.php	twentyeleven_author_bio_avatar_size	passes 1, documented 0	ParamCountMismatch
wp-content/themes/twentyeleven/content-single.php	twentyeleven_author_bio_avatar_size	passes 1, documented 0	ParamCountMismatch
wp-content/themes/twentyeleven/content-status.php	twentyeleven_status_avatar	passes 1, documented 0	ParamCountMismatch
wp-content/themes/twentyeleven/functions.php	the_permalink	passes 1, documented 2	ParamCountMismatch
wp-content/themes/twentyeleven/image.php	twentyeleven_attachment_size	passes 1, documented 0	ParamCountMismatch
wp-content/themes/twentyeleven/inc/widgets.php	widget_title	reference to wp-includes/default-widgets.php documents no such hook	DocReferenceHookMissing
wp-content/themes/twentyeleven/tag.php	tag_archive_meta	passes 1, documented 0	ParamCountMismatch
wp-content/themes/twentyfifteen/inc/template-tags.php	—	no docblock or reference comment	DocMissing
wp-content/themes/twentyfourteen/inc/widgets.php	—	no docblock or reference comment	DocMissing
wp-content/themes/twentyten/functions.php	twentyten_header_image_height	passes 1, documented 0	ParamCountMismatch
wp-content/themes/twentyten/functions.php	twentyten_header_image_width	passes 1, documented 0	ParamCountMismatch
wp-content/themes/twentythirteen/functions.php	—	no docblock or reference comment	DocMissing
wp-content/themes/twentytwentyone/functions.php	twentytwentyone_html_classes	passes 1, documented 0	ParamCountMismatch
wp-includes/abilities-api/class-wp-ability.php	—	no docblock or reference comment	DocMissing
wp-includes/class-wp-xmlrpc-server.php ×2	—	no docblock or reference comment	DocMissing
wp-includes/comment.php	the_content	passes 2, documented 1	ParamCountMismatch
wp-includes/cron.php	https_local_ssl_verify	passes 1, documented 2	ParamCountMismatch
wp-includes/rest-api/endpoints/class-wp-rest-autosaves-controller.php	wp_creating_autosave	passes 1, documented 2	ParamCountMismatch
wp-includes/rest-api/endpoints/class-wp-rest-menus-controller.php	wp_update_nav_menu	passes 1, documented 2	ParamCountMismatch
wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php	the_excerpt	passes 2, documented 1	ParamCountMismatch
wp-includes/taxonomy.php ×2	edit_term_taxonomy	passes 2, documented 3	ParamCountMismatch
wp-includes/taxonomy.php	edit_terms	passes 2, documented 3	ParamCountMismatch
wp-includes/taxonomy.php ×2	edited_term_taxonomy	passes 2, documented 3	ParamCountMismatch
wp-includes/taxonomy.php	edited_terms	passes 2, documented 3	ParamCountMismatch
wp-includes/taxonomy.php	term_id_filter	passes 2, documented 3	ParamCountMismatch

Static-analysis impact

Beyond the 40 hook-rule errors above, typing apply_filters() from its docblock changes what PHPStan can see across the whole codebase. To quantify that, PHPStan was run over trunk and over this branch and the two result sets compared.

Method. Both passes ran at level 10 with a cold result cache (the cache directory deleted outright before each pass — clear-result-cache is not sufficient, and a warm cache silently drops findings in exactly the files a branch edits). Errors are matched as a multiset keyed on file + identifier + message, deliberately ignoring line numbers, so the diff is not polluted by line shifts. Baseline trunk at c5690fd7e8, branch at 1a377052b0.

This is a local-config measurement, not a CI one. CI runs phpstan.neon.dist at level 0 with a baseline, where none of these type-level errors are reported in the first place; that config is clean both before and after. The numbers below come from a local level‑10 + bleedingEdge config, which is where filter return types actually change the analysis.

Metric	Value
Errors on trunk	32,651
Errors on this branch	29,744
Net change	−2,907
Errors fixed	3,133
Errors introduced	226
% of baseline fixed	9.60%
Net reduction	8.90%

Errors fixed (3,133)

Count	Identifier
964	argument.type
753	return.type
658	offsetAccess.nonOffsetAccessible
143	binaryOp.invalid
125	encapsedStringPart.nonString
107	echo.nonString
105	property.nonObject
70	foreach.nonIterable
57	offsetAccess.invalidOffset
50	assign.propertyType
25	missingType.return
21	method.nonObject
16	assignOp.invalid
9	missingType.iterableValue
8	new.nonObject
6	cast.string
5	phpDoc.parseError
3	variable.undefined
3	parameterByRef.type
2	offsetAccess.notFound
1	property.nameNotString
1	offsetAccess.nonArray
1	array.invalidKey

The shape of that list is the point: the top three identifiers are all "PHPStan could not reason about this value at all". Every one of those was a filtered value that the docblock already described.

Most-improved files

Count	File (under src/)
115	wp-includes/general-template.php
106	wp-includes/class-wp-query.php
103	wp-includes/user.php
98	wp-includes/link-template.php
95	wp-includes/comment-template.php
83	wp-includes/media.php
82	wp-includes/category-template.php
75	wp-includes/post-template.php
69	wp-includes/pluggable.php
68	wp-admin/includes/media.php
59	wp-includes/functions.php
58	wp-includes/formatting.php
56	wp-includes/class-wp-term-query.php
56	wp-includes/post.php
47	wp-admin/includes/file.php
44	wp-includes/blocks.php
43	wp-includes/comment.php
42	wp-includes/build/routes.php
37	wp-includes/ms-functions.php
37	wp-login.php
35	wp-admin/includes/upgrade.php
32	wp-admin/includes/ajax-actions.php
32	wp-includes/class-wp-http.php
32	wp-includes/class-wp.php
30	wp-includes/taxonomy.php

Errors introduced (226)

Count	Identifier
93	argument.type
35	return.type
21	property.nonObject
20	property.notFound
15	binaryOp.invalid
9	assign.propertyType
7	offsetAccess.nonOffsetAccessible
7	offsetAccess.invalidOffset
7	return.unusedType
6	offsetAccess.notFound
2	foreach.nonIterable
2	argument.unresolvableType
1	function.alreadyNarrowedType
1	echo.nonString

None of these are regressions from the code changes in this PR. 188 of the 226 are in files this PR never edits — they are only reachable because a filter's return type stopped being mixed. The remaining 38 are in files this PR does edit, but every edit in those files is an argument-count fix or a comment relocation; none changes a type, and each introduced error sits at an unrelated site in the same file. class-wp-site-health.php, for example, only gains a $url argument to https_local_ssl_verify, yet its one new error is a return-shape mismatch in perform_test().

What these really are is a list of places where core's own hook documentation is less precise than the code requires. Three clusters stand out:

• cron.php (12 errors). pre_get_scheduled_event is documented as returning a bare object, so every ->timestamp, ->schedule, ->hook, ->args and ->interval access on the result is now an undefined property. The docblock should describe a shape, not object.
• class-wp-query.php (32 errors). the_posts is documented as array<int|stdClass|WP_Post|null>. Taken at face value, $post->ID on its result is invalid — the documented type is looser than what the class actually requires of it.
• return.unusedType (7 errors). Documented union members that provably cannot occur, e.g. "plugins_api() never returns array", and likewise for get_the_tag_list(), wp_mime_type_icon() and wp_get_code_editor_settings().

Fixing those docblocks is out of scope here — this PR deliberately does not chase the newly-visible errors, only the hook-rule ones. They are listed so the trade-off is explicit.

The 38 introduced errors in files this PR edits

Listed in full because these are the ones where a regression could plausibly hide. Counts in parentheses where an identical error occurs more than once.

• wp-admin/includes/class-wp-site-health.php — [return.type] WP_Site_Health::perform_test() should return array{label: string, status: 'critical'|'good'|'recommended', badge: array{label: string, color: string}, description: string, actions: string, test: string} but returns array.
• wp-admin/includes/file.php — [return.type] _wp_handle_upload() should return array{error: non-empty-string}|array{file: non-empty-string, url: non-empty-string, type: non-empty-string} but returns array.
• wp-admin/includes/file.php — [argument.type] Parameter #41488: Fix handling of backslashes encoded in in partial placement context data #2 $length of fread() expects int<1, max>, int given.
• wp-admin/includes/nav-menu.php — [argument.type] (×2) Parameter Remove post_ID requirement from parse_embed AJAX call #7 $callback_args of add_meta_box() expects array|null, WP_Post_Type given.
• wp-admin/includes/template.php — [argument.type] Parameter Update class class-pclzip.php #1 $array_arg of natcasesort() expects an array of values castable to string, array given.
• wp-content/themes/twentyeleven/functions.php — [argument.type] Parameter #41488: Fix handling of backslashes encoded in in partial placement context data #2 $width of add_image_size() expects int<0, max>, int given.
• wp-content/themes/twentyeleven/functions.php — [argument.type] Parameter Build Tools: Don't send Slack notifications for Travis CI pull requests #3 $height of add_image_size() expects int<0, max>, int given.
• wp-content/themes/twentyeleven/functions.php — [return.type] twentyeleven_get_first_url() should return string but returns string|true.
• wp-content/themes/twentythirteen/functions.php — [argument.type] Parameter #41488: Fix handling of backslashes encoded in in partial placement context data #2 $size of wp_get_attachment_image() expects array<int>|string, array given.
• wp-includes/class-wp-xmlrpc-server.php — [argument.type] Parameter Update class class-pclzip.php #1 $str of strip_tags() expects string, string|null given.
• wp-includes/class-wp-xmlrpc-server.php — [argument.type] Parameter #41488: Fix handling of backslashes encoded in in partial placement context data #2 $subject of preg_match() expects string, string|null given.
• wp-includes/class-wp-xmlrpc-server.php — [argument.type] (×2) Parameter Build Tools: Don't send Slack notifications for Travis CI pull requests #3 $subject of preg_replace() expects array<float|int|string>|string, string|null given.
• wp-includes/comment.php — [return.type] wp_count_comments() should return stdClass but returns array|stdClass.
• wp-includes/cron.php — [property.notFound] (×3) Access to an undefined property object::$args.
• wp-includes/cron.php — [property.notFound] (×2) Access to an undefined property object::$hook.
• wp-includes/cron.php — [property.notFound] (×2) Access to an undefined property object::$schedule.
• wp-includes/cron.php — [property.notFound] (×2) Access to an undefined property object::$timestamp.
• wp-includes/cron.php — [property.notFound] Access to an undefined property object::$interval.
• wp-includes/cron.php — [argument.unresolvableType] (×2) Parameter Update class class-pclzip.php #1 $array_arg of uksort() contains unresolvable type.
• wp-includes/media.php — [return.type] image_downsize() should return array|false but returns non-empty-array|true.
• wp-includes/media.php — [return.type] wp_get_attachment_id3_keys() should return array<string> but returns array.
• wp-includes/media.php — [return.unusedType] get_post_gallery() never returns string so it can be removed from the return type.
• wp-includes/media.php — [argument.type] Parameter Update class class-pclzip.php #1 $function of call_user_func() expects callable(): mixed, array{string, 'test'} given.
• wp-includes/media.php — [argument.type] (×2) Parameter Update class class-pclzip.php #1 $function of call_user_func() expects callable(): mixed, array{string, 'supports_mime_type'} given.
• wp-includes/media.php — [argument.type] Parameter Build Tools: Don't send Slack notifications for Travis CI pull requests #3 $l10n of wp_localize_script() expects array<string, mixed>, array<array|string> given.
• wp-includes/media.php — [foreach.nonIterable] Argument of an invalid type array<stdClass>|null supplied for foreach.
• wp-includes/taxonomy.php — [return.type] get_terms() should return array<int|string|WP_Term>|string|WP_Error but returns array.
• wp-includes/taxonomy.php — [property.notFound] Access to an undefined property object::$term_id.
• wp-includes/taxonomy.php — [property.notFound] Access to an undefined property object::$term_taxonomy_id.

Notes for reviewers

• The argument-count fixes change which arguments callbacks receive, so they're worth reviewing against existing hook consumers. Where a call site had no meaningful value for a documented parameter (e.g. term-count callbacks, network-wide bulk screens), an empty array or 0 is passed to satisfy the signature.
• The Gutenberg-generated src/wp-includes/build tree is excluded from analysis; the corresponding fix lives in the Gutenberg wp-build page templates and is handled separately.
• The full analysis is clean: phpstan.neon.dist reports no errors, and no hook-rule errors remain at level 10.

Trac ticket: https://core.trac.wordpress.org/ticket/65376

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 4.8, Claude Opus 5
Used for: Drafting the PHPStan extension and rules, locating and fixing the hook issues across core, and ecosystem impact research. All changes were reviewed and directed by me.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[Copilot]

Pull request overview

This PR adds PHPStan support for validating WordPress hook documentation against hook invocations, then updates core and bundled theme call sites/docblocks to satisfy the new checks.

Changes:

• Adds PHPStan hook docblock resolution, return-type inference for filters, documentation validation, and hook argument-count validation.
• Extends global docblock handling for file-scope globals used by PHPStan.
• Fixes discovered hook argument mismatches and malformed/missing hook documentation across core and bundled themes.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/phpstan/HookParamCountRule.php	Adds rule comparing provided hook arguments with documented parameters.
tests/phpstan/HookDocumentationRule.php	Adds rule requiring hook docs or valid documented-elsewhere references.
tests/phpstan/HookDocsVisitor.php	Adds visitor that propagates hook docblocks to nested hook calls.
tests/phpstan/HookDocBlock.php	Adds hook docblock/reference resolution and dynamic hook-name matching.
tests/phpstan/GlobalDocBlockVisitor.php	Supports file-scope @global annotations on global statements.
tests/phpstan/base.neon	Registers new PHPStan services/rules and excludes generated build output.
tests/phpstan/ApplyFiltersDynamicFunctionReturnTypeExtension.php	Infers filter return types from documented first hook parameter.
src/wp-includes/taxonomy.php	Passes documented taxonomy hook arguments.
src/wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php	Aligns the_excerpt filter call with documented signature.
src/wp-includes/rest-api/endpoints/class-wp-rest-menus-controller.php	Passes documented menu data argument.
src/wp-includes/rest-api/endpoints/class-wp-rest-autosaves-controller.php	Passes documented autosave update flag.
src/wp-includes/media.php	Fixes PHPDoc array types for image editor output format.
src/wp-includes/cron.php	Passes cron URL to https_local_ssl_verify.
src/wp-includes/comment.php	Aligns the_content filter call with documented signature.
src/wp-includes/class-wp-xmlrpc-server.php	Adds option hook references and documented arguments.
src/wp-includes/abilities-api/class-wp-ability.php	Moves sentinel creation before the hook docblock.
src/wp-content/themes/twentytwentyone/functions.php	Adds missing hook parameter variable name.
src/wp-content/themes/twentythirteen/functions.php	Documents and updates the_permalink filter call.
src/wp-content/themes/twentyten/functions.php	Adds missing hook parameter variable names.
src/wp-content/themes/twentyfourteen/inc/widgets.php	Adds documented reference for widget_title.
src/wp-content/themes/twentyfifteen/inc/template-tags.php	Documents and updates the_permalink filter call.
src/wp-content/themes/twentyeleven/tag.php	Adds missing hook parameter variable name.
src/wp-content/themes/twentyeleven/inc/widgets.php	Updates stale widget_title documentation reference.
src/wp-content/themes/twentyeleven/image.php	Adds missing hook parameter variable name.
src/wp-content/themes/twentyeleven/functions.php	Updates the_permalink filter call arguments.
src/wp-content/themes/twentyeleven/content-status.php	Adds missing hook parameter variable name.
src/wp-content/themes/twentyeleven/author.php	Adds missing hook parameter variable name.
src/wp-admin/plugins.php	Passes documented activation hook argument.
src/wp-admin/plugin-install.php	Adds file-scope globals and passes paged argument.
src/wp-admin/network/users.php	Passes documented network bulk action site ID placeholder.
src/wp-admin/network/themes.php	Passes documented network bulk action site ID placeholder.
src/wp-admin/includes/nav-menu.php	Passes documented menu data argument.
src/wp-admin/includes/file.php	Passes final request URL to SSL verification filter.
src/wp-admin/includes/class-wp-site-health.php	Passes request URLs to SSL verification filter.
src/wp-admin/includes/class-wp-automatic-updater.php	Passes loopback URL to SSL verification filter.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[westonruter]

cc @szepeviktor @apermo

[szepeviktor]

What an ocean of bugs revealed!

[westonruter]

From Claude Opus 5 (1M context), via Claude Code, at @westonruter's request. Follow-up to my review comment, which still reads as though its findings were open. Every finding in it has now been addressed on the branch, each change directed and reviewed by @westonruter. Commit subjects are given rather than SHAs, since the commits are not pushed as of this comment and may be rebased.

Every finding from the review is addressed

#	Finding	Resolution
1	Loose dynamic hook patterns satisfied the doc rule	Require a specific anchor to resolve a hook doc reference. A pattern anchored only on separators is no longer honored, and among matching patterns the most specifically anchored wins.
2	Cross-file docblock reads bypassed the dependency graph	Invalidate cached results when inherited hook docs change. A ResultCacheMetaExtension folds the inheritable hook docblocks, and the tooling's own sources, into the result cache key.
3	An attribute was written to every AST node	Record hook docblocks only where they are read. Written on function calls only, and only when a docblock applies: 543,762 nodes carrying it across src/wp-includes/*.php became 2,511, and ~21.5 MB of retained attributes is no longer measurable.
4	Non-hook docblocks counted as hook documentation	Require a filter's docblock to document the filtered value. A filter always passes the value being filtered, so a filter documented with no @param is reported as undocumented rather than compared against a count of zero.
5	getParamTags() is keyed by parameter name	Count every documented hook parameter, including repeated names. Counted from the parsed docblock nodes, which list every tag.
6	Duplicated resolution flows	Resolve a hook's documentation in one place. One getHookDoc() replaces five overlapping methods; each rule resolves once instead of two or three times. Net 67 lines removed.
7	resolveReferencePath() walked to the filesystem root	Stop resolving a hook doc reference outside the analyzed tree, then Confine a resolved hook doc reference to the analyzed tree. The walk stops at the WordPress root, and a candidate is canonicalized and accepted only when it resolves inside the tree.

The nits are addressed too: the unset() calls and the foreach that returned on its first iteration are gone, the two rules' @param tags are aligned, every service in base.neon now has a comment describing what it actually is, the adapted files credit szepeviktor/phpstan-wordpress with @link, name its MIT license and pin the upstream commit, and tests/phpstan/README.md now documents the extensions and all five error identifiers they report.

Four things turned out worse than the review described

Each of these was demonstrated rather than reasoned about, and each was a real defect rather than the theoretical one I had written up:

• Finding 1 was a false negative, not just imprecision. A reference comment naming a hook that taxonomy.php does not document produced no hookDocReferenceHookMissing at all, because "{$taxonomy}_{$field}" compiles to #^.+_.+$# and matched it — so the rule silently accepted a broken reference and then reported an argument count borrowed from an unrelated hook. Whether a bad reference was caught came down to whether the hook name happened to contain an underscore.
• Finding 5 also hid genuine mismatches. I had described the name collapse as producing false positives. It does, but it also suppresses real errors: a hook documenting two @param tags that share a name and passing one argument matched a collapsed count of one, and was reported as correct.
• Finding 7 was not merely wasted is_file() calls. With a file present above the tree, resolution reached it and used its docblock to document, type and count the hook — so a broken reference went unreported because something unrelated answered to the same relative path.
• Finding 2 extended to the tooling itself. PHPStan hashes its configuration but not extension logic, so editing a rule left the results that rule had already produced in the cache. The same metadata extension now covers both.

What is deliberately not changed

• src/wp-includes/build stays excluded from analysis. The code is generated from Gutenberg rather than authored here, so the fix belongs upstream, as with src/wp-includes/blocks.
• The return type extension still reads the first entry of getParamTags(). With two @param tags sharing a name, a later tag's type can displace the first. Resolving it properly needs TypeNodeResolver and a NameScope, and finding 5 makes the situation loud rather than silent: duplicates now count as two, so the call is reported.
• Tests remain a follow-up, for the reasons in the previous comment.
• PHPStan\Cache\Cache was tried and reverted. Persisting parsed docblocks across runs took a warm run from 1.86 s to 1.28 s, but PHPStan reports both calls as outside its backward compatibility promise, which would have required ignore entries in the shared base.neon. Not worth pinning core tooling to PHPStan internals for 0.6 s.

One cost this introduces

The result cache metadata added for finding 2 costs about 1.2 s per run — roughly 0.25 s to scan the tree for reference comments, and 1 s to parse the 145 files they name. That is noise against a cold run of the full analysis, but it is most of the cost of an otherwise near-instant warm run. The alternatives are worse: hashing file contents rather than parsed docblocks would flush the whole cache whenever a frequently-referenced file like post.php is edited at all.

Verification

Repeated after each change:

• The CI configuration (phpstan.neon.dist, level 0 with the baseline and reportUnmatchedIgnoredErrors) reports no errors from a cold cache, in an isolated cache directory so a warm cache cannot mask a finding.
• Level 10 with bleedingEdge over tests/phpstan/ is clean.
• All 712 reference sites in the analyzed tree still resolve, through the same 19 dynamic patterns and to the same docblocks as before.
• Four rule fixtures covering missing documentation, both broken-reference forms, _ref_array counting, argument spreads of unknown size, @var above a filter and repeated @param names produce byte-identical output across the refactors.
• Filter return types were re-checked with PHPStan\dumpType() for inline, inherited, unresolvable, zero-parameter and multi-parameter docblocks, since the rule fixtures do not cover the return type extension.
• Each finding's fix was confirmed against a reproduction that failed before it and passes after, including a warm-cache versus cold-cache comparison for finding 2.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

tests/phpstan/README.md:65

• The README describes the reference-comment convention as only "This filter is documented in ", but the tooling and regex also support action references ("This action is documented in "). Updating the wording here avoids misleading users about which reference forms are accepted.

- **Hooks documented elsewhere are resolved.** Core's `/** This filter is documented in <file> */` convention is followed, so a hook documented in another file is analyzed against its canonical docblock. A dynamic canonical name such as `"{$type}_template_hierarchy"` is matched against the literal name used at the referencing site.

tests/phpstan/HookDocBlock.php:256

• getReferencedHookDocsHash() scans all PHP files under wp-includes, which includes large generated trees that are excluded from PHPStan analysis (e.g. wp-includes/blocks and wp-includes/build). Skipping those paths here avoids reading/parsing large generated files when building the cache meta hash, improving PHPStan performance without affecting reference-comment resolution.

			$iterator = new RecursiveIteratorIterator(
				new RecursiveDirectoryIterator( $path, FilesystemIterator::SKIP_DOTS )
			);

			foreach ( $iterator as $file ) {

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

tests/phpstan/HookDocumentationRule.php:104

• The wordpress.hookDocMissing error message doesn’t identify which hook is missing documentation. Including the (literal) hook name when available makes the report more actionable and aligns it with the other hook-documentation errors that include the hook name.

				RuleErrorBuilder::message(
					sprintf(
						'%s() call is not preceded by a docblock documenting the hook, nor by a "This filter/action is documented in <file>" reference comment.',
						$function_name
					)
				)

tests/phpstan/HookParamCountRule.php:125

• HookParamCountRule skips count checks for filters whose inline docblock has zero @param tags (because HookDocumentationRule reports that as wordpress.hookDocNoParams). But for filters documented via a reference comment, a canonical docblock with zero @param tags will still be treated as paramCount = 0 and this rule will report wordpress.hookParamCountMismatch at every referencing call site, duplicating the canonical error. Referencing sites should also skip param-count comparison in this specific case so the missing-@param problem is reported only where the canonical docblock lives.

		// A filter whose docblock documents no parameters is not documented at all,
		// which HookDocumentationRule reports. Comparing counts as well would report
		// one defect twice.
		if ( HookDocBlock::isFilterMissingParamDocs( $node, $hook_doc ) ) {
			return array();
		}

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (2)

tests/phpstan/HookDocBlock.php:798

• str_starts_with() is PHP 8+ only, which will fatal on PHP 7.4. Replace with a PHP 7.4-compatible prefix check in this loop condition.

		while ( $dir === $this->wordpressRoot || str_starts_with( $dir, $this->wordpressRoot . '/' ) ) {

tests/phpstan/HookDocBlock.php:844

• str_starts_with() is PHP 8+ only, which will fatal on PHP 7.4. Use a PHP 7.4-compatible prefix check when verifying the resolved path is inside the WordPress root.

		return str_starts_with( $canonical, $this->canonicalWordpressRoot . '/' ) ? $canonical : null;

[westonruter]

From Claude Opus 5 (1M context), via Claude Code, at @westonruter's request.

Checked this, and it does not fatal under PHP 7.4 — though only because of where this code runs, which is worth recording.

These classes are loaded exclusively inside PHPStan's own process, as services declared in tests/phpstan/base.neon. The pinned phpstan/phpstan 2.2.5 phar bundles symfony/polyfill-php80 and loads it through Composer's file autoloading:

vendor/composer/autoload_files.php (inside phpstan.phar)
  'a4a119a56e50fbb293281d9a48007e0e' => $vendorDir . '/symfony/polyfill-php80/bootstrap.php',

vendor/symfony/polyfill-php80/bootstrap.php
  if (\PHP_VERSION_ID >= 80000) { return; }
  …
  if (!function_exists('str_contains'))    { function str_contains(…)    { … } }
  if (!function_exists('str_starts_with')) { function str_starts_with(…) { … } }
  if (!function_exists('str_ends_with'))   { function str_ends_with(…)   { … } }

So the chain under composer phpstan is: vendor/bin/phpstan → the phar stub's require 'phar://phpstan.phar/bin/phpstan' → autoload_real.php runs its file-autoload loop → the polyfill defines those three functions globally whenever PHP_VERSION_ID < 80000 → PHPStan then instantiates these extension classes. That is also how PHPStan itself manages to require PHP 7.4+ while using these functions throughout its own source.

A caveat on the strength of that evidence: it is a verified code path rather than an executed one. Only PHP 8.2 through 8.5 were available where I checked, so I could not run the analysis under 7.4 end to end. What I did confirm is the polyfill's presence in the pinned phar, its PHP_VERSION_ID guard, its registration in autoload_files.php, and the loader that consumes that list.

There is one real limitation in the neighborhood of this concern, which is narrower than the comment but true: the guarantee holds only inside PHPStan's process. A script that requires these files directly — an ad hoc harness, for instance — would fatal on 7.4, since nothing polyfills there. Anything that loads these classes outside PHPStan needs its own polyfill, or PHP 8.

No change here, then. Reverting to strpos() would trade readability for a fatal that cannot occur in the only context this code runs in.

[westonruter]

From Claude Opus 5 (1M context), via Claude Code, at @westonruter's request.

Same answer as for str_contains() above: the pinned phpstan/phpstan 2.2.5 phar loads symfony/polyfill-php80 through Composer's file autoloading, which defines str_starts_with() globally whenever PHP_VERSION_ID < 80000, and these classes only ever run inside PHPStan's process. That covers the two further occurrences noted here as well, in resolveReferencePath() and resolveWithinRoot().

One detail specific to this line: the prefix test is also what lets the substr() after it stay clean at level 10. Under the configured PHP 7.4 floor substr() is typed string|false, since the offset may exceed the subject's length, so returning it unguarded from a method declared : string is a return.type error. Testing the prefix first narrows the offset enough for PHPStan to rule false out — and to be fair to the suggestion, I checked, and 0 === strpos( $path, $prefix ) narrows it identically. So that is not an argument against the rewrite; the reason to keep str_starts_with() here is simply that it reads as what it is.

[github-actions]

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 62939
GitHub commit: 7404a51

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.