PHP json_decode()：把 JSON 解析为数组或对象

json_decode($json, true) 把 JSON 字符串转换为 PHP 值，每个 JSON 对象都变成一个关联数组。省略 true 时，JSON 对象会变成 stdClass 对象，需要用 -> 读取。无效的 JSON 会得到 null。

<?php
$json = '{"name": "Ada", "age": 36, "langs": ["php", "js"], "admin": true}';

$data = json_decode($json, true);   // associative array
echo $data['name'], "\n";
echo $data['langs'][1], "\n";

$obj = json_decode($json);          // stdClass object
echo $obj->name, "\n";
echo $obj->langs[0], "\n";

print_r($data);

输出：

Ada
js
Ada
php
Array
(
    [name] => Ada
    [age] => 36
    [langs] => Array
        (
            [0] => php
            [1] => js
        )

    [admin] => 1
)

无论选择哪种模式，JSON 数组总是变成 PHP 列表。反方向从 PHP 转成 JSON，请用 json_encode()。

关联数组还是对象：true 与 false

两种模式保存的数据相同；选择在你的代码中读起来更顺的那种即可。数组可以配合所有数组函数使用（array_column、array_map、isset($data['key'])），所以大多数代码都传 true。如果键不是合法的属性名，例如带连字符或者是数字，对象就需要使用花括号语法：

<?php
$json = '{"first-name": "Ada", "0": "zero", "address": {"city": "London"}}';

$arr = json_decode($json, true);
echo $arr['first-name'], ' ', $arr[0], ' ', $arr['address']['city'], "\n";

$obj = json_decode($json);
echo $obj->{'first-name'}, ' ', $obj->{'0'}, ' ', $obj->address->city, "\n";

var_dump($obj->address);

输出：

Ada zero London
Ada zero London
object(stdClass)#2 (1) {
  ["city"]=>
  string(6) "London"
}

第四个参数用于传入标志。JSON_OBJECT_AS_ARRAY 也会返回数组，但前提是第二个参数为 null（它的默认值）：json_decode($json, flags: JSON_OBJECT_AS_ARRAY) 返回数组，而 json_decode($json, false, 512, JSON_OBJECT_AS_ARRAY) 仍然返回对象。

遍历嵌套的 JSON

API 响应通常是一个对象里包含一个对象列表。解码一次，然后用 foreach 遍历，对可能缺失的字段使用 ??：

<?php
$json = <<<'JSON'
{
    "page": 1,
    "users": [
        {"id": 1, "name": "Ada", "email": "ada@example.com", "roles": ["admin", "editor"]},
        {"id": 2, "name": "Linus", "roles": []},
        {"id": 3, "name": "Grace", "email": "grace@example.com", "roles": ["editor"]}
    ]
}
JSON;

$data = json_decode($json, true);

foreach ($data['users'] as $user) {
    $email = $user['email'] ?? 'no email';
    $roles = $user['roles'] ? implode(', ', $user['roles']) : 'none';
    echo "#{$user['id']} {$user['name']} <$email> roles: $roles\n";
}

$names = array_column($data['users'], 'name', 'id');
print_r($names);

输出：

#1 Ada <ada@example.com> roles: admin, editor
#2 Linus <no email> roles: none
#3 Grace <grace@example.com> roles: editor
Array
(
    [1] => Ada
    [2] => Linus
    [3] => Grace
)

处理无效的 JSON

对于无效的 JSON，json_decode() 返回 null，但对于 JSON 文本 null，null 也是正确的结果，所以单凭 null 无法判断是否失败。json_last_error_msg() 会给出上一次调用的出错原因。要在一份很长的文档中找到出错位置，可以把它粘贴到 JSON 格式化工具 中，它会指出出错的那一行。更简洁的做法是使用 JSON_THROW_ON_ERROR，它会抛出 JsonException：

<?php
var_dump(json_decode('{"a": 1,}'));   // trailing comma
echo json_last_error_msg(), "\n";

var_dump(json_decode('null'));        // valid JSON, also null
echo json_last_error_msg(), "\n";

try {
    $data = json_decode("{'a': 1}", true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo 'Invalid JSON: ', $e->getMessage(), "\n";
}

输出：

NULL
Syntax error
NULL
No error
Invalid JSON: Syntax error

第三个参数 512 是最大嵌套深度（默认值）。使用命名参数可以跳过它：json_decode($json, true, flags: JSON_THROW_ON_ERROR)。

用 json_validate() 检查字符串是否为有效的 JSON

PHP 8.3 新增了 json_validate()。它只回答 true 或 false，不会构建解码后的数组，所以当你只需要一个“是”或“否”时，它比解码占用更少的内存，例如可以用来尽早拒绝无效的请求体：

<?php
$inputs = ['{"a": 1}', '[1, 2, 3]', '"text"', '{a: 1}', "{'a': 1}", ''];

foreach ($inputs as $input) {
    $ok = json_validate($input) ? 'valid' : 'invalid: ' . json_last_error_msg();
    echo str_pad(var_export($input, true), 14), $ok, "\n";
}

输出：

'{"a": 1}'    valid
'[1, 2, 3]'   valid
'"text"'      valid
'{a: 1}'      invalid: Syntax error
'{\'a\': 1}'  invalid: Syntax error
''            invalid: Syntax error

如果你反正都要使用这些数据，就跳过 json_validate()，直接用 JSON_THROW_ON_ERROR 解码：先验证会让字符串被解析两次。

读取 JSON 文件

用 file_get_contents() 读取文件，再解码字符串。这段代码会先写入 settings.json，这样才有文件可读：

<?php
file_put_contents('settings.json', '{"theme": "dark", "fontSize": 14, "plugins": ["git", "lint"]}');

$text = file_get_contents('settings.json');
if ($text === false) {
    exit("Cannot read settings.json\n");
}

$settings = json_decode($text, true, flags: JSON_THROW_ON_ERROR);
echo "Theme: {$settings['theme']}\n";
echo "Plugins: ", count($settings['plugins']), "\n";

// Change a value and write the file back
$settings['fontSize'] = 16;
file_put_contents('settings.json', json_encode($settings, JSON_PRETTY_PRINT));
echo file_get_contents('settings.json'), "\n";

输出：

Theme: dark
Plugins: 2
{
    "theme": "dark",
    "fontSize": 16,
    "plugins": [
        "git",
        "lint"
    ]
}

json_decode 为什么返回 null：常见原因

JSON 比 JavaScript 和 PHP 的数组语法更严格。下面每个字符串看起来都没问题，但每一个都返回 null。运行代码查看各自的原因，然后修正其中一个，再运行一次：

<?php
$cases = [
    'single quotes'   => "{'name': 'Ada'}",
    'unquoted key'    => '{name: "Ada"}',
    'trailing comma'  => '{"name": "Ada",}',
    'comment'         => '{"name": "Ada" /* admin */}',
    'byte order mark' => "\xEF\xBB\xBF" . '{"name": "Ada"}',
    'too deep'        => '[[["Ada"]]]',
];

foreach ($cases as $label => $json) {
    $depth = $label === 'too deep' ? 2 : 512;
    $result = json_decode($json, true, $depth);
    echo str_pad($label, 17), $result === null ? json_last_error_msg() : 'ok', "\n";
}

// Big integers lose precision unless you ask for strings
var_dump(json_decode('{"id": 12345678901234567890}', true)['id']);
var_dump(json_decode('{"id": 12345678901234567890}', true, 512, JSON_BIGINT_AS_STRING)['id']);

输出：

single quotes    Syntax error
unquoted key     Syntax error
trailing comma   Syntax error
comment          Syntax error
byte order mark  Syntax error
too deep         Maximum stack depth exceeded
float(1.2345678901234567E+19)
string(20) "12345678901234567890"

字节顺序标记在大多数编辑器中都看不见，它是 JSON 文件“看起来没问题”却无法解码的经典原因。解码前用 $text = preg_replace('/^\xEF\xBB\xBF/', '', $text); 把它去掉。