From 86cd872c296bfe1bb71eaffcb817670e17e1ad07 Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov.ru@gmail.com>
Date: Tue, 23 Nov 2021 18:39:00 +0000
Subject: [PATCH] Docs: Add a `@since` note and description to `wp_kses_attr()`
 for new attribute-related KSES options:

* Support for an array of allowed values for attributes.
* Support for required attributes.

Follow-up to [51963].

See #54261.
Built from https://develop.svn.wordpress.org/trunk@52234


git-svn-id: http://core.svn.wordpress.org/trunk@51826 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/kses.php    | 21 ++++++++++++++++-----
 wp-includes/version.php |  2 +-
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/wp-includes/kses.php b/wp-includes/kses.php
index b77d501333..d379319f83 100644
--- a/wp-includes/kses.php
+++ b/wp-includes/kses.php
@@ -1142,7 +1142,17 @@ function wp_kses_split2( $string, $allowed_html, $allowed_protocols ) {
  * is to check if the tag has a closing XHTML slash, and if it does, it puts one
  * in the returned code as well.
  *
+ * An array of allowed values can be defined for attributes. If the attribute value
+ * doesn't fall into the list, the attribute will be removed from the tag.
+ *
+ * Attributes can be marked as required. If a required attribute is not present,
+ * KSES will remove all attributes from the tag. As KSES doesn't match opening and
+ * closing tags, it's not possible to safely remove the tag itself, the safest
+ * fallback is to strip all attributes from the tag, instead.
+ *
  * @since 1.0.0
+ * @since 5.9.0 Added support for an array of allowed values for attributes.
+ *              Added support for required attributes.
  *
  * @param string         $element           HTML element/tag.
  * @param string         $attr              HTML attributes from HTML element to closing HTML element tag.
@@ -1180,16 +1190,17 @@ function wp_kses_attr( $element, $attr, $allowed_html, $allowed_protocols ) {
 		}
 	);
 
-	// If a required attribute check fails, we can return nothing for a self-closing tag,
-	// but for a non-self-closing tag the best option is to return the element with attributes,
-	// as KSES doesn't handle matching the relevant closing tag.
+	/*
+	 * If a required attribute check fails, we can return nothing for a self-closing tag,
+	 * but for a non-self-closing tag the best option is to return the element with attributes,
+	 * as KSES doesn't handle matching the relevant closing tag.
+	 */
 	$stripped_tag = '';
 	if ( empty( $xhtml_slash ) ) {
 		$stripped_tag = "<$element>";
 	}
 
-	// Go through $attrarr, and save the allowed attributes for this element
-	// in $attr2.
+	// Go through $attrarr, and save the allowed attributes for this element in $attr2.
 	$attr2 = '';
 	foreach ( $attrarr as $arreach ) {
 		// Check if this attribute is required.
diff --git a/wp-includes/version.php b/wp-includes/version.php
index fa357a3c00..6e5823be4b 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.9-alpha-52233';
+$wp_version = '5.9-alpha-52234';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.