PHP JSON 編解碼完全指南：json_encode、json_decode 進階用法與常見陷阱

自 PHP 5.2 起內建 json_encode() 與 json_decode()，成為資料交換標準工具。本文系統整理編碼規則、陣列/物件轉換差異、類別序列化行為、解碼選項與常見錯誤，助你避開坑洞。

一、json_encode() 基礎與編碼規則

基本範例

<?php
$arr = array('a'=>1, 'b'=>2, 'c'=>3, 'd'=>4, 'e'=>5);
echo json_encode($arr); // {"a":1,"b":2,"c":3,"d":4,"e":5}

$obj = new stdClass();
$obj->body = 'another post';
$obj->id = 21;
$obj->approved = true;
$obj->favorite_count = 1;
$obj->status = null;
echo json_encode($obj); 
// {"body":"another post","id":21,"approved":true,"favorite_count":1,"status":null}
?>

⚠️ 必須為 UTF-8 編碼

json_encode() 參數必須為 UTF-8，否則中文會變成空字串或 null。若資料來源為 GB2312、Big5 或 ISO-8859-1，請先用 mb_convert_encoding() 或 iconv() 轉碼。

二、索引陣列 vs 關聯陣列：輸出格式差異

JavaScript 無關聯陣列概念，PHP 依鍵名類型決定 JSON 結構：

強制輸出為 Object

$arr = ['one', 'two', 'three'];
echo json_encode((object)$arr);           // {"0":"one","1":"two","2":"three"}
echo json_encode($arr, JSON_FORCE_OBJECT); // 同結果

三、類別序列化：僅公開屬性會被編碼

class Foo {
    const ERROR_CODE = '404';
    public $public_ex = 'this is public';
    private $private_ex = 'this is private!';
    protected $protected_ex = 'this should be protected';
    public function getErrorCode() { return self::ERROR_CODE; }
}
$foo = new Foo;
echo json_encode($foo); // {"public_ex":"this is public"}

注意：常數、私有/受保護屬性、方法均不會被編碼。若需完整序列化，請實作 JsonSerializable 介面（PHP 5.4+）。

四、json_decode() 解碼選項與回傳類型

$json = '{"a":1,"b":2,"c":3,"d":4,"e":5}';

// 預設回傳 stdClass 物件
$obj = json_decode($json);
echo $obj->a; // 1

// 第二參數 true 強制回傳關聯陣列
$arr = json_decode($json, true);
echo $arr['a']; // 1

五、常見 JSON 格式錯誤（導致回傳 null）

其他陷阱

• json_decode("Hello World") 回傳 null：JSON 須為物件或陣列結構，純字串/數值無效。
• 深度巢狀超過預設 512 層會失敗，可用第三參數 $depth 調整。
• 大整數（超過 PHP_INT_MAX）會轉為浮點數，精度可能損失，建議以字串傳遞 ID。

六、實務建議

1. API 輸出統一用 json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)，避免中文被轉義、斜線被轉義。
2. 解碼時習慣加 true 取得陣列，配合 isset()、array_key_exists() 更安全。
3. 錯誤處理：json_last_error()、json_last_error_msg() 取得詳細錯誤資訊。

更多 PHP 字串處理與資料交換技巧，請參考專題：《PHP 字串用法總結》、《PHP 陣列操作技巧大全》。