From 74b985fd7d5764a2ad2b495a920a69cb730a1073 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Tue, 14 Jul 2020 12:39:16 +0000 Subject: [PATCH] Docs: Synchronize description for the `$allowed_html` parameter of various KSES functions. Follow-up to [43016]. Props Christian1012, jdgrimes, markparnell. Fixes #39542. See #33801. git-svn-id: https://develop.svn.wordpress.org/trunk@48478 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/kses.php | 64 +++++++++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 23 deletions(-) diff --git a/src/wp-includes/kses.php b/src/wp-includes/kses.php index 154c10e277..6a579b8d91 100644 --- a/src/wp-includes/kses.php +++ b/src/wp-includes/kses.php @@ -736,8 +736,9 @@ if ( ! CUSTOM_TAGS ) { * @since 1.0.0 * * @param string $string Text content to filter. - * @param array[]|string $allowed_html An array of allowed HTML elements and attributes, or a - * context name such as 'post'. + * @param array[]|string $allowed_html An array of allowed HTML elements and attributes, + * or a context name such as 'post'. See wp_kses_allowed_html() + * for the list of accepted context names. * @param string[] $allowed_protocols Array of allowed URL protocols. * @return string Filtered content containing only the allowed HTML. */ @@ -745,9 +746,11 @@ function wp_kses( $string, $allowed_html, $allowed_protocols = array() ) { if ( empty( $allowed_protocols ) ) { $allowed_protocols = wp_allowed_protocols(); } + $string = wp_kses_no_null( $string, array( 'slash_zero' => 'keep' ) ); $string = wp_kses_normalize_entities( $string ); $string = wp_kses_hook( $string, $allowed_html, $allowed_protocols ); + return wp_kses_split( $string, $allowed_html, $allowed_protocols ); } @@ -909,20 +912,24 @@ function wp_kses_allowed_html( $context = '' ) { * * @since 1.0.0 * - * @param string $string Content to filter through KSES. - * @param array[]|string $allowed_html List of allowed HTML elements. - * @param string[] $allowed_protocols Array of allowed URL protocols. + * @param string $string Content to filter through KSES. + * @param array[]|string $allowed_html An array of allowed HTML elements and attributes, + * or a context name such as 'post'. See wp_kses_allowed_html() + * for the list of accepted context names. + * @param string[] $allowed_protocols Array of allowed URL protocols. * @return string Filtered content through {@see 'pre_kses'} hook. */ function wp_kses_hook( $string, $allowed_html, $allowed_protocols ) { /** - * Filters content to be run through kses. + * Filters content to be run through KSES. * * @since 2.3.0 * - * @param string $string Content to run through KSES. - * @param array[]|string $allowed_html Allowed HTML elements. - * @param string[] $allowed_protocols Array of allowed URL protocols. + * @param string $string Content to filter through KSES. + * @param array[]|string $allowed_html An array of allowed HTML elements and attributes, + * or a context name such as 'post'. See wp_kses_allowed_html() + * for the list of accepted context names. + * @param string[] $allowed_protocols Array of allowed URL protocols. */ return apply_filters( 'pre_kses', $string, $allowed_html, $allowed_protocols ); } @@ -945,18 +952,23 @@ function wp_kses_version() { * * @since 1.0.0 * - * @global array $pass_allowed_html - * @global array $pass_allowed_protocols + * @global array[]|string $pass_allowed_html An array of allowed HTML elements and attributes, + * or a context name such as 'post'. + * @global string[] $pass_allowed_protocols Array of allowed URL protocols. * - * @param string $string Content to filter. - * @param array $allowed_html Allowed HTML elements. - * @param string[] $allowed_protocols Array of allowed URL protocols. + * @param string $string Content to filter. + * @param array[]|string $allowed_html An array of allowed HTML elements and attributes, + * or a context name such as 'post'. See wp_kses_allowed_html() + * for the list of accepted context names. + * @param string[] $allowed_protocols Array of allowed URL protocols. * @return string Content with fixed HTML tags */ function wp_kses_split( $string, $allowed_html, $allowed_protocols ) { global $pass_allowed_html, $pass_allowed_protocols; + $pass_allowed_html = $allowed_html; $pass_allowed_protocols = $allowed_protocols; + return preg_replace_callback( '%(|$))|(<[^>]*(>|$)|>)%', '_wp_kses_split_callback', $string ); } @@ -1017,13 +1029,15 @@ function wp_kses_uri_attributes() { * @access private * @ignore * - * @global array $pass_allowed_html - * @global array $pass_allowed_protocols + * @global array[]|string $pass_allowed_html An array of allowed HTML elements and attributes, + * or a context name such as 'post'. + * @global string[] $pass_allowed_protocols Array of allowed URL protocols. * * @return string */ function _wp_kses_split_callback( $match ) { global $pass_allowed_html, $pass_allowed_protocols; + return wp_kses_split2( $match[0], $pass_allowed_html, $pass_allowed_protocols ); } @@ -1043,9 +1057,11 @@ function _wp_kses_split_callback( $match ) { * @ignore * @since 1.0.0 * - * @param string $string Content to filter. - * @param array $allowed_html Allowed HTML elements. - * @param string[] $allowed_protocols Array of allowed URL protocols. + * @param string $string Content to filter. + * @param array[]|string $allowed_html An array of allowed HTML elements and attributes, + * or a context name such as 'post'. See wp_kses_allowed_html() + * for the list of accepted context names. + * @param string[] $allowed_protocols Array of allowed URL protocols. * @return string Fixed HTML element */ function wp_kses_split2( $string, $allowed_html, $allowed_protocols ) { @@ -1109,10 +1125,12 @@ function wp_kses_split2( $string, $allowed_html, $allowed_protocols ) { * * @since 1.0.0 * - * @param string $element HTML element/tag. - * @param string $attr HTML attributes from HTML element to closing HTML element tag. - * @param array $allowed_html Allowed HTML elements. - * @param string[] $allowed_protocols Array of allowed URL protocols. + * @param string $element HTML element/tag. + * @param string $attr HTML attributes from HTML element to closing HTML element tag. + * @param array[]|string $allowed_html An array of allowed HTML elements and attributes, + * or a context name such as 'post'. See wp_kses_allowed_html() + * for the list of accepted context names. + * @param string[] $allowed_protocols Array of allowed URL protocols. * @return string Sanitized HTML element. */ function wp_kses_attr( $element, $attr, $allowed_html, $allowed_protocols ) {