Changeset 52234

Timestamp:

11/23/2021 06:37:03 PM (18 months ago)

Author:

SergeyBiryukov

Message:

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.

File:

• trunk/src/wp-includes/kses.php (modified) (3 diffs)

trunk/src/wp-includes/kses.php

@@ -1143 +1143 @@
  * 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.
@@ -1181 +1191 @@
     );
 
-    // 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 ) ) {
@@ -1189 +1201 @@
     }
 
-    // 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 ) {