json_encode

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

json_encode — Возвращает JSON-представление данных

Описание

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

Функция возвращает строку, которая содержит JSON-представление значения value. Функция рекурсивно сериализует значение параметра, если параметр — массив (array) или объект (object).

По умолчанию функция включит в результирующую строку только открытые свойства, если значение, которое сериализует функция, — объект. Чтобы создать альтернативу внутренней сериализации и самому управлять тем, как значения объекта сериализуются в JSON, в классе реализуют интерфейс JsonSerializable.

На кодирование влияет параметр flags, а кодирование значений float зависит от значения директивы serialize_precision.

Список параметров

value

Параметр value — значение, которое закодирует функция. Разрешены все типы, кроме resource.

Функция работает только с кодировкой UTF-8.

Замечание:
PHP реализует расширенный набор JSON, который описывает исходный стандарт » RFC 7159.

flags

Битовая маска, которую составили из значений 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. Значение этих констант объясняет страница JSON-констант.

depth

Устанавливает максимальную глубину. Значение параметра должно быть больше нуля.

Возвращаемые значения

Функция возвращает строку (string) в формате JSON или false, если возникла ошибка.

Список изменений

Версия	Описание
7.3.0	Добавлена константа `JSON_THROW_ON_ERROR` для параметра `flags`.
7.2.0	Добавлены константы `JSON_INVALID_UTF8_IGNORE` и `JSON_INVALID_UTF8_SUBSTITUTE` для параметра `flags`.
7.1.0	Добавлена константа `JSON_UNESCAPED_LINE_TERMINATORS` для параметра `flags`.
7.1.0	При кодировании чисел с плавающей точкой (float) вместо значения директивы precision функция учитывает значение директивы serialize_precision.

Примеры

Пример #1 Пример использования функции json_encode()

<?php

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

echo json_encode($arr);

?>

Результат выполнения приведённого примера:

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

Пример #2 Пример использования функции json_encode() с опциями

<?php

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

echo "Обычно: ",     json_encode($a), "\n";
echo "Теги: ",       json_encode($a, JSON_HEX_TAG), "\n";
echo "Апострофы: ",  json_encode($a, JSON_HEX_APOS), "\n";
echo "Кавычки: ",    json_encode($a, JSON_HEX_QUOT), "\n";
echo "Амперсанды: ", json_encode($a, JSON_HEX_AMP), "\n";
echo "Юникод: ",     json_encode($a, JSON_UNESCAPED_UNICODE), "\n";
echo "Все: ",        json_encode($a, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP | JSON_UNESCAPED_UNICODE), "\n\n";

$b = array();

echo "Отображение пустого массива как массива: ", json_encode($b), "\n";
echo "Отображение неассоциативного массива как объекта: ", json_encode($b, JSON_FORCE_OBJECT), "\n\n";

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

echo "Отображение неассоциативного массива как массива: ", json_encode($c), "\n";
echo "Отображение неассоциативного массива как объекта: ", json_encode($c, JSON_FORCE_OBJECT), "\n\n";

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

echo "Ассоциативный массив всегда отображается как объект: ", json_encode($d), "\n";
echo "Ассоциативный массив всегда отображается как объект: ", json_encode($d, JSON_FORCE_OBJECT), "\n\n";

?>

Результат выполнения приведённого примера:

Обычно: ["<foo>","'bar'","\"baz\"","&blong&","\u00e9"]
Теги: ["\u003Cfoo\u003E","'bar'","\"baz\"","&blong&","\u00e9"]
Апострофы: ["<foo>","\u0027bar\u0027","\"baz\"","&blong&","\u00e9"]
Кавычки: ["<foo>","'bar'","\u0022baz\u0022","&blong&","\u00e9"]
Амперсанды: ["<foo>","'bar'","\"baz\"","\u0026blong\u0026","\u00e9"]
Юникод: ["<foo>","'bar'","\"baz\"","&blong&","é"]
Все: ["\u003Cfoo\u003E","\u0027bar\u0027","\u0022baz\u0022","\u0026blong\u0026","é"]

Отображение пустого массива как массива: []
Отображение неассоциативного массива как объекта: {}

Отображение неассоциативного массива как массива: [[1,2,3]]
Отображение неассоциативного массива как объекта: {"0":{"0":1,"1":2,"2":3}}

Ассоциативный массив всегда отображается как объект: {"foo":"bar","baz":"long"}
Ассоциативный массив всегда отображается как объект: {"foo":"bar","baz":"long"}

Пример #3 Пример использования опции JSON_NUMERIC_CHECK

<?php

echo "Строки, которые содержат числа, преобразовываются в числа" . PHP_EOL;
$numbers = array('+123123', '-123123', '1.2e3', '0.00001');

var_dump(
    $numbers,
    json_encode($numbers, JSON_NUMERIC_CHECK)
);

echo "Строки, которые содержат некорректно заданные числа" . PHP_EOL;
$strings = array('+a33123456789', 'a123');

var_dump(
    $strings,
    json_encode($strings, JSON_NUMERIC_CHECK)
);

?>

Вывод приведённого примера будет похож на:

Строки, которые содержат числа, преобразовываются в числа
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]"
Строки, которые содержат некорректно заданные числа
array(2) {
  [0]=>
  string(13) "+a33123456789"
  [1]=>
  string(4) "a123"
}
string(24) "["+a33123456789","a123"]"

Пример #4 Пример с последовательными индексами, которые начинаются с нуля, и непоследовательными индексами массивов

<?php

echo "Последовательный массив" . PHP_EOL;
$sequential = array("foo", "bar", "baz", "blong");

var_dump(
    $sequential,
    json_encode($sequential)
);

echo PHP_EOL . "Непоследовательный массив" . PHP_EOL;
$nonsequential = array(1 => "foo", 2 => "bar", 3 => "baz", 4 => "blong");

var_dump(
    $nonsequential,
    json_encode($nonsequential)
);

echo PHP_EOL . "Последовательный массив с одним удалённым индексом" . PHP_EOL;
unset($sequential[1]);

var_dump(
    $sequential,
    json_encode($sequential)
);

?>

Результат выполнения приведённого примера:

Последовательный массив
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(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(3) {
  [0]=>
  string(3) "foo"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(33) "{"0":"foo","2":"baz","3":"blong"}"

Пример #5 Пример использования опции JSON_PRESERVE_ZERO_FRACTION

<?php

var_dump(json_encode(12.0, JSON_PRESERVE_ZERO_FRACTION));
var_dump(json_encode(12.0));

?>

Результат выполнения приведённого примера:

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

Примечания

Замечание:
Функция json_last_error() помогает определить точную причину ошибки, если возникла ошибка кодирования.

Замечание:
Функция кодирует ключи как строковые и для каждой пары ключ-значение указывает ключи явным образом, если при кодировании массива ключи нарушают непрерывную числовую последовательность, которая начинается с 0.

Замечание:
Как и эталонный JSON-кодировщик, функция json_encode() сгенерирует JSON в виде простого значения, а не объекта или массива, если входное значение параметра value — string, int, float или bool. Декодеры будут принимать эти значения как корректный JSON, но часть декодеров не примет, потому что спецификация в этом отношении неоднозначна.

Заключение: проверяйте, правильно ли JSON-декодер обрабатывает вывод, который генерирует функция json_encode().

Смотрите также

JsonSerializable
json_decode() - Декодирует строку JSON
json_last_error() - Возвращает последнюю ошибку
json_last_error_msg() - Возвращает строку с сообщением об ошибке последнего вызова json_encode() или json_decode()
serialize() - Генерирует пригодное для хранения представление переменной

Нашли ошибку?

Инструкция • Исправление • Сообщение об ошибке

＋Добавить

Примечания пользователей 11 notes

down

109

bohwaz ¶

13 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!

down

elliseproduction at gmail dot com ¶

2 years 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":[]}

?>

down

ck at ergovia dot de ¶

12 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);

down

Istratov Vadim ¶

15 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.

down

ryan at ryanparman dot com ¶

15 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));
?>

down

Garrett ¶

16 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.

down

diagnose at gmail dot com ¶

5 months ago

Beware of Trailing Backslashes!

The JSON specification *does not allow* trailing backslashes in strings. It will create a JSON-encoded string without throwing an error, but this string will cause an error when parsed.

For example, the string "Example\" will cause the following error in JavaScript when parsing:

JSON.parse: expected ',' or '}' after property value in object

This appears to be an oversight in the JSON specification and the only work-around appears to be removing trailing slashes from all strings before encoding.

down

guilhenfsu at gmail dot com ¶

12 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;

?>

down

dassolucas at c238 dot com dot ar ¶

6 months ago

The Problem:
---------------
When you filter an array in PHP using array_filter, the original keys are preserved. If you remove elements, you'll end up with gaps in the keys (non-consecutive). When encoded to JSON, this can lead to the list being interpreted as a JSON object instead of a JSON array, which might not be what your JavaScript code expects.

The Solution:
---------------
The array_values() function is essential in this scenario. It re-indexes the array with consecutive numerical keys (0, 1, 2, ...), ensuring that the JSON output is always a well-formed array.

Example:
----------
<?php

// Use Case: Filtering a list and ensuring consistent JSON array output

// Imagine you have a list of items and need to send a filtered version to a JavaScript frontend 
// using JSON.  You want to ensure the filtered list is always received as a JSON array, 
// regardless of which items were removed.

// Sample data: A list of items
$items = [
    "first",
    "second",
    "third",
    "fourth",
    "fifth"
];

// Items to remove from the list
$itemsToRemove = ["second", "fourth"];

// Filter the list, keeping original keys (which become non-consecutive)
$filteredItems = array_filter($items, function($item) use ($itemsToRemove) {
    return !in_array($item, $itemsToRemove);
});

// Prepare data for JSON output
$output_arr = [
    "list" => $filteredItems 
];

// Output 1: JSON with non-consecutive keys (becomes an object)
echo "Output without array_values:\n";
echo json_encode($output_arr, JSON_PRETTY_PRINT) . "\n\n";
/* Output:
{
    "list": {
        "0": "first",
        "2": "third",
        "4": "fifth"
    }
}
*/

// Reset keys to be consecutive using array_values
$output_arr['list'] = array_values($output_arr['list']);

// Output 2: JSON with consecutive keys (remains an array)
echo "Output with array_values:\n";
echo json_encode($output_arr, JSON_PRETTY_PRINT) . "\n";
/* Output:
{
    "list": [
        "first",
        "third",
        "fifth"
    ]
}
*/
?>

down

Sam Barnum ¶

16 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);
?>

down

Walter Tross ¶

9 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);

＋Добавить