Accept non-string scalars in the esc_*() escaping functions

[westonruter]

✅ Committed in r63296 (abc50fe).

---

Widens the @param annotation on the esc_*() escaping functions from string to string|int|float, and adds an explicit (string) cast to each.

This clears 54 baseline entries covering 101 errors from tests/phpstan/baselines/argument.type.neon. esc_attr() alone accounted for 94 of them — the largest single cluster in that file.

Background

esc_attr(), esc_html(), esc_js(), esc_textarea(), and esc_xml() were all annotated @param string $text, but none of them has ever required a string at runtime. The two helpers they delegate to each open by coercing:

• _wp_specialchars() — $text = (string) $text;
• wp_check_invalid_utf8() — the same

Tracing that cast back through r11380 (which deprecated wp_specialchars() in favour of esc_html()) to r10298 puts it in 2009. Since esc_attr() and esc_html() are @since 2.8.0, also 2009, the coercion is as old as the functions themselves. Only the annotation ever claimed otherwise — which is why passing an int, overwhelmingly a post ID, a term ID, or a count, has always worked while still registering as a static analysis error.

Confirmed against the current codebase (PHP 8.5):

input	esc_attr()	esc_html()	esc_js()	esc_textarea()
42	'42'	'42'	'42'	'42'
-7	'-7'	'-7'	'-7'	'-7'
1.5	'1.5'	'1.5'	'1.5'	'1.5'
true	'1'	'1'	'1'	'1'
false	''	''	''	''

Why the cast is not redundant

For esc_attr(), esc_html(), and esc_js() the value is already coerced downstream, so the new cast does not change what gets escaped. What it does change is the second argument handed to the attribute_escape, esc_html, and js_escape filters. Each is documented as @param string $text The text prior to being escaped, but callbacks previously received the raw int or float. The cast makes that documented contract true.

esc_textarea() is the one case where the cast also affects escaping: it passed $text straight to htmlspecialchars(), so esc_textarea( null ) emitted a PHP 8.1+ deprecation. That no longer happens.

Why bool is excluded

bool is accepted at runtime, and the cast handles it, but it is deliberately left out of the annotation. Casting true yields '1' while false yields '', and an empty string is indistinguishable from a missing value, an empty option, or a failed lookup in any output context. There is no output context where '' is a meaningful rendering of false.

Core has exactly two call sites passing a bool, and they split evenly:

• wp-admin/options-general.php:193 — data-state="<?php echo esc_attr( has_site_icon() ); ?>". This works, because site-icon.js compares against the literal '1' and writes back '1'/''. The convention is real but implicit.
• wp-admin/customize.php:291 — aria-pressed="<?php echo esc_attr( $active ); ?>". This renders aria-pressed="1" for the desktop button and aria-pressed="" for tablet and mobile. Valid ARIA tristate values are only "true", "false", "mixed", and "undefined", so all three buttons are exposed as non-toggles until controls.js (which correctly writes "true"/"false") runs.

Admitting bool to the signature would permanently silence the second one. Both stay baselined instead, so they remain visible as outstanding work. The accessibility fix is intentionally not in this PR and will be handled separately.

Scope

esc_textarea() and esc_xml() had no baselined errors and are included only to keep the family consistent — five functions with identical semantics should not carry three different parameter annotations.

Call sites are not touched. Nothing here changes escaping behaviour for any input that was already a string.

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
Used for: Investigating the runtime coercion behaviour and its history, the docblock and cast changes, regenerating the baselines, and drafting this description. The decision to exclude bool and to defer the accessibility fix was mine, as was review of the result.

---

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.

[github-actions]

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 props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props westonruter.

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

[github-actions]

Test using WordPress Playground

The 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

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.