Repository navigation
Options, Meta APIs: Document register_setting() $args as array|callable. - #14137
jorgefilipecosta wants to merge 4 commits into
Conversation
…tting()` arguments. The theme passed its validation callback as the third argument of register_setting(), the signature from before WordPress 4.7, which the function still accepts for backward compatibility. PHPStan reports the call against the documented `$args` array, and the report was baselined. Register the setting without a callback and attach twentyeleven_theme_options_validate() to the option's sanitize filter, which is what register_setting() does with its `sanitize_callback` argument. The `$args` array only exists since 4.7 and the theme supports earlier versions, so this keeps the registration working on both. Remove the matching PHPStan baseline entry.
|
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. |
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. |
…allable`. `register_setting()` still accepts a sanitize callback as its third argument for backward compatibility, converting it into the `sanitize_callback` arg. Documenting `$args` as only `array` made PHPStan flag callers that pass a callback, such as Twenty Eleven and the deprecated `add_option_update_handler()`, even though the call is supported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ting()`. This reverts the theme change from cf8ceea. Now that `register_setting()` documents a callable `$args`, the original call no longer trips PHPStan. Attaching the validator with `add_filter()` instead hid it from the Settings API: it no longer showed as the setting's `sanitize_callback` and `unregister_setting()` no longer removed it, a behavior change for child themes that replace the setting. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
westonruter
changed the title
register_setting() arguments.register_setting() $args as array|callable.
westonruter
left a comment
westonruter
left a comment
There was a problem hiding this comment.
🤖 Comment by Claude Opus 5.5
The approach of this PR has been changed. Instead of changing Twenty Eleven, the register_setting() docblock is corrected.
What was changed
- dc4056e documents the
$argsparam ofregister_setting()asarray|callable. A note says a callable is accepted for backward compatibility and is used as the$sanitize_callback. The documented$argskeys are unchanged, so array arguments are still checked against them. - 2cfd72b restores Twenty Eleven's original
register_setting()call, reverting the theme part of cf8ceea. The removal of the PHPStan baseline entry is kept, since the call is no longer reported.
Why
The PHPStan error was a false positive caused by the docblock, not a bug in the theme. register_setting() still supports a callable third argument through its back-compat branch, which turns it into sanitize_callback, and it raises no deprecation notice.
Attaching the validator with add_filter( 'sanitize_option_twentyeleven_theme_options', … ) instead also changed runtime behavior:
unregister_setting()only removes the registeredsanitize_callback, so the validator would stay attached after a child theme unregisters the setting and registers its own.get_registered_settings()and theregister_setting_argsfilter would report anullsanitize_callbackfor the setting, so plugins could no longer see or replace the validator.
The callable form is also in wide use across the WordPress.org directories. A search with Veloria, which indexes every WordPress.org plugin and theme, found:
| Form of the third argument | Plugins | Themes |
|---|---|---|
Function name as a string, e.g. 'absint' |
8,745 matches in 2,403 plugins | 373 matches in 215 themes |
Array callable, e.g. array( $this, 'validate' ) |
4,617 matches in 2,840 plugins | 89 matches in 85 themes |
These are lower bounds, since the search only matched single-line calls with a literal callback. Examples include UpdraftPlus (4M installs), Jetpack, WPS Hide Login, EWWW Image Optimizer, MC4WP, Safe SVG, WP Fastest Cache, and BuddyPress. Twenty Fourteen, another bundled theme, does the same in inc/featured-content.php: register_setting( 'featured-content', 'featured-content', array( __CLASS__, 'validate_settings' ) ).
With this much use, fixing the type at its source corrects static analysis for every caller, including the deprecated add_option_update_handler() in core, with no behavior change. Changing callers one at a time would not.
For backward compatibility, `register_setting()` still accepts a sanitize callback as its third argument, converting it into the `sanitize_callback` argument without a deprecation notice. Its docblock documented `$args` only as an array, so once PHPStan began reading the hash notation in r63420, callers passing a callback were reported, such as Twenty Eleven and the deprecated `add_option_update_handler()`. This form remains in wide use across thousands of plugins and themes in the theme & plugin directories. Developed in #14137. Follow-up to r38635, r63420. Props jorgefilipecosta, westonruter. See #65817, #65860. git-svn-id: https://develop.svn.wordpress.org/trunk@64670 602fd350-edb4-49c9-b593-d223f7449a82
For backward compatibility, `register_setting()` still accepts a sanitize callback as its third argument, converting it into the `sanitize_callback` argument without a deprecation notice. Its docblock documented `$args` only as an array, so once PHPStan began reading the hash notation in r63420, callers passing a callback were reported, such as Twenty Eleven and the deprecated `add_option_update_handler()`. This form remains in wide use across thousands of plugins and themes in the theme & plugin directories. Developed in WordPress/wordpress-develop#14137. Follow-up to r38635, r63420. Props jorgefilipecosta, westonruter. See #65817, #65860. Built from https://develop.svn.wordpress.org/trunk@64670 git-svn-id: http://core.svn.wordpress.org/trunk@63820 1a063a9b-81f0-0310-95a4-ce76da25c4cd
✅ Committed in r64670 (ff2a71f).
What
Follow up to #12141 (comment).
register_setting()still accepts a sanitize callback as its third argument. Its back-compat branch converts the callable into thesanitize_callbackarg, and there is no deprecation notice. But its docblock types$argsasarrayonly, so PHPStan reports callers that pass a callback, such as Twenty Eleven'stwentyeleven_theme_options_init(). That report sits in the PHPStan baseline.$argsparam ofregister_setting()is now documented asarray|callable, with a note that a callable is accepted for backward compatibility and is used as the$sanitize_callback. The documented$argskeys are unchanged, so callers passing an array are still checked against them.sanitize_callback. It still shows up inget_registered_settings()and theregister_setting_argsfilter, andunregister_setting()still removes it.tests/phpstan/baselines/argument.type.neon.Testing
Verify PHPStan reports no
register_setting()error for callers that pass a callback:Trac ticket: https://core.trac.wordpress.org/ticket/65817
Use of AI Tools
AI assistance: Yes
Tool(s): Claude Code (Claude Opus 5.5)
Used for: drafting the change and this description, and revising the approach after code review.
🤖 Generated with Claude Code