Formatting: Document sanitize_key() as accepting mixed - #14759

✅ Committed in r64682 (eaa3b6b).

This widens the documented type of sanitize_key()'s $key parameter from string to mixed, which resolves 50 PHPStan errors at rule level 10 without introducing any.

Background

The sanitize_key() function was documented as taking a string, but it has accepted any value since r52292 (Core-54160) added a type guard to fix a PHP warning when an array was passed. Changeset r52370 then switched that guard from is_string() to is_scalar() so that non-string scalars keep being coerced to a string by strtolower(), as they always had been. The existing tests lock this behavior in:

• 0 → '0', true → '1', false → '', 0.123 → '0123'
• an array, null, or an object → ''

So the function is total over mixed, and that matches how it is used. Of its ~75 call sites in core, most pass raw request data ($_POST, $_GET, $_REQUEST, often through wp_unslash()), and it is also used as a REST sanitize_callback, as an array_map() callback, and as a pre_post_* filter callback. In all of these the value can be of any type, such as an array from ?post_type[]=x.

PHPStan errors resolved

At level 10 (the local phpstan.neon), trunk reports:

• 47 × argument.type: Parameter #1 $key of function sanitize_key expects string, mixed given. across 19 files.
• 2 × argument.type in WP_Query::parse_query(): Parameter #1 $callback of function array_map expects (callable(mixed): mixed)|null, 'sanitize_key' given.
• 1 × return.type in sanitize_key() itself: Function sanitize_key() should return lowercase-string but returns string. The apply_filters() return type extension reads the type of the filter's first @param, which was string.

A full run goes from 27,467 to 27,417 errors, with no new errors. No baselines change, since none of these errors are baselined at level 5, and phpstan.neon.dist still reports no errors.

Alternative considered: scalar

Widening to scalar (documented as string|int|float|bool plus @phpstan-param scalar) was tried first. It fixes only the return.type error: every call site still passes mixed, which scalar does not accept either, and the strtolower() call gains a new error for bool|float|int|string. Making the call sites pass scalar would mean adding an is_scalar() check before each one, duplicating the check the function already does.

Changes

• $key is documented as mixed in the function and in the sanitize_key filter, since the filter receives the original, unsanitized value.
• Scalars are cast to string explicitly before strtolower(). This preserves the prior implicit coercion.
• The filter gets @phpstan-param lowercase-string $sanitized_key, so that apply_filters() agrees with the function's existing @phpstan-return lowercase-string.
• The nonstring_scalar data provider and its test are renamed to non_string, since the provider now covers non-scalar types too.
• Test cases are added for a negative integer, a float in scientific notation (1.0E+25 → '10e25', which exercises lowercasing after the cast), INF (→ 'inf'), an array, an object, null, a stringable object, and a closure. A stringable object still yields '', because the guard is is_scalar().
• A test is added for the arguments passed to the sanitize_key filter, using the same non-string cases.

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

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: Analyzing the call sites and PHPStan errors, prototyping the scalar and mixed alternatives, writing the change and tests, and drafting this description. Reviewed by me.

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

🤖 Generated with Claude Code