diff --git a/wp-includes/functions.php b/wp-includes/functions.php index 6f9e77c5b7..de978b3b5d 100644 --- a/wp-includes/functions.php +++ b/wp-includes/functions.php @@ -5365,9 +5365,11 @@ function send_frame_options_header() { * * @staticvar array $protocols * - * @return array Array of allowed protocols. Defaults to an array containing 'http', 'https', - * 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet', - * 'mms', 'rtsp', 'svn', 'tel', 'fax', 'xmpp', 'webcal', and 'urn'. + * @return string[] Array of allowed protocols. Defaults to an array containing 'http', 'https', + * 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet', + * 'mms', 'rtsp', 'svn', 'tel', 'fax', 'xmpp', 'webcal', and 'urn'. This covers + * all common link protocols, except for 'javascript' which should not be + * allowed for untrusted users. */ function wp_allowed_protocols() { static $protocols = array(); diff --git a/wp-includes/kses.php b/wp-includes/kses.php index 93bb4abc1d..827e6f84bd 100644 --- a/wp-includes/kses.php +++ b/wp-includes/kses.php @@ -31,15 +31,15 @@ */ /** - * You can override this in a plugin. + * Specifies the default allowable HTML tags. * - * The {@see 'wp_kses_allowed_html'} filter is more powerful and supplies context. - * - * `CUSTOM_TAGS` is not recommended and should be considered deprecated. + * Using `CUSTOM_TAGS` is not recommended and should be considered deprecated. The + * {@see 'wp_kses_allowed_html'} filter is more powerful and supplies context. * * @see wp_kses_allowed_html() - * * @since 1.2.0 + * + * @var array[]|bool Array of default allowable HTML tags, or false to use the defaults. */ if ( ! defined( 'CUSTOM_TAGS' ) ) { define( 'CUSTOM_TAGS', false ); @@ -51,11 +51,11 @@ global $allowedposttags, $allowedtags, $allowedentitynames; if ( ! CUSTOM_TAGS ) { /** - * Kses global for default allowable HTML tags. + * KSES global for default allowable HTML tags. * - * Can be override by using CUSTOM_TAGS constant. + * Can be overridden with the `CUSTOM_TAGS` constant. * - * @global array $allowedposttags + * @var array[] $allowedposttags Array of default allowable HTML tags. * @since 2.0.0 */ $allowedposttags = array( @@ -416,9 +416,7 @@ if ( ! CUSTOM_TAGS ) { ); /** - * Kses allowed HTML elements. - * - * @global array $allowedtags + * @var array[] $allowedtags Array of KSES allowed HTML elements. * @since 1.0.0 */ $allowedtags = array( @@ -451,6 +449,10 @@ if ( ! CUSTOM_TAGS ) { 'strong' => array(), ); + /** + * @var string[] $allowedentitynames Array of KSES allowed HTML entitity names. + * @since 1.0.0 + */ $allowedentitynames = array( 'nbsp', 'iexcl', @@ -714,24 +716,23 @@ if ( ! CUSTOM_TAGS ) { } /** - * Filters content and keeps only allowable HTML elements. + * Filters text content and strips out disallowed HTML. * * This function makes sure that only the allowed HTML element names, attribute - * names and attribute values plus only sane HTML entities will occur in - * $string. You have to remove any slashes from PHP's magic quotes before you - * call this function. + * names, attribute values, and HTML entities will occur in the given text string. * - * The default allowed protocols are 'http', 'https', 'ftp', 'mailto', 'news', - * 'irc', 'gopher', 'nntp', 'feed', 'telnet, 'mms', 'rtsp' and 'svn'. This - * covers all common link protocols, except for 'javascript' which should not - * be allowed for untrusted users. + * This function expects unslashed data. + * + * @see wp_kses_post() for specifically filtering post content and fields. + * @see wp_allowed_protocols() for the default allowed protocols in link URLs. * * @since 1.0.0 * - * @param string $string Content to filter through kses - * @param array $allowed_html List of allowed HTML elements - * @param array $allowed_protocols Optional. Allowed protocol in links. - * @return string Filtered content with only allowed HTML elements + * @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 string[] $allowed_protocols Array of allowed URL protocols. + * @return string Filtered content containing only the allowed HTML. */ function wp_kses( $string, $allowed_html, $allowed_protocols = array() ) { if ( empty( $allowed_protocols ) ) { @@ -739,20 +740,19 @@ function wp_kses( $string, $allowed_html, $allowed_protocols = array() ) { } $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 ); // WP changed the order of these funcs and added args to wp_kses_hook + $string = wp_kses_hook( $string, $allowed_html, $allowed_protocols ); return wp_kses_split( $string, $allowed_html, $allowed_protocols ); } /** - * Filters one attribute only and ensures its value is allowed. + * Filters one HTML attribute and ensures its value is allowed. * - * This function has the advantage of being more secure than esc_attr() and can - * escape data in some situations where wp_kses() must strip the whole attribute. + * This function can escape data in some situations where `wp_kses()` must strip the whole attribute. * * @since 4.2.3 * - * @param string $string The 'whole' attribute, including name and value. - * @param string $element The element name to which the attribute belongs. + * @param string $string The 'whole' attribute, including name and value. + * @param string $element The HTML element name to which the attribute belongs. * @return string Filtered attribute. */ function wp_kses_one_attr( $string, $element ) { @@ -818,7 +818,7 @@ function wp_kses_one_attr( $string, $element ) { } /** - * Return a list of allowed tags and attributes for a given context. + * Returns an array of allowed HTML tags and attributes for a given context. * * @since 3.5.0 * @@ -826,22 +826,22 @@ function wp_kses_one_attr( $string, $element ) { * @global array $allowedtags * @global array $allowedentitynames * - * @param string|array $context The context for which to retrieve tags. - * Allowed values are post, strip, data, entities, or - * the name of a field filter such as pre_user_description. - * @return array List of allowed tags and their allowed attributes. + * @param string|array $context The context for which to retrieve tags. Allowed values are 'post', + * 'strip', 'data', 'entities', or the name of a field filter such as + * 'pre_user_description'. + * @return array Array of allowed HTML tags and their allowed attributes. */ function wp_kses_allowed_html( $context = '' ) { global $allowedposttags, $allowedtags, $allowedentitynames; if ( is_array( $context ) ) { /** - * Filters HTML elements allowed for a given context. + * Filters the HTML that is allowed for a given context. * * @since 3.5.0 * - * @param array $context Context to judge allowed tags by. - * @param string $context_type Context type (explicit). + * @param array[]|string $context Context to judge allowed tags by. + * @param string $context_type Context name. */ return apply_filters( 'wp_kses_allowed_html', $context, 'explicit' ); } @@ -874,16 +874,16 @@ function wp_kses_allowed_html( $context = '' ) { } /** - * You add any kses hooks here. + * You add any KSES hooks here. * - * There is currently only one kses WordPress hook, {@see 'pre_kses'}, and it is called here. + * There is currently only one KSES WordPress hook, {@see 'pre_kses'}, and it is called here. * All parameters are passed to the hooks and expected to receive a string. * * @since 1.0.0 * - * @param string $string Content to filter through kses - * @param array $allowed_html List of allowed HTML elements - * @param array $allowed_protocols Allowed protocol in links + * @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. * @return string Filtered content through {@see 'pre_kses'} hook. */ function wp_kses_hook( $string, $allowed_html, $allowed_protocols ) { @@ -892,19 +892,19 @@ function wp_kses_hook( $string, $allowed_html, $allowed_protocols ) { * * @since 2.3.0 * - * @param string $string Content to run through kses. - * @param array $allowed_html Allowed HTML elements. - * @param array $allowed_protocols Allowed protocol in links. + * @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. */ return apply_filters( 'pre_kses', $string, $allowed_html, $allowed_protocols ); } /** - * This function returns kses' version number. + * Returns the version number of KSES. * * @since 1.0.0 * - * @return string KSES Version Number + * @return string KSES version number. */ function wp_kses_version() { return '0.2.2'; @@ -913,16 +913,16 @@ function wp_kses_version() { /** * Searches for HTML tags, no matter how malformed. * - * It also matches stray ">" characters. + * It also matches stray `>` characters. * * @since 1.0.0 * * @global array $pass_allowed_html * @global array $pass_allowed_protocols * - * @param string $string Content to filter - * @param array $allowed_html Allowed HTML elements - * @param array $allowed_protocols Allowed protocols to keep + * @param string $string Content to filter. + * @param array $allowed_html Allowed HTML elements. + * @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 ) { @@ -933,10 +933,11 @@ function wp_kses_split( $string, $allowed_html, $allowed_protocols ) { } /** - * Callback for wp_kses_split. + * Callback for `wp_kses_split()`. * * @since 3.1.0 * @access private + * @ignore * * @global array $pass_allowed_html * @global array $pass_allowed_protocols @@ -949,11 +950,11 @@ function _wp_kses_split_callback( $match ) { } /** - * Callback for wp_kses_split for fixing malformed HTML tags. + * Callback for `wp_kses_split()` for fixing malformed HTML tags. * * This function does a lot of work. It rejects some very malformed things like - * <:::>. It returns an empty string, if the element isn't allowed (look ma, no - * strip_tags()!). Otherwise it splits the tag into an element and an attribute + * `<:::>`. It returns an empty string, if the element isn't allowed (look ma, no + * `strip_tags()`!). Otherwise it splits the tag into an element and an attribute * list. * * After the tag is split into an element and an attribute list, it is run @@ -961,11 +962,12 @@ function _wp_kses_split_callback( $match ) { * completed, will be returned. * * @access private + * @ignore * @since 1.0.0 * - * @param string $string Content to filter - * @param array $allowed_html Allowed HTML elements - * @param array $allowed_protocols Allowed protocols to keep + * @param string $string Content to filter. + * @param array $allowed_html Allowed HTML elements. + * @param string[] $allowed_protocols Array of allowed URL protocols. * @return string Fixed HTML element */ function wp_kses_split2( $string, $allowed_html, $allowed_protocols ) { @@ -1021,19 +1023,19 @@ function wp_kses_split2( $string, $allowed_html, $allowed_protocols ) { /** * Removes all attributes, if none are allowed for this element. * - * If some are allowed it calls wp_kses_hair() to split them further, and then - * it builds up new HTML code from the data that kses_hair() returns. It also - * removes "<" and ">" characters, if there are any left. One more thing it does + * If some are allowed it calls `wp_kses_hair()` to split them further, and then + * it builds up new HTML code from the data that `kses_hair()` returns. It also + * removes `<` and `>` characters, if there are any left. One more thing it does * is to check if the tag has a closing XHTML slash, and if it does, it puts one * in the returned code as well. * * @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 array $allowed_protocols Allowed protocols to keep - * @return string Sanitized HTML element + * @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. + * @return string Sanitized HTML element. */ function wp_kses_attr( $element, $attr, $allowed_html, $allowed_protocols ) { if ( ! is_array( $allowed_html ) ) { @@ -1071,17 +1073,17 @@ function wp_kses_attr( $element, $attr, $allowed_html, $allowed_protocols ) { } /** - * Determine whether an attribute is allowed. + * Determines whether an attribute is allowed. * * @since 4.2.3 * - * @param string $name The attribute name. Returns empty string when not allowed. - * @param string $value The attribute value. Returns a filtered value. - * @param string $whole The name=value input. Returns filtered input. - * @param string $vless 'y' when attribute like "enabled", otherwise 'n'. - * @param string $element The name of the element to which this attribute belongs. - * @param array $allowed_html The full list of allowed elements and attributes. - * @return bool Is the attribute allowed? + * @param string $name The attribute name. Passed by reference. Returns empty string when not allowed. + * @param string $value The attribute value. Passed by reference. Returns a filtered value. + * @param string $whole The `name=value` input. Passed by reference. Returns filtered input. + * @param string $vless Whether the attribute is valueless. Use 'y' or 'n'. + * @param string $element The name of the element to which this attribute belongs. + * @param array $allowed_html The full list of allowed elements and attributes. + * @return bool Whether or not the attribute is allowed. */ function wp_kses_attr_check( &$name, &$value, &$whole, $vless, $element, $allowed_html ) { $allowed_attr = $allowed_html[ strtolower( $element ) ]; @@ -1126,13 +1128,13 @@ function wp_kses_attr_check( &$name, &$value, &$whole, $vless, $element, $allowe * or apostrophes around them, to make it easier to produce HTML code that will * conform to W3C's HTML specification. It will also remove bad URL protocols * from attribute values. It also reduces duplicate attributes by using the - * attribute defined first (foo='bar' foo='baz' will result in foo='bar'). + * attribute defined first (`foo='bar' foo='baz'` will result in `foo='bar'`). * * @since 1.0.0 * - * @param string $attr Attribute list from HTML element to closing HTML element tag - * @param array $allowed_protocols Allowed protocols to keep - * @return array List of attributes after parsing + * @param string $attr Attribute list from HTML element to closing HTML element tag. + * @param string[] $allowed_protocols Array of allowed URL protocols. + * @return array[] Array of attribute information after parsing. */ function wp_kses_hair( $attr, $allowed_protocols ) { $attrarr = array(); @@ -1271,12 +1273,12 @@ function wp_kses_hair( $attr, $allowed_protocols ) { * * Does not modify input. May return "evil" output. * - * Based on wp_kses_split2() and wp_kses_attr() + * Based on `wp_kses_split2()` and `wp_kses_attr()`. * * @since 4.2.3 * - * @param string $element HTML element/tag - * @return array|bool List of attributes found in $element. Returns false on failure. + * @param string $element HTML element. + * @return array|bool List of attributes found in the element. Returns false on failure. */ function wp_kses_attr_parse( $element ) { $valid = preg_match( '%^(<\s*)(/\s*)?([a-zA-Z0-9]+\s*)([^>]*)(>?)$%', $element, $matches ); @@ -1322,11 +1324,11 @@ function wp_kses_attr_parse( $element ) { * Does not modify input. May return "evil" output. * In case of unexpected input, returns false instead of stripping things. * - * Based on wp_kses_hair() but does not return a multi-dimensional array. + * Based on `wp_kses_hair()` but does not return a multi-dimensional array. * * @since 4.2.3 * - * @param string $attr Attribute list from HTML element to closing HTML element tag + * @param string $attr Attribute list from HTML element to closing HTML element tag. * @return array|bool List of attributes found in $attr. Returns false on failure. */ function wp_kses_hair_parse( $attr ) { @@ -1374,16 +1376,16 @@ function wp_kses_hair_parse( $attr ) { /** * Performs different checks for attribute values. * - * The currently implemented checks are "maxlen", "minlen", "maxval", "minval" + * The currently implemented checks are "maxlen", "minlen", "maxval", "minval", * and "valueless". * * @since 1.0.0 * - * @param string $value Attribute value - * @param string $vless Whether the value is valueless. Use 'y' or 'n' + * @param string $value Attribute value. + * @param string $vless Whether the attribute is valueless. Use 'y' or 'n'. * @param string $checkname What $checkvalue is checking for. - * @param mixed $checkvalue What constraint the value should pass - * @return bool Whether check passes + * @param mixed $checkvalue What constraint the value should pass. + * @return bool Whether check passes. */ function wp_kses_check_attr_val( $value, $vless, $checkname, $checkvalue ) { $ok = true; @@ -1437,9 +1439,9 @@ function wp_kses_check_attr_val( $value, $vless, $checkname, $checkvalue ) { case 'valueless': // The valueless check makes sure if the attribute has a value - // (like ) or not (`) or not (`