[huzaifaalmesbah]

What?

See #86088

Fixes return types and docblocks in WP_Theme_JSON_Gutenberg and WP_Duotone_Gutenberg reported by PHPStan, and removes the resolved entries from the PHPStan baseline. It also applies the array shape for block type selectors that was added to WordPress Core in r65318 (Core-65817, WordPress/wordpress-develop#15644).

Why?

Three of these are already fixed in WordPress Core, so the Gutenberg classes were out of sync. The fourth is in a deprecated, Gutenberg-only method. This resolves 4 of the 226 errors initially baselined in #66693.

How?

• WP_Theme_JSON_Gutenberg::get_block_name_from_metadata_path() fell off the end without a return value when there was no path. It now returns $block_metadata['path'][2] ?? null, matching Core. (return.missing)
• WP_Theme_JSON_Gutenberg::get_block_selectors() documented its $block_type parameter as object, but it is only called with block types from the registry and passes them to wp_get_block_css_selector(), so it is now documented as WP_Block_Type, matching Core.
• The deprecated, Gutenberg-only WP_Theme_JSON_Gutenberg::get_block_custom_css() documented $css as array, but passes it to process_blocks_custom_css(), which expects a string. It is now documented as string. (argument.type)
• WP_Duotone_Gutenberg::get_all_global_style_block_names() never returns null, so its @return is now array<string, string>, keyed by block name. (return.unusedType) This is more precise than Core's string[], so it can be synced to Core later.
• Removed the 4 corresponding entries from tools/phpstan/baseline.neon.

The block type selectors shape from Core is applied wherever Gutenberg passes the selectors along, matching Core's docblocks: the return value of WP_Theme_JSON_Gutenberg::get_block_selectors(), the selectors key of get_feature_declarations_for_node()'s $metadata, and the parameters of gutenberg_get_state_style_groups(). As in Core, get_block_selectors() now prepends the root selector to the default feature selectors, so that a feature named root cannot replace the root selector string with an array.

The docblock of the Gutenberg-only $feature_selectors and $feature_declarations parameters of WP_Theme_JSON_Gutenberg::get_state_declarations_with_text_clip_escapes() now follows Core's layout, with the declaration list shapes that Core documents. Those need the names of the escape declarations to be non-empty strings, so gutenberg_get_state_text_clip_escape() and gutenberg_get_state_text_fill_reset() now document the exact declaration each returns, such as array{ 'background-image'?: 'unset' }. This is more precise than the array<non-falsy-string, non-falsy-string> that Core has on them, so it can be synced to Core later.

The WordPress stubs for PHPStan are generated from Core trunk at r65318, so that the analysis knows the type of WP_Block_Type::$selectors.

The method.childParameterType error for WP_REST_Global_Styles_Controller_Gutenberg::prepare_links() is left as it is: Core has the same code and keeps the same entry in its baseline, and fixing it would change the method signature.

There is no change in behavior.

Testing Instructions

1. Run composer phpstan and confirm it passes with no unmatched ignored errors.
2. Run composer phpstan:baselines and confirm tools/phpstan/baseline.neon has no further changes.
3. Run the theme.json, block state, and duotone PHP unit tests: npm run test:unit:php -- -- --filter "WP_Theme_JSON|States|Duotone".

Testing Instructions for Keyboard

Not applicable. There are no UI changes.

Screenshots or screencast

Not applicable.

Use of AI Tools

I used Claude Code to identify the affected occurrences and draft the change. I reviewed the diff and take responsibility for it.

Additional changes were made by @westonruter using Claude Code with Claude Opus 5.5 (medium effort): the block type selectors shape, the matching Core docblocks, and the stubs update.

[github-actions]

🤖 PR meta 🤖

🎉 Props

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: huzaifaalmesbah <huzaifaalmesbah@git.wordpress.org>
Co-authored-by: westonruter <westonruter@git.wordpress.org>
Co-authored-by: noruzzamans <noruzzaman@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

---

Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

• @propsbot add <username> to give props to a GitHub user. Requires write access.
• @propsbot remove <username> to leave a user out of the props. Requires write access.
• @propsbot refresh to refresh this list. Adding the props-bot label works too.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

[noruzzamans]

I had opened #86107 for the Duotone return type fix before spotting it here. I've closed #86107 in favor of this PR. Nice work!

[Copilot]

🟢 Approval recommended

No active review issues remain, with the documented annotation, stub, and baseline updates addressing the identified changes.

No open issues 🎉

What changed in this PR

This pull request aligns Gutenberg’s Theme JSON, duotone, and block-state PHPStan annotations with WordPress Core, updates the generated stubs to revision r65318, and removes four resolved baseline suppressions.

Changes:

• Corrects return types and parameter documentation in Theme JSON and duotone code.
• Applies precise block-selector and state-declaration array shapes.
• Preserves root-selector precedence when constructing default selectors.
• Updates WordPress stubs and removes resolved PHPStan baseline entries.
• Review note: add focused tests covering root-first selector construction and subclass selector-key collisions.

File	Description
tools/​phpstan/​wordpress-stubs/​composer.json	Updates the generated WordPress stubs source revision to r65318.
tools/​phpstan/​baseline.neon	Removes the four resolved PHPStan suppressions while retaining unrelated ignores.
lib/​class-wp-theme-json-gutenberg.php	Corrects Theme JSON documentation, return handling, selector shapes, and root-selector handling.
lib/​class-wp-duotone-gutenberg.php	Corrects the global style block names return documentation.
lib/​block-supports/​states.php	Adds precise selector and state-declaration annotations.

_{Review effort: Lite}