概述

mbstring_binary_safe_encoding() 函数用于在启用 mbstring.func_overload 时，将 mbstring 内部编码设置为二进制安全编码，以避免多字节编码下 strlen() 等函数返回错误长度。它通过临时切换编码并配合 reset_mbstring_encoding() 恢复，支持递归调用。

关键要点

• 当 mbstring.func_overload 启用时，此函数将 mbstring 内部编码临时设置为 ISO-8859-1，以确保二进制数据处理的正确性。
• 函数使用静态变量跟踪编码状态，支持通过 $reset 参数重置编码，且必须与 reset_mbstring_encoding() 配对调用以保持平衡。
• 如果 mbstring.func_overload 未启用或 mb_internal_encoding() 不可用，函数将直接返回而不执行任何操作。

代码示例

function mbstring_binary_safe_encoding( $reset = false ) {
	static $encodings  = array();
	static $overloaded = null;

	if ( is_null( $overloaded ) ) {
		if ( function_exists( 'mb_internal_encoding' )
			&& ( (int) ini_get( 'mbstring.func_overload' ) & 2 ) // phpcs:ignore PHPCompatibility.IniDirectives.RemovedIniDirectives.mbstring_func_overloadDeprecated
		) {
			$overloaded = true;
		} else {
			$overloaded = false;
		}
	}

	if ( false === $overloaded ) {
		return;
	}

	if ( ! $reset ) {
		$encoding = mb_internal_encoding();
		array_push( $encodings, $encoding );
		mb_internal_encoding( 'ISO-8859-1' );
	}

	if ( $reset && $encodings ) {
		$encoding = array_pop( $encodings );
		mb_internal_encoding( $encoding );
	}
}

注意事项

• 此函数主要用于处理二进制数据，如文件签名验证或字符串操作，在多字节环境下避免长度计算错误。
• 递归调用时，每次 mbstring_binary_safe_encoding() 必须对应相同次数的 reset_mbstring_encoding() 调用，否则可能导致编码状态不一致。
• 自 WordPress 3.7.0 引入，相关函数如 verify_file_signature() 和 wpdb::strip_invalid_text() 依赖此功能确保兼容性。