From 37bff7cea28c21a649a3016adfadaa81b49dd4be Mon Sep 17 00:00:00 2001 From: SergeyBiryukov Date: Thu, 15 Sep 2022 13:29:13 +0000 Subject: [PATCH] Docs: Clarify the `$allowed_protocols` default value in various KSES functions. Add a note that the parameter is optional and defaults to the result of `wp_allowed_protocols()`. This affects: * `wp_kses()` * `filter_block_content()` * `filter_block_kses()` * `filter_block_kses_value()` Includes synchronizing the `$allowed_html` parameter description for consistency. Follow-up to [649], [6630], [18826], [32603], [43016], [46896], [48478]. Props armondal, SergeyBiryukov. Fixes #56580. Built from https://develop.svn.wordpress.org/trunk@54181 --- wp-includes/blocks.php | 43 ++++++++++++++++++++++------------------- wp-includes/kses.php | 3 ++- wp-includes/version.php | 2 +- 3 files changed, 26 insertions(+), 22 deletions(-) diff --git a/wp-includes/blocks.php b/wp-includes/blocks.php index b18e88d47b..04bc04cf72 100644 --- a/wp-includes/blocks.php +++ b/wp-includes/blocks.php @@ -717,8 +717,8 @@ function serialize_block( $block ) { } /** - * Returns a joined string of the aggregate serialization of the given parsed - * blocks. + * Returns a joined string of the aggregate serialization of the given + * parsed blocks. * * @since 5.3.1 * @@ -730,16 +730,17 @@ function serialize_blocks( $blocks ) { } /** - * Filters and sanitizes block content to remove non-allowable HTML from - * parsed block attribute values. + * Filters and sanitizes block content to remove non-allowable HTML + * from parsed block attribute values. * * @since 5.3.1 * * @param string $text Text that may contain block content. - * @param array[]|string $allowed_html An array of allowed HTML elements - * and attributes, or a context name - * such as 'post'. - * @param string[] $allowed_protocols Array of allowed URL protocols. + * @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 Optional. Array of allowed URL protocols. + * Defaults to the result of wp_allowed_protocols(). * @return string The filtered and sanitized content result. */ function filter_block_content( $text, $allowed_html = 'post', $allowed_protocols = array() ) { @@ -755,16 +756,17 @@ function filter_block_content( $text, $allowed_html = 'post', $allowed_protocols } /** - * Filters and sanitizes a parsed block to remove non-allowable HTML from block - * attribute values. + * Filters and sanitizes a parsed block to remove non-allowable HTML + * from block attribute values. * * @since 5.3.1 * * @param WP_Block_Parser_Block $block The parsed block object. - * @param array[]|string $allowed_html An array of allowed HTML - * elements and attributes, or a - * context name such as 'post'. - * @param string[] $allowed_protocols Allowed URL protocols. + * @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 Optional. Array of allowed URL protocols. + * Defaults to the result of wp_allowed_protocols(). * @return array The filtered and sanitized block object result. */ function filter_block_kses( $block, $allowed_html, $allowed_protocols = array() ) { @@ -780,16 +782,17 @@ function filter_block_kses( $block, $allowed_html, $allowed_protocols = array() } /** - * Filters and sanitizes a parsed block attribute value to remove non-allowable - * HTML. + * Filters and sanitizes a parsed block attribute value to remove + * non-allowable HTML. * * @since 5.3.1 * * @param string[]|string $value The attribute value to filter. - * @param array[]|string $allowed_html An array of allowed HTML elements - * and attributes, or a context name - * such as 'post'. - * @param string[] $allowed_protocols Array of allowed URL protocols. + * @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 Optional. Array of allowed URL protocols. + * Defaults to the result of wp_allowed_protocols(). * @return string[]|string The filtered and sanitized result. */ function filter_block_kses_value( $value, $allowed_html, $allowed_protocols = array() ) { diff --git a/wp-includes/kses.php b/wp-includes/kses.php index 7776de59d5..5dddfd023e 100644 --- a/wp-includes/kses.php +++ b/wp-includes/kses.php @@ -706,7 +706,8 @@ * @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. + * @param string[] $allowed_protocols Optional. Array of allowed URL protocols. + * Defaults to the result of wp_allowed_protocols(). * @return string Filtered content containing only the allowed HTML. */ function wp_kses( $string, $allowed_html, $allowed_protocols = array() ) { diff --git a/wp-includes/version.php b/wp-includes/version.php index d6e3accb56..e0e1d7f465 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.1-alpha-54180'; +$wp_version = '6.1-alpha-54181'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.