Changeset 55346 for trunk/src/wp-includes/formatting.php

Timestamp:

02/15/2023 01:04:06 PM (19 months ago)

Author:

SergeyBiryukov

Message:

Docs: Improve code comments in some sanitizing functions.

This aims to clarify a few inline comments related to removing percent-encoded characters and HTML entities.

Affected functions:

• sanitize_user()
• sanitize_title_with_dashes()
• sanitize_html_class()
• _sanitize_text_fields()
• get_comments_number_text()

Follow-up to [465], [3454], [11433], [12503], [37987].

Props ace100, tanjimtc71, codemonksuvro, SergeyBiryukov.
Fixes #57712.

File:

• trunk/src/wp-includes/formatting.php (modified) (8 diffs)

trunk/src/wp-includes/formatting.php

@@ -2112 +2112 @@
  * Sanitizes a username, stripping out unsafe characters.
  *
- * Removes tags, octets, entities, and if strict is enabled, will only keep
- * alphanumeric, _, space, ., -, @. After sanitizing, it passes the username,
- * raw username (the username in the parameter), and the value of $strict as
- * parameters for the {@see 'sanitize_user'} filter.
+ * Removes tags, percent-encoded characters, HTML entities, and if strict is enabled,
+ * will only keep alphanumeric, _, space, ., -, @. After sanitizing, it passes the username,
+ * raw username (the username in the parameter), and the value of $strict as parameters
+ * for the {@see 'sanitize_user'} filter.
  *
  * @since 2.0.0
  *
  * @param string $username The username to be sanitized.
- * @param bool   $strict   Optional. If set limits $username to specific characters.
+ * @param bool   $strict   Optional. If set to true, limits $username to specific characters.
  *                         Default false.
  * @return string The sanitized username, after passing through filters.
@@ -2128 +2128 @@
     $username     = wp_strip_all_tags( $username );
     $username     = remove_accents( $username );
-    // Kill octets.
+    // Remove percent-encoded characters.
     $username = preg_replace( '|%([a-fA-F0-9][a-fA-F0-9])|', '', $username );
-    // Kill entities.
+    // Remove HTML entities.
     $username = preg_replace( '/&.+?;/', '', $username );
 
@@ -2365 +2365 @@
     }
 
-    // Kill entities.
+    // Remove HTML entities.
     $title = preg_replace( '/&.+?;/', '', $title );
     $title = str_replace( '.', '-', $title );
@@ -2413 +2413 @@
  */
 function sanitize_html_class( $classname, $fallback = '' ) {
-    // Strip out any %-encoded octets.
+    // Strip out any percent-encoded characters.
     $sanitized = preg_replace( '|%[a-fA-F0-9][a-fA-F0-9]|', '', $classname );
 
@@ -5451 +5451 @@
  * - Strips all tags
  * - Removes line breaks, tabs, and extra whitespace
- * - Strips octets
+ * - Strips percent-encoded characters
  *
  * @since 2.9.0
@@ -5528 +5528 @@
         $filtered = wp_strip_all_tags( $filtered, false );
 
-        // Use HTML entities in a special case to make sure no later
-        // newline stripping stage could lead to a functional tag.
+        /*
+         * Use HTML entities in a special case to make sure that
+         * later newline stripping stages cannot lead to a functional tag.
+         */
         $filtered = str_replace( "<\n", "&lt;\n", $filtered );
     }
@@ -5538 +5540 @@
     $filtered = trim( $filtered );
 
+    // Remove percent-encoded characters.
     $found = false;
     while ( preg_match( '/%[a-f0-9]{2}/i', $filtered, $match ) ) {
@@ -5545 +5548 @@
 
     if ( $found ) {
-        // Strip out the whitespace that may now exist after removing the octets.
+        // Strip out the whitespace that may now exist after removing percent-encoded characters.
         $filtered = trim( preg_replace( '/ +/', ' ', $filtered ) );
     }