Referência de Funções JSON do PHP

JSON (JavaScript Object Notation) é um formato leve de intercâmbio de dados baseado em texto. Por ser fácil de ler para humanos e trivial para máquinas analisarem, tornou-se a maneira padrão de enviar dados entre um servidor e um navegador, e entre serviços web (APIs REST).

O PHP vem com um pequeno conjunto de funções integradas — coletivamente a extensão JSON — que convertem valores PHP em texto JSON e vice-versa. Esta página é uma referência rápida para essas funções e as constantes de opção mais úteis. Para um tutorial passo a passo, consulte PHP JSON.

Quando usaria JSON em PHP?

Você utiliza essas funções sempre que dados precisam sair do PHP como texto ou chegar como texto:

• Retornar dados de um endpoint de API (echo json_encode($data);).
• Ler um corpo de requisição ou um arquivo de configuração escrito em JSON.
• Armazenar um valor estruturado (um array de configurações, por exemplo) em uma única coluna de banco de dados ou chave de cache.
• Comunicar-se com um serviço web de terceiros que usa JSON.

A extensão JSON está habilitada por padrão no PHP 5.2 e posteriores, e faz parte do núcleo no PHP 8.0+, portanto nenhuma instalação é necessária.

Funções JSON

json_encode()

json_encode() serializa um valor PHP em uma string formatada em JSON.

<?php

$data = [
    "name"  => "Ada",
    "age"   => 36,
    "langs" => ["PHP", "JS"],
];

echo json_encode($data);

?>

Saída:

{"name":"Ada","age":36,"langs":["PHP","JS"]}

Observe como um array associativo se torna um objeto JSON {}, enquanto um array de lista (["PHP","JS"]) se torna um array JSON []. Veja a referência completa em json_encode().

Formatando a saída

Passe a opção JSON_PRETTY_PRINT para tornar o resultado legível:

<?php

$data = ["name" => "Ada", "langs" => ["PHP", "JS"]];

echo json_encode($data, JSON_PRETTY_PRINT);

?>

Saída:

{
    "name": "Ada",
    "langs": [
        "PHP",
        "JS"
    ]
}

json_decode()

json_decode() analisa uma string JSON e a transforma em um valor PHP. Por padrão, retorna objetos (stdClass); passe true como segundo argumento para obter arrays associativos em vez disso.

<?php

$json = '{"name":"Ada","age":36,"langs":["PHP","JS"]}';

// Decode as an associative array
$data = json_decode($json, true);

echo $data["name"];   // Ada
echo "\n";
echo $data["langs"][0]; // PHP

?>

Saída:

Ada
PHP

Veja a referência completa em json_decode().

Tratamento de erros

json_encode() retorna false e json_decode() retorna null quando algo dá errado (UTF-8 inválido, erro de sintaxe na entrada ou aninhamento mais profundo que o limite de profundidade). Como null também é um valor decodificado válido, sempre verifique json_last_error() em vez de apenas testar null.

<?php

$bad = '{"name": "Ada", }';   // trailing comma is invalid JSON

$result = json_decode($bad, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "Invalid JSON: " . json_last_error_msg();
} else {
    echo "Decoded fine.";
}

?>

Saída:

Invalid JSON: Syntax error

No PHP 7.3+ você pode passar o sinalizador JSON_THROW_ON_ERROR para ambas as funções para obter uma JsonException em vez de inspecionar o código de erro manualmente.

Constantes de opção comuns

Essas constantes de bitmask são passadas no argumento $options de json_encode() (e algumas se aplicam a json_decode()):

• JSON_PRETTY_PRINT — formata a saída com espaço em branco e indentação.
• JSON_UNESCAPED_SLASHES — deixa os caracteres / sem escape (http:// em vez de http:\/\/).
• JSON_UNESCAPED_UNICODE — mantém caracteres multibyte como estão, em vez de escapes \uXXXX.
• JSON_THROW_ON_ERROR — lança uma JsonException em caso de falha (PHP 7.3+).
• JSON_FORCE_OBJECT — sempre emite um objeto JSON, mesmo para um array sequencial.

Combine-os com o operador OR bit a bit:

<?php

$data = ["site" => "https://www.w3docs.com", "name" => "café"];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

?>

Saída:

{
    "site": "https://www.w3docs.com",
    "name": "café"
}

Tópicos relacionados

• PHP JSON — a introdução completa do tutorial.
• Arrays PHP e Arrays Associativos — as estruturas que mapeiam mais naturalmente para JSON.
• Funções PHP — como encapsular encode/decode em seus próprios auxiliares.

Prática