Skip to content

Commit abc50fe

Browse files
westonruterwestonruter
committed
Formatting: Document that escaping functions can take numbers.
The `esc_attr()`, `esc_html()`, `esc_js()`, `esc_textarea()`, and `esc_xml()` functions were each annotated `@param string $text`, but none of them has ever required a string at runtime. Both `wp_check_invalid_utf8()` and `_wp_specialchars()` open by casting to string, and that coercion dates to r10298 and r11380, the same year `esc_attr()` and `esc_html()` were introduced in 2.8.0. Only the annotation ever claimed otherwise, which is why passing an integer, overwhelmingly a post ID, a term ID, or a count, has always worked while still registering as a static analysis error. Widen the annotation to `string|int|float` and cast at the top of each function. That cast is not redundant with the ones downstream: it is what makes the `$text` argument handed to the `attribute_escape`, `esc_html`, and `js_escape` filters match its documented `string` type, where callbacks previously received the raw integer or float. For `esc_textarea()` it also affects the output, since that function passed `$text` straight to `htmlspecialchars()`, so `esc_textarea( null )` emitted a deprecation notice on PHP 8.1 and later. The `bool` type is deliberately excluded. Casting `true` yields `'1'` while `false` yields the empty string, and an empty string is indistinguishable from a missing value in any output context. The two call sites in core which pass one stay baselined rather than being permitted by the signature; one of the two is an a11y defect being addressed separately. Regenerating the baselines drops 54 entries covering 101 errors from `tests/phpstan/baselines/argument.type.neon`, where `esc_attr()` was the largest single cluster. Developed in WordPress#13044. Follow-up to r11380, r63024. See #65817. git-svn-id: https://develop.svn.wordpress.org/trunk@63296 602fd350-edb4-49c9-b593-d223f7449a82
1 parent 5a96e2a commit abc50fe

2 files changed

Lines changed: 17 additions & 277 deletions

File tree

‎src/wp-includes/formatting.php‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4716,11 +4716,13 @@ function htmlentities2( $text ) {
47164716
* be in single quotes. The {@see 'js_escape'} filter is also applied here.
47174717
*
47184718
* @since 2.8.0
4719+
* @since 7.2.0 Non-string scalars are cast to string before escaping.
47194720
*
4720-
* @param string $text The text to be escaped.
4721+
* @param string|int|float $text The text to be escaped.
47214722
* @return string Escaped text.
47224723
*/
47234724
function esc_js( $text ) {
4725+
$text = (string) $text;
47244726
$safe_text = wp_check_invalid_utf8( $text );
47254727
$safe_text = _wp_specialchars( $safe_text, ENT_COMPAT );
47264728
$safe_text = preg_replace( '/&#(x)?0*(?(1)27|39);?/i', "'", stripslashes( $safe_text ) );
@@ -4744,11 +4746,13 @@ function esc_js( $text ) {
47444746
* Escaping for HTML blocks.
47454747
*
47464748
* @since 2.8.0
4749+
* @since 7.2.0 Non-string scalars are cast to string before escaping.
47474750
*
4748-
* @param string $text
4751+
* @param string|int|float $text The text to be escaped.
47494752
* @return string Escaped text.
47504753
*/
47514754
function esc_html( $text ) {
4755+
$text = (string) $text;
47524756
$safe_text = wp_check_invalid_utf8( $text );
47534757
$safe_text = _wp_specialchars( $safe_text, ENT_QUOTES );
47544758
/**
@@ -4769,11 +4773,13 @@ function esc_html( $text ) {
47694773
* Escaping for HTML attributes.
47704774
*
47714775
* @since 2.8.0
4776+
* @since 7.2.0 Non-string scalars are cast to string before escaping.
47724777
*
4773-
* @param string $text
4778+
* @param string|int|float $text The text to be escaped.
47744779
* @return string Escaped text.
47754780
*/
47764781
function esc_attr( $text ) {
4782+
$text = (string) $text;
47774783
$safe_text = wp_check_invalid_utf8( $text );
47784784
$safe_text = _wp_specialchars( $safe_text, ENT_QUOTES );
47794785
/**
@@ -4794,11 +4800,13 @@ function esc_attr( $text ) {
47944800
* Escaping for textarea values.
47954801
*
47964802
* @since 3.1.0
4803+
* @since 7.2.0 Non-string scalars are cast to string before escaping.
47974804
*
4798-
* @param string $text
4805+
* @param string|int|float $text The text to be escaped.
47994806
* @return string Escaped text.
48004807
*/
48014808
function esc_textarea( $text ) {
4809+
$text = (string) $text;
48024810
$safe_text = htmlspecialchars( $text, ENT_QUOTES, get_option( 'blog_charset' ) );
48034811
/**
48044812
* Filters a string cleaned and escaped for output in a textarea element.
@@ -4815,11 +4823,13 @@ function esc_textarea( $text ) {
48154823
* Escaping for XML blocks.
48164824
*
48174825
* @since 5.5.0
4826+
* @since 7.2.0 Non-string scalars are cast to string before escaping.
48184827
*
4819-
* @param string $text Text to escape.
4828+
* @param string|int|float $text The text to be escaped.
48204829
* @return string Escaped text.
48214830
*/
48224831
function esc_xml( $text ) {
4832+
$text = (string) $text;
48234833
$safe_text = wp_check_invalid_utf8( $text );
48244834

48254835
$cdata_regex = '\<\!\[CDATA\[.*?\]\]\>';

0 commit comments

Comments
 (0)