萬盛學電腦網

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

PHP JSON 處理完全指南:json_encode/json_decode 參數詳解、對象轉換、錯誤處理與實戰技巧

編碼:json_encode()

string json_encode(mixed $value, int $flags = 0, int $depth = 512): string|false

常用 flags 位掩碼

實戰範例

$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());
    // 降級處理
}

常見坑點與解決

常量作用
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+)
問題原因解決
中文變 \uXXXX未加 JSON_UNESCAPED_UNICODE始終加上此 flag
數字字符串變數字JSON_NUMERIC_CHECK移除該 flag,或預處理保留字符串
頂層數組變對象JSON_FORCE_OBJECT 或鍵非連續數字確保數組鍵為 0..N-1 連續整數
循環引用報錯對象屬性互相引用實現 JsonSerializable 控制輸出
解碼返回 nullJSON 語法錯誤/編碼非 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