PHP JSON

JSON (JavaScript Object Notation) é um formato leve de intercâmbio de dados baseado em texto. É a forma mais comum de enviar e receber dados entre um backend PHP e um navegador, um aplicativo móvel ou outro serviço web (a maioria das APIs REST usa JSON). Este guia cobre tudo o que você precisa para trabalhar com JSON em PHP: transformar dados PHP em JSON com json_encode, converter JSON de volta em dados PHP com json_decode, formatar a saída e tratar erros com segurança.

O PHP inclui suporte a JSON em seu núcleo (a extensão ext-json é empacotada e habilitada por padrão desde o PHP 8.0), portanto não há nada a instalar.

Como o JSON se parece

O JSON representa dados como pares chave-valor dentro de objetos ({ }) e listas ordenadas dentro de arrays ([ ]). Os valores podem ser strings, números, booleanos, null, arrays ou objetos aninhados:

{
  "name": "John",
  "age": 30,
  "active": true,
  "roles": ["admin", "editor"]
}

As duas funções que você usará quase sempre são:

• json_encode($value) — valor PHP → string JSON (serializar).
• json_decode($json) — string JSON → valor PHP (desserializar).

Codificação: PHP para JSON com json_encode

json_encode() converte um valor PHP — tipicamente um array ou objeto — em uma string JSON.

Codificando um array associativo

Um array associativo torna-se um objeto JSON, enquanto um array indexado (chaves inteiras sequenciais começando em 0) torna-se um array JSON:

<?php

echo json_encode(["red", "green", "blue"]);
// ["red","green","blue"]

?>

Formatando a saída

Por padrão, json_encode produz JSON compacto em uma única linha, o que é ideal para envio pela rede. Quando você deseja uma saída legível por humanos (para registro ou depuração), passe o flag JSON_PRETTY_PRINT. Os flags são combinados com o operador bit a bit |:

<?php

$data = [
    "user" => ["name" => "Jane", "roles" => ["admin", "editor"]],
    "active" => true,
];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

?>

Isso imprime JSON bem indentado:

{
    "user": {
        "name": "Jane",
        "roles": [
            "admin",
            "editor"
        ]
    },
    "active": true
}

Outros flags úteis: JSON_UNESCAPED_SLASHES (mantém / em vez de \/) e JSON_UNESCAPED_UNICODE (mantém caracteres como é em vez de é).

Decodificação: JSON para PHP com json_decode

json_decode() converte uma string JSON de volta em um valor PHP. Por padrão, retorna objetos, mas passar true como segundo argumento retorna arrays associativos — que geralmente são mais fáceis de iterar:

Sem o argumento true, você obtém um objeto stdClass e acessa os valores com a notação de seta -> em vez de [ ]:

Use true quando quiser um array; omita quando preferir a sintaxe de objeto. Ambos contêm os mesmos dados.

Codificando um objeto personalizado

json_encode também funciona em objetos. Quando você precisa construir uma estrutura JSON dinamicamente, o objeto stdClass vazio permite anexar propriedades dinamicamente. (Para classes completas, consulte PHP Classes e Objetos.)

As propriedades públicas de qualquer objeto são incluídas automaticamente; propriedades privadas e protegidas são ignoradas, a menos que a classe implemente a interface JsonSerializable.

Tratando erros

A análise de JSON pode falhar — uma string malformada, uma aspas não fechada ou uma vírgula no final podem quebrar a decodificação. Quando json_decode falha, retorna null, então você deve distinguir um valor real null de um erro. Verifique json_last_error() (ou leia json_last_error_msg() para uma mensagem legível por humanos):

<?php

$badJson = '{invalid}';
$result = json_decode($badJson);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "JSON error: " . json_last_error_msg();
    // JSON error: Syntax error
}

?>

Desde o PHP 7.3, você pode passar o flag JSON_THROW_ON_ERROR para fazer ambas as funções lançarem uma JsonException, que se encaixa perfeitamente em blocos try/catch:

<?php

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

?>

Nota: json_decode tem um limite de profundidade (512 níveis por padrão, o terceiro argumento). JSON muito profundamente aninhado falhará com um erro JSON_ERROR_DEPTH, a menos que você aumente esse limite.

Caso de uso comum: lendo o corpo de uma requisição JSON

Quando um cliente envia JSON para um endpoint PHP (como a maioria das APIs faz), o corpo chega como entrada bruta em vez de $_POST. Leia-o com php://input e decodifique:

<?php

$body = file_get_contents("php://input");
$data = json_decode($body, true);

// echo a JSON response back to the client
header("Content-Type: application/json");
echo json_encode(["received" => $data]);

?>

Conclusão

JSON é o formato padrão para troca de dados em aplicações web modernas, e o PHP torna esse trabalho simples:

• Use json_encode para transformar arrays e objetos em JSON; adicione JSON_PRETTY_PRINT para saída legível.
• Use json_decode para converter JSON de volta em PHP — passe true para um array, omita para um objeto.
• Sempre verifique erros com json_last_error() ou JSON_THROW_ON_ERROR antes de confiar nos dados decodificados.

Com essas ferramentas, você pode enviar e receber JSON com confiança entre seu código PHP, bancos de dados, navegadores e serviços web externos.

Prática