| 常量 | 作用 |
| JSON_HEX_TAG | < > 轉為 \u003C \u003E (防 XSS) |
| JSON_HEX_QUOT | 雙引號轉 \u0022 |
| JSON_HEX_AMP | & 轉 \u0026 |
| JSON_HEX_APOS | 單引號轉 \u0027 |
| JSON_NUMERIC_CHECK | 數字字符串轉數字類型 (慎用,可能改變語義) |
| JSON_PRETTY_PRINT | 美化輸出 (縮進、換行) |
| JSON_UNESCAPED_SLASHES | 不轉義 / (URL 更易讀) |
| JSON_UNESCAPED_UNICODE | **中文不轉 Unicode** (強烈推薦,節省體積、可讀) |
| JSON_FORCE_OBJECT | 索引數組強制輸出為對象 {} |
| JSON_PRESERVE_ZERO_FRACTION | 浮點數保留 .0 (PHP 7.1+) |
| JSON_THROW_ON_ERROR | 錯誤拋出 Exception 而非返回 false (PHP 7.3+) |
實戰範例
$arr = ['id' => 1, 'name' => '張三', 'tags' => ['php', 'json'], 'price' => 99.0];
// 推薦生產配置
$flags = JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRESERVE_ZERO_FRACTION;
echo json_encode($arr, $flags);
// {"id":1,"name":"張三","tags":["php","json"],"price":99.0}
// 對象轉換
class User { public $name='李四'; public $age=25; }
echo json_encode(new User(), $flags);
// {"name":"李四","age":25}
// 只有 public 屬性會被編碼,private/protected 需實現 JsonSerializable
class User2 implements JsonSerializable {
private $pwd = 'secret';
public function jsonSerialize() {
return ['name' => $this->name]; // 僅暴露安全字段
}
}
解碼:json_decode()
mixed json_decode(string $json, bool $assoc = false, int $depth = 512, int $flags = 0): mixed
參數詳解
- $assoc = true:返回關聯數組而非
stdClass 對象 (推薦,數組操作更方便)。
- $depth:最大遞歸深度,防止異常嵌套導致棧溢出。
- $flags:
JSON_BIGINT_AS_STRING (大整數作字符串防精度丟失)、JSON_OBJECT_AS_ARRAY (同 assoc)、JSON_THROW_ON_ERROR。
實戰範例
$json = '{"a":1,"b":2,"nested":{"c":3}}';
var_dump(json_decode($json));
// object(stdClass)#1 (3) { ["a"]=>int(1) ["b"]=>int(2) ["nested"]=>object(stdClass)#2 (1) { ["c"]=>int(3) } }
var_dump(json_decode($json, true));
// array(3) { ["a"]=>int(1) ["b"]=>int(2) ["nested"]=>array(1) { ["c"]=>int(3) } }
// 大整數精度保護
$big = '{"id": 9007199254740993}'; // 超過 JS Number.MAX_SAFE_INTEGER
var_dump(json_decode($big, true, 512, JSON_BIGINT_AS_STRING));
// array(1) { ["id"]=>string(16) "9007199254740993" }
錯誤處理最佳實踐
function safe_json_decode($json, $assoc = true) {
if (!is_string($json)) throw new InvalidArgumentException('Input must be string');
$result = json_decode($json, $assoc, 512, JSON_THROW_ON_ERROR);
return $result;
}
try {
$data = safe_json_decode($apiResponse);
} catch (JsonException $e) {
log_error('JSON 解析失敗: ' . $e->getMessage());
// 降級處理
}
常見坑點與解決
| 問題 | 原因 | 解決 |
| 中文變 \uXXXX | 未加 JSON_UNESCAPED_UNICODE | 始終加上此 flag |
| 數字字符串變數字 | JSON_NUMERIC_CHECK | 移除該 flag,或預處理保留字符串 |
| 頂層數組變對象 | JSON_FORCE_OBJECT 或鍵非連續數字 | 確保數組鍵為 0..N-1 連續整數 |
| 循環引用報錯 | 對象屬性互相引用 | 實現 JsonSerializable 控制輸出 |
| 解碼返回 null | JSON 語法錯誤/編碼非 UTF-8/深度超限 | json_last_error_msg() 診斷、檢查編碼、增大 depth |
性能提示
- 大量數據序列化考慮
igbinary/msgpack (二進制、更快、更小)。
- 避免在循環中重複
json_encode 相同數據,預先編碼緩存。
- PHP 8.0+
json_encode 內部優化顯著,優先升級。
總結
**「編碼加 JSON_UNESCAPED_UNICODE,解碼加 true 返回數組,錯誤拋出 JsonException」** 是現代 PHP JSON 處理的黃金法則。掌握 flags 組合、實現 JsonSerializable、處理大整數精度,即可應對 99% 的 API 交互與存儲場景。
copyright ©
萬盛學電腦網 all rights reserved