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