Descrição

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

Recebe uma string codificada em JSON e converte em um valor do PHP.

Parâmetros

json

A string json a ser decodificada.

Esta função funciona apenas com strings codificadas em UTF-8.

Nota:
O PHP implementa um superconjunto de JSON conforme especificado na » RFC 7159 original.

associative

Quando true, objetos JSON serão retornados como arrays associativo; quando false, objetos JSON serão retornados como objects. Quando null, objetos JSON serão retornados como arrays ou objects dependendo se flags JSON_OBJECT_AS_ARRAY estiver definida.

depth

Profundidade máxima da estrutura que será decodificada. O valor deve ser maior que 0, e menor ou igual a 2147483647.

flags

Máscara de bits de JSON_BIGINT_AS_STRING, JSON_INVALID_UTF8_IGNORE, JSON_INVALID_UTF8_SUBSTITUTE, JSON_OBJECT_AS_ARRAY, JSON_THROW_ON_ERROR. O comportamento dessas constantes é descrito na página de constantes JSON.

Valor Retornado

Retorna o valor codificado em json como um tipo apropriado do PHP. Valores sem aspas true, false e null são retornados como true, false e null respectivamente. null é retornado se o json não puder ser decodificado ou se os dados codificados tiverem profundidade maior que o limite de aninhamento.

Erros/Exceções

Se a depth estiver fora do intervalo permitido, um ValueError é lançado a partir do PHP 8.0.0, enquanto anteriormente, era gerado um erro do nível E_WARNING.

Registro de Alterações

Versão Descrição

7.3.0 Foi adicionado JSON_THROW_ON_ERROR em flags

7.2.0 associative agora é nullable.

7.2.0 Foi adicionado JSON_INVALID_UTF8_IGNORE, e JSON_INVALID_UTF8_SUBSTITUTE em flags.

7.1.0 Uma chave JSON vazia ("") pode ser codificada para a propriedade vazia de objeto, em vez de usar uma chave com o valor _empty_.

Versão	Descrição
7.3.0	Foi adicionado `JSON_THROW_ON_ERROR` em `flags`
7.2.0	`associative` agora é nullable.
7.2.0	Foi adicionado `JSON_INVALID_UTF8_IGNORE`, e `JSON_INVALID_UTF8_SUBSTITUTE` em `flags`.
7.1.0	Uma chave JSON vazia ("") pode ser codificada para a propriedade vazia de objeto, em vez de usar uma chave com o valor `_empty_`.

Exemplos

Exemplo #1 json_decode() exemplos

<?php
$json = '{"a":1,"b":2,"c":3,"d":4,"e":5}';

var_dump(json_decode($json));
var_dump(json_decode($json, true));

?>

O exemplo acima produzirá:

object(stdClass)#1 (5) {
    ["a"] => int(1)
    ["b"] => int(2)
    ["c"] => int(3)
    ["d"] => int(4)
    ["e"] => int(5)
}

array(5) {
    ["a"] => int(1)
    ["b"] => int(2)
    ["c"] => int(3)
    ["d"] => int(4)
    ["e"] => int(5)
}

Exemplo #2 Acessando propriedades inválidas do objeto

Acessar elementos dentro de um objeto que contém caracteres não permitidos pela convenção de nomenclatura do PHP (por exemplo, o hífen) pode ser realizado encapsulando o nome do elemento entre chaves e apóstrofo.

<?php

$json = '{"foo-bar": 12345}';

$obj = json_decode($json);
print $obj->{'foo-bar'}; // 12345

?>

Exemplo #3 erros comuns usando json_decode()

<?php

// as seguintes strings são JavaScript válidas, mas não JSON válidos

// o nome e o valor devem ser colocados entre aspas duplas
// aspas simples não são válidas
$bad_json = "{ 'bar': 'baz' }";
json_decode($bad_json); // null

// o nome deve ser colocado entre aspas duplas
$bad_json = '{ bar: "baz" }';
json_decode($bad_json); // null

// vírgulas à direita não são permitidas
$bad_json = '{ bar: "baz", }';
json_decode($bad_json); // null

?>

Exemplo #4 erros de depth

<?php
// Codifica alguns dados com uma profundidade máxima de 4 (array -> array -> array -> string)
$json = json_encode(
    array(
        1 => array(
            'English' => array(
                'One',
                'January'
            ),
            'French' => array(
                'Une',
                'Janvier'
            )
        )
    )
);

// Mostrar os erros para diferentes profundidades.
var_dump(json_decode($json, true, 4));
echo 'Last error: ', json_last_error_msg(), PHP_EOL, PHP_EOL;

var_dump(json_decode($json, true, 3));
echo 'Last error: ', json_last_error_msg(), PHP_EOL, PHP_EOL;
?>

O exemplo acima produzirá:

array(1) {
  [1]=>
  array(2) {
    ["English"]=>
    array(2) {
      [0]=>
      string(3) "One"
      [1]=>
      string(7) "January"
    }
    ["French"]=>
    array(2) {
      [0]=>
      string(3) "Une"
      [1]=>
      string(7) "Janvier"
    }
  }
}
Last error: No error

NULL
Last error: Maximum stack depth exceeded

Exemplo #5 json_decode() de inteiros grandes

<?php
$json = '{"number": 12345678901234567890}';

var_dump(json_decode($json));
var_dump(json_decode($json, false, 512, JSON_BIGINT_AS_STRING));

?>

O exemplo acima produzirá:

object(stdClass)#1 (1) {
  ["number"]=>
  float(1.2345678901235E+19)
}
object(stdClass)#1 (1) {
  ["number"]=>
  string(20) "12345678901234567890"
}

Notas

Nota:
A especificação JSON não é JavaScript, mas um subconjunto de JavaScript.

Nota:
No caso de falha na decodificação, json_last_error() pode ser usado para determinar a exata natureza do erro.

Veja Também

json_encode() - Retorna a representação JSON de um valor
json_last_error() - Retorna o último erro ocorrido
json_last_error_msg() - Retorna a string de erro da última chamada a json_validate(), json_encode() ou json_decode()