Docs: Require view config filter callbacks to return the container#12641
Docs: Require view config filter callbacks to return the container#12641jorgefilipecosta wants to merge 1 commit into
Conversation
The `get_entity_view_config_{$kind}_{$name}` filter docblock advised
callbacks not to return the container, but as with any filter each
callback's return value is passed to the next callback, so a callback
that returns nothing hands `null` to callbacks hooked at later
priorities. Document the standard filter contract instead, noting that
the write methods return the container for chaining. Also fixes a
doubled word.
See #65577.
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the Core Committers: Use this line as a base for the props when committing in SVN: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
There was a problem hiding this comment.
Pull request overview
Updates the inline documentation for the get_entity_view_config_{$kind}_{$name} filter to reflect WordPress’s standard filter contract: each callback must return the (possibly mutated) value so subsequent callbacks receive the expected container object, preventing null from being passed down the filter chain.
Changes:
- Corrects the filter docblock to require callbacks to return the
WP_View_Config_Datacontainer they receive (since each return value is forwarded to the next callback). - Adds a concrete example showing callbacks can return the container directly from a write method (e.g.
return $data->merge( $patch, $version );). - Fixes a duplicated “the” in the same paragraph.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Test using WordPress PlaygroundThe 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
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
What
Corrects the
get_entity_view_config_{$kind}_{$name}filter docblock: callbacks must return the container they receive. Also fixes a doubled "the" in the same paragraph.Follow-up to #12638.
Why
The docblock told callbacks the container is mutated in place, so there is "no need to return it; any returned value is ignored". Only the final return is discarded: as with any filter,
WP_Hook::apply_filters()passes each callback's return value to the next callback as$data, so a callback that follows that advice handsnullto every callback hooked at a later priority, which fatals the moment it calls a method on it (Call to a member function merge() on null). A single callback never surfaces this, so it would only show up in the wild once two plugins hook the same filter.Docs-only; the dispatch is unchanged. The new text states the standard filter rule and points out that the write methods return the container, so a callback can end with
return $data->merge( $patch, $version );. The existing filter tests already register callbacks that return the container.AI usage disclosure
AI assistance: Yes
Tool(s): Claude Code
Model(s): Opus
Used for: PR description and code comment. Manually verified and tuned.
Trac ticket: https://core.trac.wordpress.org/ticket/65577