Codificação JSON com PHP

JSON (JavaScript Object Notation) é um formato leve de intercâmbio de dados baseado em texto, fácil de ler para humanos e fácil de analisar por máquinas. É o formato padrão para envio de dados entre um servidor e o navegador, para APIs REST e para arquivos de configuração. Em PHP, json_encode() recebe um valor PHP — um escalar, um array ou um objeto — e retorna sua representação JSON como uma string.

Esta página aborda a sintaxe, os $flags mais úteis, como os tipos PHP se mapeiam para JSON e como detectar erros de codificação. Para fazer o caminho inverso (string JSON → valor PHP), consulte json_decode().

Sintaxe

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

Retorna uma string codificada em JSON em caso de sucesso, ou false em caso de falha (por exemplo, quando a entrada contém UTF-8 malformado).

Parâmetros

• $value — o valor a ser codificado. Pode ser de qualquer tipo exceto resource. Todos os dados de string devem ser UTF-8 válido.
• $flags (opcional) — uma máscara de bits que personaliza a saída. Os mais comuns:
  • JSON_PRETTY_PRINT — adiciona espaços em branco e indentação para que a saída seja legível.
  • JSON_UNESCAPED_UNICODE — mantém caracteres multibyte (é, ñ, 日) literais em vez de escapá-los para \uXXXX.
  • JSON_UNESCAPED_SLASHES — deixa / sem escape (o PHP escapa como \/ por padrão).
  • JSON_FORCE_OBJECT — codifica um array sequencial como um objeto JSON ({}) em vez de um array ([]).
  • JSON_THROW_ON_ERROR — lança uma JsonException em caso de falha em vez de retornar false (PHP 7.3+).
  • Combine flags com o operador bitwise OR: JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE.
• $depth (opcional) — a profundidade máxima de aninhamento. Deve ser maior que 0. O padrão de 512 é suficiente para dados normais.

Como os tipos PHP se mapeiam para JSON

Exemplos

Codificando um array

Um array associativo PHP torna-se um objeto JSON; as chaves tornam-se nomes de propriedades.

Saída:

{"a":1,"b":2,"c":3,"d":4,"e":5}

Codificando um objeto

As propriedades públicas de um objeto são codificadas; propriedades private e protected são ignoradas.

Saída:

{"name":"John Doe","age":35,"city":"New York"}

Formatação legível e Unicode sem escape

Por padrão, a saída é compacta, em uma linha, e caracteres não-ASCII são escapados (então é torna-se é). Duas flags tornam a saída amigável para humanos:

<?php

$data = [
    "name"  => "Café",
    "tags"  => ["php", "json"],
    "price" => 9.50,
];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

?>

Saída:

{
    "name": "Café",
    "tags": [
        "php",
        "json"
    ],
    "price": 9.5
}

Note que 9.50 é emitido como 9.5 — zeros finais em floats são removidos. Use JSON_PRESERVE_ZERO_FRACTION se precisar que 9.0 permaneça como float em vez de virar 9.

Tratando erros

Se json_encode() retornar false, algo deu errado — na maioria das vezes UTF-8 malformado em uma string. Verifique json_last_error_msg(), ou passe JSON_THROW_ON_ERROR para obter uma exceção.

<?php

$value = json_encode("\xB1\x31"); // invalid UTF-8 byte sequence

if ($value === false) {
    echo "Encoding failed: " . json_last_error_msg();
}

?>

Saída:

Encoding failed: Malformed UTF-8 characters, possibly incorrectly encoded

Casos de uso comuns

• Retornando dados de uma API. Defina o cabeçalho e exiba o array codificado:

  header('Content-Type: application/json');
  echo json_encode(['status' => 'ok', 'items' => $items]);

  Copiar

• Armazenando dados estruturados em um arquivo ou em uma coluna de texto de banco de dados em vez de serialize(). JSON é portável entre linguagens; serialize() é exclusivo do PHP.

• Passando dados para JavaScript renderizado na página, pois JSON válido é uma sintaxe válida de objeto JavaScript.

Conclusão

json_encode() transforma arrays e objetos PHP em uma string JSON compacta e portável. Use JSON_PRETTY_PRINT e JSON_UNESCAPED_UNICODE quando um humano for ler a saída, proteja-se contra entradas malformadas verificando o valor de retorno ou usando JSON_THROW_ON_ERROR, e lembre-se de que apenas propriedades públicas de objetos são codificadas. Para analisar JSON de volta para PHP, use json_decode(); para uma visão geral mais ampla, consulte Trabalhando com JSON em PHP.

Prática