mb_decode_numericentity函数的范围数组如何正确设置

gitbox 2025-05-29

在PHP中，mb_decode_numericentity函数用于将字符串中的数值实体（numeric entities）转换为对应的字符。这在处理多字节字符编码时非常实用，比如转换包含HTML实体的文本。正确设置其范围数组，是确保函数正常工作的关键。

一、mb_decode_numericentity函数简介

string mb_decode_numericentity ( string $string , array $map , string $encoding = mb_internal_encoding() )

$string：要转换的字符串。
$map：范围数组，定义数值实体的转换范围和偏移。
$encoding：字符编码，默认为内部编码。

二、范围数组 $map 的格式与规则

范围数组是一个一维数组，长度必须是4的倍数，每4个元素代表一个转换范围：

[
    start_codepoint, end_codepoint, offset, mask,
    start_codepoint, end_codepoint, offset, mask,
    ...
]

start_codepoint：起始Unicode码点（十进制）。
end_codepoint：结束Unicode码点（十进制）。
offset：应用于数值实体数值的偏移量（通常为0）。
mask：掩码，用于位操作，通常为0xFFFF或0xFFFFFFFF。

注： mb_decode_numericentity只会转换数值实体码点落在start_codepoint到end_codepoint区间内的字符。

三、示例：正确设置范围数组

假设我们要转换的数值实体涵盖的Unicode范围是基本多文种平面（BMP），即从0x0到0xFFFF：

$map = [
    0x0, 0xFFFF, 0, 0xFFFF
];

这里的解释：

转换所有Unicode码点从0到65535的数值实体。
偏移0表示不调整原数值实体码点。
掩码0xFFFF用于保证转换结果限制在16位范围内。

四、完整代码示例

<?php
// 待转换的字符串，包含数值实体
$input = "Hello &#20320;&#22909;!"; // “Hello 你好!”

// 设置转换范围数组，转换BMP范围的实体
$map = [0x0, 0xFFFF, 0, 0xFFFF];

// 使用mb_decode_numericentity转换
$output = mb_decode_numericentity($input, $map, 'UTF-8');

echo $output;  // 输出：Hello 你好!
?>

五、注意事项

范围数组必须是4的倍数长度，否则函数无效。
偏移一般设为0，除非特殊需求。
掩码通常为0xFFFF（16位）或0xFFFFFFFF（32位），视Unicode范围决定。
如果数值实体超出范围，函数不会转换它。

六、总结

mb_decode_numericentity的范围数组决定了哪些数值实体会被转换。
设定合理的起止码点和掩码，确保目标字符能够正确解析。
对大部分普通场景，设定[0x0, 0xFFFF, 0, 0xFFFF]即可满足BMP范围字符转换。

掌握范围数组设置，能让你灵活处理各种多字节编码字符实体，避免乱码和解析错误。

mb_decode_numericentity