Changeset 60950 for trunk/src/wp-includes/compat.php

Timestamp:

10/16/2025 11:17:14 PM (12 months ago)

Author:

dmsnell

Message:

Charset: Conditionally polyfill utf8_encode() and utf8_decode().

The utf8_encode() and utf8_decode() functions were deprecated in PHP 8.2.0 and will be removed in PHP 9.0. When that happens, any existing code which calls them will trigger a crash.

This patch introduces polyfills for those functions when they aren’t already present. The polyfill functions maintain backwards compatibility, including a deprecation notice.

Any code calling either of these functions ought to be refactored to avoid using them; there are better options which don’t carry the issues these functions do, and any code calling them is likely calling them inappropriately.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10011
Discussed in https://core.trac.wordpress.org/ticket/55603
Discussed in https://core.trac.wordpress.org/ticket/63863

See #63863.

File:

• trunk/src/wp-includes/compat.php (modified) (1 diff)

trunk/src/wp-includes/compat.php

@@ -248 +248 @@
 }
 
+if ( ! function_exists( 'utf8_encode' ) ) :
+        if ( extension_loaded( 'mbstring' ) ) :
+                /**
+                 * Converts a string from ISO-8859-1 to UTF-8.
+                 *
+                 * @deprecated Use {@see \mb_convert_encoding()} instead.
+                 *
+                 * @since 6.9.0
+                 *
+                 * @param string $iso_8859_1_text Text treated as ISO-8859-1 (latin1) bytes.
+                 * @return string Text converted into a UTF-8.
+                 */
+                function utf8_encode( $iso_8859_1_text ): string {
+                        _deprecated_function( __FUNCTION__, '6.9.0', 'mb_convert_encoding' );
+
+                        return mb_convert_encoding( $iso_8859_1_text, 'UTF-8', 'ISO-8859-1' );
+                }
+
+        else :
+                /**
+                 * @ignore
+                 * @private
+                 *
+                 * @since 6.9.0
+                 */
+                function utf8_encode( $iso_8859_1_text ): string {
+                        _deprecated_function( __FUNCTION__, '6.9.0', 'mb_convert_encoding' );
+
+                        return _wp_utf8_encode_fallback( $iso_8859_1_text );
+                }
+
+        endif;
+endif;
+
+if ( ! function_exists( 'utf8_decode' ) ) :
+        if ( extension_loaded( 'mbstring' ) ) :
+                /**
+                 * Converts a string from UTF-8 to ISO-8859-1.
+                 *
+                 * @deprecated Use {@see \mb_convert_encoding()} instead.
+                 *
+                 * @since 6.9.0
+                 *
+                 * @param string $utf8_text Text treated as UTF-8.
+                 * @return string Text converted into ISO-8859-1.
+                 */
+                function utf8_decode( $utf8_text ): string {
+                        _deprecated_function( __FUNCTION__, '6.9.0', 'mb_convert_encoding' );
+
+                        return mb_convert_encoding( $utf8_text, 'ISO-8859-1', 'UTF-8' );
+                }
+
+        else :
+                /**
+                 * @ignore
+                 * @private
+                 *
+                 * @since 6.9.0
+                 */
+                function utf8_decode( $utf8_text ): string {
+                        _deprecated_function( __FUNCTION__, '6.9.0', 'mb_convert_encoding' );
+
+                        return _wp_utf8_decode_fallback( $utf8_text );
+                }
+
+        endif;
+endif;
+
 // sodium_crypto_box() was introduced in PHP 7.2.
 if ( ! function_exists( 'sodium_crypto_box' ) ) {