Entendendo a Função json_decode no PHP

A função json_decode no PHP transforma uma string formatada em JSON em um valor PHP nativo que você pode ler e manipular. É o equivalente inverso de json_encode, que faz o caminho contrário (valor PHP → string JSON). Você usa json_decode sempre que dados chegam como texto e você precisa trabalhar com eles: uma resposta de API REST, um payload de webhook, um arquivo de configuração ou uma coluna armazenada em um banco de dados.

Este capítulo aborda a assinatura da função, a diferença entre decodificar para um objeto e para um array associativo, como os dados aninhados se comportam, opções de profundidade e flags, e a forma correta de tratar entradas inválidas.

O que é JSON?

JSON (JavaScript Object Notation) é um formato leve de intercâmbio de dados baseado em texto, fácil de ler para humanos e de processar para máquinas. Ele representa dados como pares chave-valor (objetos, escritos {}) e listas ordenadas (arrays, escritos []), com strings, números, booleanos e null como valores escalares. Como quase todas as linguagens conseguem produzi-lo e consumi-lo, o JSON se tornou o formato padrão para APIs web. Veja a visão geral de PHP e JSON para uma perspectiva mais ampla.

Sintaxe

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

A função retorna o valor decodificado (array, stdClass, string, int, float, bool ou null), ou null em caso de falha.

Decodificando uma string JSON

O uso mais comum é decodificar um objeto JSON. Passe true como segundo argumento para obter um array associativo PHP de volta.

Exemplo da função json_decode em PHP

Aqui $json representa o nome, a idade e a cidade de uma pessoa. Com true, json_decode constrói um array PHP, portanto o resultado é:

Array
(
    [name] => John
    [age] => 30
    [city] => New York
)

Você então lê os valores com a sintaxe de array, por exemplo $array['name']. Veja arrays associativos para mais informações sobre essa estrutura de dados.

Usando o Segundo Parâmetro

O segundo parâmetro da função json_decode é opcional, mas é frequentemente usado para controlar o tipo da variável retornada. Se o segundo parâmetro for definido como true, json_decode retornará um array. Se o segundo parâmetro for definido como false (o padrão), json_decode retornará um objeto.

Exemplo da função json_decode em PHP com objetos

Quando $associative é false (ou omitido), json_decode retorna um objeto stdClass. Você lê os valores com a sintaxe de propriedade de objeto $object->name, $object->age, e assim por diante. Use essa forma quando preferir acesso no estilo de objeto ou quando o resultado for passado para código que espera objetos (veja classes e objetos PHP).

Decodificando JSON aninhado

JSON do mundo real geralmente é aninhado. json_decode lida com o aninhamento automaticamente: cada nível se torna um array aninhado (com true) ou um objeto aninhado (com false).

<?php

$json = '{"user":{"name":"John","roles":["admin","editor"]}}';
$data = json_decode($json, true);

echo $data['user']['name'];      // John
echo "\n";
echo $data['user']['roles'][0];  // admin

?>

Objetos JSON internos se tornam arrays internos, e arrays JSON ([...]) se tornam arrays indexados PHP que você pode percorrer com foreach.

Tratamento de Erros

Se a string de entrada passada para json_decode não for um JSON válido, a função retorna null. Porém, null também é um valor JSON válido, então verificar if ($array === null) não consegue distinguir entre um erro de decodificação e uma decodificação bem-sucedida do literal null. Para tratar erros corretamente, verifique json_last_error() ou use a flag JSON_THROW_ON_ERROR (PHP 7.3+).

Tratamento de erros de json_decode em PHP

A string acima está sem uma aspa de fechamento, então json_last_error() não é JSON_ERROR_NONE e a mensagem explica o que deu errado.

A partir do PHP 7.3, a opção mais limpa é a flag JSON_THROW_ON_ERROR, que lança uma JsonException em vez de retornar silenciosamente null:

<?php

try {
    $data = json_decode('{"invalid": }', true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo "Could not decode JSON: " . $e->getMessage();
}

?>

Isso permite tratar entradas malformadas com blocos try/catch padrão em vez de verificar o resultado manualmente após cada chamada.

Funções relacionadas

• json_encode — converte um valor PHP em uma string JSON.
• PHP e JSON — visão geral sobre como trabalhar com JSON em PHP.
• Referência JSON do PHP — lista completa das funções e constantes JSON do PHP.

Conclusão

A função json_decode no PHP é uma ferramenta poderosa para trabalhar com dados JSON. É rápida, confiável e fácil de usar. Ao entender os detalhes de json_decode e seu segundo parâmetro, você pode decodificar strings JSON com confiança e usar os dados resultantes em suas aplicações PHP.

Prática