萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 陣列與 JSON 互轉完整指南:json_encode、json_decode 進階用法與陷阱

前言

JSON(JavaScript Object Notation)是現代 Web 應用的標準資料交換格式。PHP 提供 json_encode() 與 json_decode() 兩大核心函數實現陣列/物件與 JSON 字串的雙向轉換。本文深入解析參數選項、資料結構對應規則、常見陷阱與最佳實踐。

一、json_encode() — PHP 值轉 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

關鍵 Flags 參數

常數說明建議
JSON_UNESCAPED_UNICODE不轉義 Unicode(中文直接輸出)強烈建議永遠開啟
JSON_UNESCAPED_SLASHES不轉義 /URL、路徑較易讀
JSON_PRETTY_PRINT格式化縮排輸出除錯/日誌用,正式環境關閉
JSON_NUMERIC_CHECK數字字串轉數值謹慎使用,可能導致大數精度遺失
JSON_PRESERVE_ZERO_FRACTION浮點數保留 .0API 需嚴格型別時
JSON_THROW_ON_ERROR錯誤拋出 JsonExceptionPHP 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() — JSON 字串轉 PHP 值

基本語法

json_decode(string $json, bool $associative = false, int $depth = 512, int $flags = 0): mixed

關鍵參數:$associative

<?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 取得陣列,操作一致、效能稍好、可序列化
?>

進階 Flags

常數說明
JSON_BIGINT_AS_STRING大整數以字串返回(避免 64 位整數精度遺失)
JSON_OBJECT_AS_ARRAY物件強制轉陣列(等同 $associative=true)
JSON_THROW_ON_ERROR解析失敗拋出 JsonException (PHP 7.3+)

三、常見陷阱與解決方案

1. 中文被轉義為 \uXXXX

<?php
echo json_encode(['msg' => '中文']); 
// {"msg":"\u4e2d\u6587"}

echo json_encode(['msg' => '中文'], JSON_UNESCAPED_UNICODE);
// {"msg":"中文"} ✓

2. 索引陣列 vs 關聯陣列輸出差異

<?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 (需括號)。

3. 深度超限導致截斷

<?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);

4. 錯誤處理:json_last_error()

<?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();
}
?>

5. 物件私有屬性不會被序列化

<?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 或分批處理
  • API 回應:JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES 平衡體積與相容性
  • 移除 JSON_PRETTY_PRINT 可減少 20-40% 傳輸體積

五、總結

PHP JSON 處理核心口訣:

  1. 編碼:json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)
  2. 解碼:json_decode($json, true, 512, JSON_THROW_ON_ERROR) (PHP 7.3+)
  3. 錯誤處理:永遠檢查 json_last_error() 或捕獲 JsonException
  4. 資料結構:明確區分「索引陣列→JSON 陣列」與「關聯陣列→JSON 物件」

遵循這些原則,能避開 90% 的 JSON 相關 Bug,構建穩健的 API 介接與資料儲存。

copyright © 萬盛學電腦網 all rights reserved