From 2b4d385298504d412e9f0dea2e7019d53463c705 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Thu, 15 Sep 2022 13:27:38 +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. git-svn-id: https://develop.svn.wordpress.org/trunk@54181 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/blocks.php | 43 ++++++++++++++++++++------------------ src/wp-includes/kses.php | 3 ++- 2 files changed, 25 insertions(+), 21 deletions(-) diff --git a/src/wp-includes/blocks.php b/src/wp-includes/blocks.php index b18e88d47b..04bc04cf72 100644 --- a/src/wp-includes/blocks.php +++ b/src/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/src/wp-includes/kses.php b/src/wp-includes/kses.php index 7776de59d5..5dddfd023e 100644 --- a/src/wp-includes/kses.php +++ b/src/wp-includes/kses.php @@ -706,7 +706,8 @@ if ( ! CUSTOM_TAGS ) { * @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() ) {