Repository navigation
Add support for tracking WordPress array parameter keys - #26
Merged
johnbillion merged 8 commits intoOct 9, 2026
Merged
johnbillion merged 8 commits into
johnbillion merged 8 commits into
Conversation
WordPress documents the elements of an array shaped parameter with the hash notation, so the generator can collect those keys along with their nesting and then attribute the `@since` changelog entries of the symbol to them. A key is only recorded when the changelog entry describes it as being added, and only when it postdates both the symbol and the parameter that holds it. Entries which merely describe a change to an existing key, such as "Added support for `$operator`", are ignored, as are keys which share their name with a parameter of the same symbol because those are already handled as parameters. Co-authored-by: Pascal Birchler <[email protected]> Co-Authored-By: Claude <[email protected]> Claude-Session: https://claude.ai/code/session_01JZCYw6juqn1GruS2o7Exmr
An argument which is an array is checked against the keys recorded for its parameter, so passing an element which WordPress only understands from a later version triggers an error. Nested keys are supported too, which is how the `meta` argument of the Abilities API is documented. Only keys which PHPStan knows are present get reported, so an array which is assembled conditionally doesn't trigger an error. Co-authored-by: Pascal Birchler <[email protected]> Co-Authored-By: Claude <[email protected]> Claude-Session: https://claude.ai/code/session_01JZCYw6juqn1GruS2o7Exmr
Adds the array keys of 41 parameters, covering registration APIs such as register_post_type(), register_taxonomy(), register_meta(), register_setting() and register_sidebar(), as well as WP_Query, WP_Block_Type, and a number of template functions. Co-authored-by: Pascal Birchler <[email protected]> Co-Authored-By: Claude <[email protected]> Claude-Session: https://claude.ai/code/session_01JZCYw6juqn1GruS2o7Exmr
getParametersSinceFromDoc() and getParameterKeysSinceFromDoc() both matched the @SInCE tags, mapped the MU version, validated the version format and discarded the entries which predate the symbol. getSinceEntriesFromDoc() now does that once and hands back the version and description of each entry, leaving the two callers to do only their own attribution. Regenerating the symbols against WordPress 7.1 produces an identical file. Co-authored-by: Pascal Birchler <[email protected]> Co-Authored-By: Claude <[email protected]> Claude-Session: https://claude.ai/code/session_01JZCYw6juqn1GruS2o7Exmr
The symbol extraction has moved out of generate.php and into SymbolExtractor, so generate.php and symbols.json are resolved in favour of trunk. The array key extraction they carried needs reapplying to the extractor.
Owner
|
Neat, thanks. I reworked this a bit because in the main branch I extracted the symbols.json generation to make it testable. |
…sn't matter. We'll get the bots to do it.
Contributor
Author
|
Awesome, thank you! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR extends WPCompat to track and validate the introduction versions of array keys within function and method parameters. Previously, the extension only checked if parameters themselves were available in the target WordPress version. Now it also validates that specific array keys used within those parameters were introduced before the minimum supported version.
Key Changes
getHashNotationKeys()function to parse WordPress's hash notation documentation format and extract array keys from@paramblocksgetParameterKeysSinceFromDoc()to identify which array keys were introduced in specific WordPress versions by analyzing@sincechangelog entriesSinceVersionRuleto detect when array keys are used and report errors if they were introduced after the minimum versionhasArrayKeyPath()method to determine if a given key path exists in an array argument using PHPStan's type analysissymbols.jsonschema to support optionalkeysproperty on parameters, allowing documentation of per-key version informationsymbols.jsonwith version information for array keys across 40+ WordPress functions and methods (e.g.,register_meta(),wp_get_attachment_image(),WP_Theme_JSON::get_stylesheet())Implementation Details
@typetagsoptions.skip_root_layout_styles)https://claude.ai/code/session_01JZCYw6juqn1GruS2o7Exmr