JSON(JavaScript Object Notation)是現代 Web 應用的標準資料交換格式。PHP 提供 json_encode() 與 json_decode() 兩大核心函數實現陣列/物件與 JSON 字串的雙向轉換。本文深入解析參數選項、資料結構對應規則、常見陷阱與最佳實踐。
json_encode(mixed $value, int $flags = 0, int $depth = 512): string|false
| PHP 型別 | JSON 型別 | 說明 |
|---|---|---|
| 索引陣列 (連續數字鍵 0..n) | 陣列 [] | ["a", "b"] |
| 關聯陣列 / 非連續鍵 | 物件 {} | {"a":1, "b":2} |
| 物件 (stdClass / 自訂類別) | 物件 {} | 公開屬性序列化 |
| 字串、整數、浮點數、布林、null | 對應 JSON 基本型別 | null → null |
| resource、closure | 不可序列化 | 會觸發警告並返回 false |
| 常數 | 說明 | 建議 |
|---|---|---|
JSON_UNESCAPED_UNICODE | 不轉義 Unicode(中文直接輸出) | 強烈建議永遠開啟 |
JSON_UNESCAPED_SLASHES | 不轉義 / | URL、路徑較易讀 |
JSON_PRETTY_PRINT | 格式化縮排輸出 | 除錯/日誌用,正式環境關閉 |
JSON_NUMERIC_CHECK | 數字字串轉數值 | 謹慎使用,可能導致大數精度遺失 |
JSON_PRESERVE_ZERO_FRACTION | 浮點數保留 .0 | API 需嚴格型別時 |
JSON_THROW_ON_ERROR | 錯誤拋出 JsonException | PHP 7.3+,配合 try-catch 處理 |
<?php
$data = [
'user' => [
'id' => 123,
'name' => '王小明',
'tags' => ['vip', 'beta'],
'settings' => (object)['theme' => 'dark', 'lang' => 'zh-TW']
],
'items' => [
['id' => 1, 'price' => 99.5],
['id' => 2, 'price' => 199.0]
]
];
// 推薦:生產環境輸出
echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
// 除錯:易讀格式
echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
// 強制索引陣列輸出為物件
$arr = ['a', 'b', 'c'];
echo json_encode($arr); // ["a","b","c"]
echo json_encode($arr, JSON_FORCE_OBJECT); // {"0":"a","1":"b","2":"c"}
?>
json_decode(string $json, bool $associative = false, int $depth = 512, int $flags = 0): mixed
<?php
$json = '{"name": "John", "age": 30, "skills": ["PHP", "JS"]}';
// $associative = false (預設) → 回傳 stdClass 物件
$obj = json_decode($json);
echo $obj->name; // John
echo $obj->skills[0]; // PHP
// $associative = true → 回傳關聯陣列
$arr = json_decode($json, true);
echo $arr['name']; // John
echo $arr['skills'][0]; // PHP
// 建議:永遠使用 true 取得陣列,操作一致、效能稍好、可序列化
?>
| 常數 | 說明 |
|---|---|
JSON_BIGINT_AS_STRING | 大整數以字串返回(避免 64 位整數精度遺失) |
JSON_OBJECT_AS_ARRAY | 物件強制轉陣列(等同 $associative=true) |
JSON_THROW_ON_ERROR | 解析失敗拋出 JsonException (PHP 7.3+) |
<?php
echo json_encode(['msg' => '中文']);
// {"msg":"\u4e2d\u6587"}
echo json_encode(['msg' => '中文'], JSON_UNESCAPED_UNICODE);
// {"msg":"中文"} ✓
<?php
$indexed = ['a', 'b', 'c'];
$assoc = ['0' => 'a', '1' => 'b', '2' => 'c']; // 字串鍵
$gap = [0 => 'a', 2 => 'c']; // 非連續
echo json_encode($indexed); // ["a","b","c"] → JSON 陣列
echo json_encode($assoc); // {"0":"a","1":"b","2":"c"} → JSON 物件
echo json_encode($gap); // {"0":"a","2":"c"} → JSON 物件
前端接收時注意: JSON 陣列用 data[0],JSON 物件用 data['0'] 或 data.0 (需括號)。
<?php
// 預設深度 512,超深結構會被截斷為 null
$deep = 'a';
for ($i = 0; $i < 600; $i++) $deep = [$deep];
json_encode($deep); // 返回 false,觸發警告
// 解決:增加 depth 參數 (PHP 5.5+)
json_encode($deep, 0, 1000);
<?php
$json = '{invalid json}';
$data = json_decode($json);
if (json_last_error() !== JSON_ERROR_NONE) {
echo 'JSON 錯誤:' . json_last_error_msg();
// JSON_ERROR_SYNTAX, JSON_ERROR_UTF8, JSON_ERROR_DEPTH, etc.
}
// PHP 7.3+ 推薦:拋出例外
try {
$data = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
echo '解析失敗:' . $e->getMessage();
}
?>
<?php
class User {
public $name = 'John';
private $password = 'secret';
protected $email = 'john@example.com';
}
echo json_encode(new User());
// {"name":"John"} 只有 public 屬性
// 解決:實作 JsonSerializable 介面 (PHP 5.4+)
class User implements JsonSerializable {
public function jsonSerialize() {
return [
'name' => $this->name,
'email' => $this->email
];
}
}
echo json_encode(new User());
// {"name":"John","email":"john@example.com"}
JsonStreamingParser 或分批處理JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES 平衡體積與相容性JSON_PRETTY_PRINT 可減少 20-40% 傳輸體積PHP JSON 處理核心口訣:
json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)json_decode($json, true, 512, JSON_THROW_ON_ERROR) (PHP 7.3+)json_last_error() 或捕獲 JsonException遵循這些原則,能避開 90% 的 JSON 相關 Bug,構建穩健的 API 介接與資料儲存。