json_encode

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL json >= 1.2.0)

json_encodeRetorna a representação JSON de um valor

Descrição

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

Retorna uma string contendo a representação JSON de value fornecido. Se o parâmetro for um array ou object, ele será serializado recursivamente.

Se um valor a ser serializado for um objeto, então, por padrão, apenas propriedades visíveis publicamente serão incluídas. Alternativamente, uma classe pode implementar JsonSerializable para controlar como seus valores são serializados para JSON.

A codificação é afetada pelas flags fornecidas e além disso a codificação de valores com ponto flutuante depende do valor de serialize_precision.

Parâmetros

value

O value a ser codificado. Pode ser qualquer tipo, exceto um resource.

Toda a string deve ser codificada como UTF-8.

Nota:

O PHP implementa uma extensção do JSON, além do especificado no » RFC 4627 - podendo também codificar e decodificar tipos escalares e null. RFC 4627 apenas suporta esses valores quando eles estão inseridos dentro de um objeto ou array.

Embora isso seja consistente com a definição expandida de "texto JSON" na nova » RFC 7159 (que pretende susceder RFC 4627) e ECMA-404, isto pode causar problemas de interoperabilidade com parsers JSON antigos que aderem estritamente a RFC 4627 quando decodificando um valor escalar.

flags

Bitmask consistindo de JSON_FORCE_OBJECT, JSON_HEX_QUOT, JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS, JSON_INVALID_UTF8_IGNORE, JSON_INVALID_UTF8_SUBSTITUTE, JSON_NUMERIC_CHECK, JSON_PARTIAL_OUTPUT_ON_ERROR, JSON_PRESERVE_ZERO_FRACTION, JSON_PRETTY_PRINT, JSON_UNESCAPED_LINE_TERMINATORS, JSON_UNESCAPED_SLASHES, JSON_UNESCAPED_UNICODE, JSON_THROW_ON_ERROR. O comportamento destas constantes é descrito na página de constantes JSON.

depth

Define a profundidade máxima. Deve ser maior do que zero.

Valor Retornado

Retorna uma string JSON codificada em caso de sucesso ou false em caso de falha.

Changelog

Versão Descrição
7.3.0 Adicionado JSON_THROW_ON_ERROR em flags.
7.2.0 Adicionado JSON_INVALID_UTF8_IGNORE e JSON_INVALID_UTF8_SUBSTITUTE em flags.
7.1.0 Adicionado JSON_UNESCAPED_LINE_TERMINATORS em flags.
7.1.0 É usado serialize_precision em vez de precision quando codificado valores float.

Exemplos

Exemplo #1 Um exemplo da json_encode()

<?php
$arr 
= array('a' => 1'b' => 2'c' => 3'd' => 4'e' => 5);

echo 
json_encode($arr);
?>

O exemplo acima irá imprimir:

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

Exemplo #2 Um exemplo de json_encode() mostrando algumas opções em uso

<?php
$a 
= array('<foo>',"'bar'",'"baz"','&blong&'"\xc3\xa9");

echo 
"Normal: ",  json_encode($a), "\n";
echo 
"Tags: ",    json_encode($aJSON_HEX_TAG), "\n";
echo 
"Apos: ",    json_encode($aJSON_HEX_APOS), "\n";
echo 
"Quot: ",    json_encode($aJSON_HEX_QUOT), "\n";
echo 
"Amp: ",     json_encode($aJSON_HEX_AMP), "\n";
echo 
"Unicode: "json_encode($aJSON_UNESCAPED_UNICODE), "\n";
echo 
"All: ",     json_encode($aJSON_HEX_TAG JSON_HEX_APOS JSON_HEX_QUOT JSON_HEX_AMP JSON_UNESCAPED_UNICODE), "\n\n";

$b = array();

echo 
"Saída de um array vazio como array: "json_encode($b), "\n";
echo 
"Saída de um array vazio como objeto: "json_encode($bJSON_FORCE_OBJECT), "\n\n";

$c = array(array(1,2,3));

echo 
"Saída de um array não-associativo como array: "json_encode($c), "\n";
echo 
"Saída de um array não-associativo como objeto: "json_encode($cJSON_FORCE_OBJECT), "\n\n";

$d = array('foo' => 'bar''baz' => 'long');

echo 
"Array associativo sempre tem saída como objeto: "json_encode($d), "\n";
echo 
"Array associativo sempre tem saída como objeto: "json_encode($dJSON_FORCE_OBJECT), "\n\n";
?>

O exemplo acima irá imprimir:

Normal: ["<foo>","'bar'","\"baz\"","&blong&","\u00e9"]
Tags: ["\u003Cfoo\u003E","'bar'","\"baz\"","&blong&","\u00e9"]
Apos: ["<foo>","\u0027bar\u0027","\"baz\"","&blong&","\u00e9"]
Quot: ["<foo>","'bar'","\u0022baz\u0022","&blong&","\u00e9"]
Amp: ["<foo>","'bar'","\"baz\"","\u0026blong\u0026","\u00e9"]
Unicode: ["<foo>","'bar'","\"baz\"","&blong&","é"]
All: ["\u003Cfoo\u003E","\u0027bar\u0027","\u0022baz\u0022","\u0026blong\u0026","é"]

Saída de um array vazio como array: []
Saída de um array vazio como objeto: {}

Saída de um array não-associativo como array: [[1,2,3]]
Saída de um array não-associativo como objeto: {"0":{"0":1,"1":2,"2":3}}

Array associativo sempre tem saída como objeto: {"foo":"bar","baz":"long"}
Array associativo sempre tem saída como objeto: {"foo":"bar","baz":"long"}

Exemplo #3 Exemplo com a opção JSON_NUMERIC_CHECK

<?php
echo "Strings representando números automaticamente transformados em números".PHP_EOL;
$numbers = array('+123123''-123123''1.2e3''0.00001');
var_dump(
 
$numbers,
 
json_encode($numbersJSON_NUMERIC_CHECK)
);
echo 
"Strings contendo números formatados incorretamente".PHP_EOL;
$strings = array('+a33123456789''a123');
var_dump(
 
$strings,
 
json_encode($stringsJSON_NUMERIC_CHECK)
);
?>

O exemplo acima irá imprimir algo similar à:

Strings representando números automaticamente transformados em números
array(4) {
  [0]=>
  string(7) "+123123"
  [1]=>
  string(7) "-123123"
  [2]=>
  string(5) "1.2e3"
  [3]=>
  string(7) "0.00001"
}
string(28) "[123123,-123123,1200,1.0e-5]"
Strings contendo números formatados incorretamente
array(2) {
  [0]=>
  string(13) "+a33123456789"
  [1]=>
  string(4) "a123"
}
string(24) "["+a33123456789","a123"]"

Exemplo #4 Exemplo de array sequencial versus não-sequencial

<?php
echo "Array sequencial".PHP_EOL;
$sequential = array("foo""bar""baz""blong");
var_dump(
 
$sequential,
 
json_encode($sequential)
);

echo 
PHP_EOL."Array não-sequencial".PHP_EOL;
$nonsequential = array(1=>"foo"2=>"bar"3=>"baz"4=>"blong");
var_dump(
 
$nonsequential,
 
json_encode($nonsequential)
);

echo 
PHP_EOL."Array sequencial com uma chave não definida".PHP_EOL;
unset(
$sequential[1]);
var_dump(
 
$sequential,
 
json_encode($sequential)
);
?>

O exemplo acima irá imprimir:

Array sequencial
array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(27) "["foo","bar","baz","blong"]"

Array não-sequencial
array(4) {
  [1]=>
  string(3) "foo"
  [2]=>
  string(3) "bar"
  [3]=>
  string(3) "baz"
  [4]=>
  string(5) "blong"
}
string(43) "{"1":"foo","2":"bar","3":"baz","4":"blong"}"

Array sequencial com uma chave não definida
array(3) {
  [0]=>
  string(3) "foo"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(33) "{"0":"foo","2":"baz","3":"blong"}"

Exemplo #5 Exemplo com a opção JSON_PRESERVE_ZERO_FRACTION

<?php
var_dump
(json_encode(12.0JSON_PRESERVE_ZERO_FRACTION));
var_dump(json_encode(12.0));
?>

O exemplo acima irá imprimir:

string(4) "12.0"
string(2) "12"

Notas

Nota:

Em uma eventual falha ao codificar, json_last_error() pode ser usado para determinar a natureza exata do erro.

Nota:

Quando codificando um array, se as chaves não são uma sequência numérica contínua começando por 0, todas as chaves são codificadas como strings, e especificadas explicitamente para cada par chave-valor.

Nota:

Assim como o codificador JSON referenciado, json_encode() irá gerar JSON que é um valor simples (isto é, nem um objeto e nem um array) se informado um string, int, float ou bool como uma entrada. Enquanto a maioria dos decodificadores aceitará esses valores como JSON válido, alguns podem não aceitar, já que a especificação é ambígua neste ponto.

Para resumir, sempre teste se o seu decodificador JSON pode dar conta da saída que você gerar a partir de json_encode().

Veja Também

add a note

User Contributed Notes 15 notes

up
101
bohwaz
11 years ago
Are you sure you want to use JSON_NUMERIC_CHECK, really really sure?

Just watch this usecase:

<?php
// International phone number
json_encode(array('phone_number' => '+33123456789'), JSON_NUMERIC_CHECK);
?>

And then you get this JSON:

{"phone_number":33123456789}

Maybe it makes sense for PHP (as is_numeric('+33123456789') returns true), but really, casting it as an int?!

So be careful when using JSON_NUMERIC_CHECK, it may mess up with your data!
up
10
ryan at ryanparman dot com
12 years ago
I came across the "bug" where running json_encode() over a SimpleXML object was ignoring the CDATA. I ran across http://bugs.php.net/42001 and http://bugs.php.net/41976, and while I agree with the poster that the documentation should clarify gotchas like this, I was able to figure out how to workaround it.

You need to convert the SimpleXML object back into an XML string, then re-import it back into SimpleXML using the LIBXML_NOCDATA option. Once you do this, then you can use json_encode() and still get back the CDATA.

<?php
// Pretend we already have a complex SimpleXML object stored in $xml
$json = json_encode(new SimpleXMLElement($xml->asXML(), LIBXML_NOCDATA));
?>
up
2
ck at ergovia dot de
9 years ago
Attention when passing a plain array to json_encode and using JSON_FORCE_OBJECT. It figured out that the index-order of the resulting JSON-string depends on the system PHP is running on.

$a = array("a" , "b", "c");
echo json_encode($a, JSON_FORCE_OBJECT);

On Xampp (Windows) you get:

{"0":"a","1":"b","2":"c"}';

On a machine running debian I get:

{"2":"a","1":"b","0":"c"}';

Note that the key:value pairs are different!

Solution here was to use array_combine to create a ssociative array and then pass it to json_encode:

json_encode(array_combine(range(0, count($a) - 1), $a), JSON_FORCE_OBJECT);
up
11
guilhenfsu at gmail dot com
9 years ago
Solution for UTF-8 Special Chars.

<?

$array = array('nome'=>'Paição','cidade'=>'São Paulo');

$array = array_map('htmlentities',$array);

//encode
$json = html_entity_decode(json_encode($array));

//Output: {"nome":"Paição","cidade":"São Paulo"}
echo $json;

?>
up
4
Istratov Vadim
13 years ago
Be careful with floating values in some locales (e.g. russian) with comma (",") as decimal point. Code:

<?php
setlocale
(LC_ALL, 'ru_RU.utf8');

$arr = array('element' => 12.34);
echo
json_encode( $arr );
?>

Output will be:
--------------
{"element":12,34}
--------------

Which is NOT a valid JSON markup. You should convert floating point variable to strings or set locale to something like "LC_NUMERIC, 'en_US.utf8'" before using json_encode.
up
2
Nick
6 years ago
Please note that there was an (as of yet) undocumented change to the json_encode() function between 2 versions of PHP with respect to JSON_PRETTY_PRINT:

In version 5.4.21 and earlier, an empty array [] using JSON_PRETTY_PRINT would be rendered as 3 lines, with the 2nd one an empty (indented) line, i.e.:
    "data": [
       
    ],

In version 5.4.34 and above, an empty array [] using JSON_PRETTY_PRINT would be rendered as exactly [] at the spot where it occurs, i.e.
    "data: [],

This is not mentioned anywhere in the PHP changelist and migration documentations; neither on the json_encode documentation page.

This is very useful to know when you are parsing the JSON using regular expressions to manually insert portions of data, as is the case with my current use-case (working with JSON exports of over several gigabytes requires sub-operations and insertion of data).
up
4
Sam Barnum
13 years ago
Note that if you try to encode an array containing non-utf values, you'll get null values in the resulting JSON string.  You can batch-encode all the elements of an array with the array_map function:
<?php
$encodedArray
= array_map(utf8_encode, $rawArray);
?>
up
0
elliseproduction at gmail dot com
1 month ago
Notice that JSON_FORCE_OBJECT will convert all non-associative arrays to objects. This is not necessarily a good solution for empty arrays.
If you want to convert only empty arrays to objects, simply convert them to empty object before use json_encode function.

For example:

<?php

$foo
=array(
  
'empty2object'=>(object)[],
  
'empty2array'=>[],
);

echo
json_encode($foo);  // {"empty2object":{},"empty2array":[]}

?>
up
2
Garrett
14 years ago
A note about json_encode automatically quoting numbers:

It appears that the json_encode function pays attention to the data type of the value. Let me explain what we came across:

We have found that when retrieving data from our database, there are occasions when numbers appear as strings to json_encode which results in double quotes around the values.

This can lead to problems within javascript functions expecting the values to be numeric.

This was discovered when were were retrieving fields from the database which contained serialized arrays. After unserializing them and sending them through the json_encode function the numeric values in the original array were now being treated as strings and showing up with double quotes around them.

The fix: Prior to encoding the array, send it to a function which checks for numeric types and casts accordingly. Encoding from then on worked as expected.
up
1
Walter Tross
7 years ago
If you need pretty-printed output, but want it indented by 2 spaces instead of 4:

$json_indented_by_4 = json_encode($output, JSON_UNESCAPED_SLASHES|JSON_PRETTY_PRINT);
$json_indented_by_2 = preg_replace('/^(  +?)\\1(?=[^ ])/m', '$1', $json_indented_by_4);
up
0
pvl dot kolensikov at gmail dot com
11 years ago
As json_encode() is recursive, you can use it to serialize whole structure of objects.

<?php
class A {
    public
$a = 1;
    public
$b = 2;
    public
$collection = array();

    function 
__construct(){
        for (
$i=3; $i-->0;){
           
array_push($this->collection, new B);
        }
    }
}

class
B {
    public
$a = 1;
    public
$b = 2;
}

echo
json_encode(new A);
?>

Will give:

{
    "a":1,
    "b":2,
    "collection":[{
        "a":1,
        "b":2
    },{
        "a":1,
        "b":2
    },{
        "a":1,
        "b":2
    }]
}
up
-1
spam.goes.in.here AT gmail.com
14 years ago
For anyone who has run into the problem of private properties not being added, you can simply implement the IteratorAggregate interface with the getIterator() method. Add the properties you want to be included in the output into an array in the getIterator() method and return it.
up
-1
jakepucan at gmail dot com
1 year ago
It's also  worth mentioning that adding charset is fine.

<?php
header
('Content-type:application/json;charset=utf-8');
json_encode(['name' => 'Jake', 'country' => 'Philippines']);
up
-2
DimeCadmium
10 months ago
> While most decoders will accept these values as valid JSON, some may not, as the specification is ambiguous on this point.

The specification (https://datatracker.ietf.org/doc/html/rfc8259#section-2) is not ambiguous, whether you look at RFC8259, go back to RFC7159 or 7158 or 4627, look at (either edition of) ECMA-404, or even at JSON.org.

The original RFC - from 16 years ago, mind you - specified that the root level of JSON text could only be a object or array.

Literally every other standard - from as long as 9 years ago (RFC7158 and ECMA-404 1st Ed.) and as recent as 5 years ago (RFC8259 and ECMA-404 2nd Ed., both current standards) - makes explicit that any value can appear at the root.
up
-2
mikko dot rantalainen at peda dot net
1 year ago
Notice that <?php $json = json_encode($x, JSON_FORCE_OBJECT); ?> doesn't guarantee that $json is actually an object encoded with JSON syntax. It *only* guarantees that the output doesn't start with "[".

For example:
<?php
json_encode
("foo", JSON_FORCE_OBJECT); # "foo"
json_encode(42, JSON_FORCE_OBJECT); # 42
json_encode(false, JSON_FORCE_OBJECT); # false
json_encode("false", JSON_FORCE_OBJECT); # "false"
json_encode(10/3, JSON_FORCE_OBJECT); # 3.3333333333333335
?>
To Top