PHP json_encode(): converter arrays e objetos em JSON

Q: Como converto um array PHP em JSON?

Passe-o para o jsonencode(): jsonencode(['name' => 'Ada', 'age' => 36]) retorna {"name":"Ada","age":36}. Um array com chaves 0, 1, 2... em ordem vira um array JSON: json_encode(['a', 'b']) retorna ["a","b"].

Q: Como formato o JSON (pretty print) no PHP?

Adicione a flag JSONPRETTYPRINT: jsonencode($data, JSONPRETTYPRINT) indenta com 4 espaços e coloca cada valor numa linha própria. Combine flags com |, por exemplo JSONPRETTYPRINT | JSONUNESCAPED_UNICODE.

Q: Como faço o json_encode gerar {} em vez de [] para um array vazio?

Um array PHP vazio sempre vira []. Use new stdClass() ou (object) [] para um objeto vazio, ou a flag JSONFORCEOBJECT, que transforma todos os arrays do valor em objetos.

json_encode($value) retorna o texto JSON de um valor PHP. Um array associativo vira um objeto JSON, uma lista (chaves 0, 1, 2...) vira um array JSON, e strings, números, true, false e null viram os equivalentes em JSON.

<?php
$user = [
    'name'    => 'Ada',
    'age'     => 36,
    'langs'   => ['php', 'js'],
    'admin'   => true,
    'manager' => null,
];

$json = json_encode($user);
echo $json, "\n";
echo gettype($json), "\n";

Saída:

{"name":"Ada","age":36,"langs":["php","js"],"admin":true,"manager":null}
string

O resultado é uma string simples, pronta para enviar a um navegador, guardar num arquivo ou numa coluna do banco, ou passar para outro programa. Para transformar JSON de volta em PHP, use o json_decode().

Formatar o JSON (pretty print)

O json_encode() recebe flags como segundo argumento. JSON_PRETTY_PRINT adiciona quebras de linha e indentação de 4 espaços, o que você quer num arquivo de configuração ou num log de depuração. Combine várias flags com |:

<?php
$config = [
    'app'   => 'shop',
    'debug' => false,
    'db'    => ['host' => 'localhost', 'port' => 3306],
    'tags'  => [],
];

echo json_encode($config, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), "\n";

Saída:

{
    "app": "shop",
    "debug": false,
    "db": {
        "host": "localhost",
        "port": 3306
    },
    "tags": []
}

Manter legíveis o japonês e outros textos UTF-8

Por padrão, o json_encode() escreve todo caractere fora do ASCII como um escape \u e coloca uma barra invertida antes de cada /. Os dois são JSON válido e decodificam de volta para o mesmo texto, mas deixam a saída difícil de ler e mais longa. JSON_UNESCAPED_UNICODE mantém os caracteres, e JSON_UNESCAPED_SLASHES mantém as URLs como estão:

<?php
$item = ['name' => 'りんご', 'price' => 120, 'url' => 'https://example.com/fruit/apple'];

echo json_encode($item), "\n";
echo json_encode($item, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

Saída:

{"name":"\u308a\u3093\u3054","price":120,"url":"https:\/\/example.com\/fruit\/apple"}
{"name":"りんご","price":120,"url":"https://example.com/fruit/apple"}

Se o texto em japonês (ou com acentos) aparecer embaralhado depois de decodificado, o problema não são os escapes: a string não era UTF-8 desde o início. O json_encode() só aceita UTF-8 e retorna false para qualquer outra coisa, como mostra a seção sobre erros.

Quando um array vira objeto em vez de lista

Um array PHP só vira um array JSON quando as chaves são exatamente 0, 1, 2... em ordem. Quaisquer outras chaves o transformam num objeto JSON. Isso pega muita gente depois de unset() ou array_filter(), que deixam buracos nas chaves:

<?php
$fruits = ['apple', 'banana', 'cherry'];
unset($fruits[1]);

echo json_encode($fruits), "\n";                // keys 0, 2: an object
echo json_encode(array_values($fruits)), "\n";  // renumbered: a list

echo json_encode([1 => 'a', 2 => 'b']), "\n";   // does not start at 0

echo json_encode([]), "\n";                     // empty array: always []
echo json_encode(new stdClass()), "\n";         // empty object
echo json_encode(['a', 'b'], JSON_FORCE_OBJECT), "\n";

Saída:

{"0":"apple","2":"cherry"}
["apple","cherry"]
{"1":"a","2":"b"}
[]
{}
{"0":"a","1":"b"}

Chame array_values() antes de codificar sempre que o código que recebe esperar uma lista. Se ele espera um objeto que pode estar vazio, use new stdClass() ou (object) $array para que um valor vazio ainda saia como {}.

Codificar um objeto e controlar o JSON dele com JsonSerializable

Um objeto simples é codificado só com as propriedades públicas; as protegidas e privadas são puladas. Para decidir exatamente como um objeto fica em JSON, implemente a interface JsonSerializable e retorne os dados em jsonSerialize():

<?php
class User
{
    public string $name = 'Ada';
    public ?string $nick = null;
    private string $password = 'secret';   // never encoded
}

echo json_encode(new User()), "\n";

// A date object encodes its internals, which is rarely what an API wants
echo json_encode(new DateTimeImmutable('2026-03-14 09:30')), "\n";

class Order implements JsonSerializable
{
    public function __construct(
        private int $id,
        private float $total,
        private DateTimeImmutable $created,
    ) {}

    public function jsonSerialize(): array
    {
        return [
            'id'      => $this->id,
            'total'   => $this->total,
            'created' => $this->created->format(DATE_ATOM),
        ];
    }
}

$order = new Order(7, 19.5, new DateTimeImmutable('2026-03-14 09:30'));
echo json_encode($order, JSON_PRETTY_PRINT), "\n";

Saída:

{"name":"Ada","nick":null}
{"date":"2026-03-14 09:30:00.000000","timezone_type":3,"timezone":"UTC"}
{
    "id": 7,
    "total": 19.5,
    "created": "2026-03-14T09:30:00+00:00"
}

Um backed enum como enum Status: string é codificado como o seu valor ("active"). Um enum puro não tem valor, então o json_encode() falha nele com "Non-backed enums have no default serialization".

Números, floats e strings numéricas

Inteiros e floats são escritos como números JSON, e strings continuam strings mesmo quando contêm dígitos. Três flags mudam isso:

<?php
echo json_encode(['price' => 10.0]), "\n";                               // 10.0 loses its .0
echo json_encode(['price' => 10.0], JSON_PRESERVE_ZERO_FRACTION), "\n";
echo json_encode(0.1 + 0.2), "\n";                                       // full float precision

echo json_encode(['qty' => '3', 'id' => '007']), "\n";
echo json_encode(['qty' => '3', 'id' => '007'], JSON_NUMERIC_CHECK), "\n";

Saída:

{"price":10}
{"price":10.0}
0.30000000000000004
{"qty":"3","id":"007"}
{"qty":3,"id":7}

JSON_NUMERIC_CHECK converte toda string numérica, então um ID como "007" ou um código postal como "01234" perde os zeros à esquerda. Converta os campos que você quer com (int) em vez de usá-la num array inteiro.

json_encode retorna false: encontrar o erro

O json_encode() retorna false quando não consegue codificar o valor. As causas comuns são uma string que não é UTF-8 válido (texto lido de um arquivo antigo ou de um banco Latin-1) e os valores float NAN e INF. json_last_error_msg() diz o que deu errado; JSON_THROW_ON_ERROR faz ele lançar uma JsonException:

<?php
$name = "Caf\xE9";   // "Café" in Latin-1, not valid UTF-8

var_dump(json_encode(['name' => $name]));
echo json_last_error_msg(), "\n";

// Replace the broken bytes instead of failing
echo json_encode(['name' => $name], JSON_INVALID_UTF8_SUBSTITUTE), "\n";

// Or convert the text to UTF-8 first
echo json_encode(['name' => mb_convert_encoding($name, 'UTF-8', 'ISO-8859-1')], JSON_UNESCAPED_UNICODE), "\n";

try {
    json_encode(NAN, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo get_class($e), ': ', $e->getMessage(), "\n";
}

Saída:

bool(false)
Malformed UTF-8 characters, possibly incorrectly encoded
{"name":"Caf\ufffd"}
{"name":"Café"}
JsonException: Inf and NaN cannot be JSON encoded

JSON_THROW_ON_ERROR é o melhor padrão em código novo: um false que ninguém verifica acaba guardado ou enviado como string vazia.

Retornar JSON de uma API PHP

Um script PHP que responde com JSON define o cabeçalho Content-Type antes de imprimir qualquer coisa, codifica uma vez e para:

<?php
header('Content-Type: application/json; charset=utf-8');

$products = [
    ['id' => 1, 'name' => 'りんご', 'price' => 120],
    ['id' => 2, 'name' => 'みかん', 'price' => 80],
];

echo json_encode(['data' => $products], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
exit;

Quando você imprime JSON dentro de uma tag HTML <script>, adicione JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT. O escape padrão das barras transforma </script> em <\/script>, mas essa proteção some assim que alguém adiciona JSON_UNESCAPED_SLASHES, e um <!-- num valor ainda muda como o navegador interpreta o script. As flags escrevem <, >, &, ' e " como \u003C, \u003E, \u0026, \u0027 e \u0022, que o JavaScript lê de volta como os mesmos caracteres.

Perguntas frequentes

Como converto um array PHP em JSON?

Passe-o para o json_encode(): json_encode(['name' => 'Ada', 'age' => 36]) retorna {"name":"Ada","age":36}. Um array com chaves 0, 1, 2... em ordem vira um array JSON: json_encode(['a', 'b']) retorna ["a","b"].

Como formato o JSON (pretty print) no PHP?

Adicione a flag JSON_PRETTY_PRINT: json_encode($data, JSON_PRETTY_PRINT) indenta com 4 espaços e coloca cada valor numa linha própria. Combine flags com |, por exemplo JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE.

Por que o json_encode transforma acentos e texto japonês em códigos \u?

Por padrão, todo caractere fora do ASCII é escrito como um escape \uXXXX, então りんご vira \u308a\u3093\u3054. Ainda é JSON válido, mas passe JSON_UNESCAPED_UNICODE para manter os caracteres legíveis.

Por que o json_encode retorna false?

Normalmente porque uma string não é UTF-8 válido, ou porque os dados contêm NAN ou INF. Chame json_last_error_msg() para ver o motivo, ou passe JSON_THROW_ON_ERROR para que ele lance uma JsonException em vez de retornar false.

Como faço o json_encode gerar {} em vez de [] para um array vazio?

Um array PHP vazio sempre vira []. Use new stdClass() ou (object) [] para um objeto vazio, ou a flag JSON_FORCE_OBJECT, que transforma todos os arrays do valor em objetos.

Conceitos relacionados