前後端分離、API 對接 Java/JS 時,常需將中文轉為 \uXXXX Unicode 轉義序列,或將含 Unicode 轉義的字串還原為可讀中文。本文提供純 PHP 實作的 UnicodeCodec 類,無需 mbstring/iconv 擴充,支援 BMP 平面(U+0000~U+FFFF)與補充平面(Emoji U+10000+)。
<?php
class UnicodeCodec
{
/**
* 中文/任意字串 → Unicode 轉義 (\uXXXX 或 \u{XXXXX})
* @param string $str 輸入字串(UTF-8 編碼)
* @param bool $useBrace true=ES2015 \u{1F600} 格式,false=傳統 \uXXXX
* @return string
*/
public static function encode(string $str, bool $useBrace = false): string
{
$len = mb_strlen($str, 'UTF-8');
$out = '';
for ($i = 0; $i < $len; $i++) {
$ch = mb_substr($str, $i, 1, 'UTF-8');
$cp = mb_ord($ch, 'UTF-8'); // PHP 7.2+
if ($cp <= 0xFFFF) {
$out .= $useBrace
? sprintf('\\u{%04X}', $cp)
: sprintf('\\u%04X', $cp);
} else {
// 補充平面:ES2015 必須用 \u{XXXXX},傳統格式需拆成 surrogate pair
$out .= $useBrace
? sprintf('\\u{%X}', $cp)
: self::toSurrogatePair($cp);
}
}
return $out;
}
/**
* Unicode 轉義 → UTF-8 字串
* 支援 \uXXXX、\u{XXXXX}、\UXXXXXXXX 格式
*/
public static function decode(string $str): string
{
return preg_replace_callback(
'/\\\\u(?:{([0-9A-Fa-f]+)}|([0-9A-Fa-f]{4}))|\\\\U([0-9A-Fa-f]{8})/',
function ($m) {
$hex = $m[1] ?? $m[2] ?? $m[3];
$cp = hexdec($hex);
if ($cp > 0x10FFFF) return ''; // 非法碼位
return mb_chr($cp, 'UTF-8'); // PHP 7.2+
},
$str
);
}
/** 將 >0xFFFF 碼位轉為 UTF-16 Surrogate Pair (\uXXXX\uXXXX) */
private static function toSurrogatePair(int $cp): string
{
$cp -= 0x10000;
$high = 0xD800 | (($cp >> 10) & 0x3FF);
$low = 0xDC00 | ($cp & 0x3FF);
return sprintf('\\u%04X\\u%04X', $high, $low);
}
}
<?php
$original = '測試😀Emoji'; // 含 BMP 中文 + 補充平面 Emoji
// 編碼
$escaped = UnicodeCodec::encode($original);
echo $escaped . PHP_EOL;
// 輸出:\u6E2C\u8A66\uD83D\uDE00Emoji (傳統格式)
$escapedBrace = UnicodeCodec::encode($original, true);
echo $escapedBrace . PHP_EOL;
// 輸出:\u{6E2C}\u{8A66}\u{1F600}Emoji (ES2015 格式)
// 解碼
echo UnicodeCodec::decode($escaped) . PHP_EOL; // 測試😀Emoji
echo UnicodeCodec::decode($escapedBrace) . PHP_EOL; // 測試😀Emoji
// 實際場景:JSON 字串手動構建
$json = '{"msg": "' . UnicodeCodec::encode('中文訊息') . '"}';
// 送給 Java/JS 解析均正常
| 場景 | json_encode($arr, JSON_UNESCAPED_UNICODE) | UnicodeCodec::encode() |
|---|---|---|
| 輸出格式 | 原生中文 UTF-8 | \uXXXX 轉義 |
| 適用對象 | 現代前端、API 直讀 | Java \uXXXX、JS eval、舊系統相容 |
| Emoji 支援 | 直接輸出 😀 | 可選 \u{1F600} 或 surrogate pair |
| 效能 | C 底層,極快 | PHP 迴圈,較慢(長字串建議分段) |
mb_ord/mb_chr 會拋錯;來源若為 GBK/Big5 請先 iconv('GBK', 'UTF-8', $str)。mb_ord/mb_chr,可用 json_encode('"' . $ch . '"') 繞道取碼位,或升級 PHP。