如何利用mb_encode_numericentity 和mb_decode_numericentity 實現數據編碼與解碼？

gitbox 2025-06-10

1. mb_encode_numericentity 函數簡介

mb_encode_numericentity用於將字符串中符合指定範圍的字符編碼成數值實體（numeric entity）格式。數值實體格式類似於HTML 中的&#xxxx; ，其中xxxx是字符對應的Unicode 碼點。

函數原型：

 string mb_encode_numericentity(string $str, array $convmap, string $encoding = mb_internal_encoding(), bool $is_hex = false)

$str ：待編碼的字符串。
$convmap ：轉換映射數組，用於指定哪些字符範圍需要編碼。格式是四個整數一組，分別表示起始碼點、結束碼點、偏移值和編碼值。
$encoding ：字符串編碼，默認為內部編碼。
$is_hex ：如果設為true ，則數值實體用十六進製表示。

2. mb_decode_numericentity 函數簡介

mb_decode_numericentity用於將數值實體格式的字符串轉換回原始的多字節字符串。

函數原型：

 string mb_decode_numericentity(string $str, array $convmap, string $encoding = mb_internal_encoding())

$str ：待解碼的字符串。
$convmap ：轉換映射數組，作用同mb_encode_numericentity 。
$encoding ：字符串編碼。

3. 實際示例：對中文字符進行編碼和解碼

假設我們需要對一段包含中文的字符串進行編碼，編碼後將所有中文字符轉成數值實體，然後再解碼還原成原始字符串。

 <?php
// 定義轉換映射，覆蓋常用的漢字字符編碼範圍
$convmap = [0x4E00, 0x9FFF, 0, 0xFFFF];

// 待編碼字符串
$str = "你好，世界！Hello World!";

// 編碼，將漢字轉成數值實體
$encoded = mb_encode_numericentity($str, $convmap, "UTF-8");

echo "編碼后：\n" . $encoded . "\n";

// 解碼，將數值實體還原回漢字
$decoded = mb_decode_numericentity($encoded, $convmap, "UTF-8");

echo "解碼后：\n" . $decoded . "\n";
?>

運行結果：

 編碼后：
&#20320;&#22909;，&#19990;&#30028;！Hello World!
解碼后：
你好，世界！Hello World!

4. 結合URL 應用場景

有時候我們需要對URL 中帶有多字節字符的部分進行編碼，確保傳輸過程安全且符合規範。這裡展示一個簡易的例子，對URL 中的路徑部分使用數值實體編碼，再解碼回來。

 <?php
$convmap = [0x4E00, 0x9FFF, 0, 0xFFFF];

$url = "https://gitbox.net/路徑/測試";

// 只对路徑部分編碼
$parsed = parse_url($url);
$encoded_path = mb_encode_numericentity(urldecode($parsed['path']), $convmap, "UTF-8");

// 拼接編碼后的 URL
$encoded_url = $parsed['scheme'] . "://" . $parsed['host'] . $encoded_path;

echo "編碼后的 URL：\n" . $encoded_url . "\n";

// 解碼路徑
$decoded_path = mb_decode_numericentity($encoded_path, $convmap, "UTF-8");

// 還原完整 URL
$decoded_url = $parsed['scheme'] . "://" . $parsed['host'] . $decoded_path;

echo "解碼后的 URL：\n" . $decoded_url . "\n";
?>

輸出：

 編碼后的 URL：
https://gitbox.net/&#36710;&#x8def;/&#27979;&#35797;
解碼后的 URL：
https://gitbox.net/路徑/測試

5. 總結

mb_encode_numericentity可以將字符串中指定範圍內的字符轉換成數值實體編碼，有效保護多字節字符在傳輸或存儲時不被破壞。
mb_decode_numericentity負責把編碼後的數值實體還原回對應的多字節字符。
這兩個函數配合使用，在多語言環境下處理字符串編碼問題時非常方便，尤其適合處理帶有特殊字符的URL 或需要安全傳輸的文本數據。

掌握這兩個函數，可以大大提升多字節字符串處理的靈活性和安全性。