PHP json_encode(): массивы и объекты в JSON

json_encode($value) возвращает JSON-текст для значения PHP. Ассоциативный массив становится JSON-объектом, список (ключи 0, 1, 2...) JSON-массивом, а строки, числа, true, false и null становятся своими эквивалентами в 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";

Вывод:

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

Результат это обычная строка, готовая к отправке в браузер, сохранению в файл или столбец базы данных или передаче другой программе. Чтобы превратить JSON обратно в PHP, используйте json_decode().

Красивый вывод JSON

json_encode() принимает флаги вторым аргументом. JSON_PRETTY_PRINT добавляет переносы строк и отступы в 4 пробела, и именно это нужно в файле настроек или отладочном логе. Несколько флагов объединяются через |:

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

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

Вывод:

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

Читаемый японский, русский и другой текст в UTF-8

По умолчанию json_encode() записывает каждый не-ASCII символ escape-последовательностью \u и ставит обратный слеш перед каждым /. И то, и другое корректный JSON и декодируется обратно в тот же текст, но вывод становится длиннее и хуже читается. JSON_UNESCAPED_UNICODE сохраняет символы, а JSON_UNESCAPED_SLASHES оставляет URL как есть:

<?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";

Вывод:

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

Если после декодирования текст выглядит как кракозябры, дело не в escape-последовательностях: строка изначально была не в UTF-8. json_encode() принимает только UTF-8 и для всего остального возвращает false, как показано в разделе об ошибках.

Когда массив становится объектом, а не списком

Массив PHP кодируется как JSON-массив, только когда его ключи ровно 0, 1, 2... по порядку. Любые другие ключи делают его JSON-объектом. На этом попадаются после unset() или array_filter(), которые оставляют пропуски в ключах:

<?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";

Вывод:

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

Вызывайте array_values() перед кодированием всякий раз, когда принимающий код ждёт список. Если он ждёт объект, который может быть пустым, используйте new stdClass() или (object) $array, чтобы пустое значение всё равно выходило как {}.

Кодирование объекта и управление его JSON через JsonSerializable

Обычный объект кодируется только со своими публичными свойствами; защищённые и закрытые пропускаются. Чтобы точно решать, как объект выглядит в JSON, реализуйте интерфейс JsonSerializable и возвращайте данные из 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";

Вывод:

{"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"
}

Типизированное перечисление вроде enum Status: string кодируется своим значением ("active"). У чистого перечисления значения нет, поэтому json_encode() на нём падает с сообщением "Non-backed enums have no default serialization".

Числа, float и числовые строки

Целые числа и float записываются как JSON-числа, а строки остаются строками, даже если состоят из цифр. Три флага это меняют:

<?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";

Вывод:

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

JSON_NUMERIC_CHECK преобразует каждую числовую строку, поэтому ID вроде "007" или почтовый индекс вроде "01234" теряет ведущие нули. Преобразуйте нужные поля через (int), а не применяйте флаг ко всему массиву.

json_encode возвращает false: поиск ошибки

json_encode() возвращает false, когда не может закодировать значение. Обычные причины это строка, которая не является корректным UTF-8 (текст из старого файла или базы данных в Latin-1), и значения float NAN и INF. json_last_error_msg() сообщает, что пошло не так; JSON_THROW_ON_ERROR заставляет функцию выбрасывать 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";
}

Вывод:

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 лучший вариант по умолчанию в новом коде: false, который никто не проверил, в итоге сохраняется или отправляется как пустая строка.

Ответ JSON из PHP API

PHP-скрипт, который отвечает JSON, устанавливает заголовок Content-Type до любого вывода, кодирует один раз и завершается:

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

Когда вы выводите JSON внутри HTML-тега <script>, добавьте JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT. Стандартное экранирование слешей превращает </script> в <\/script>, но эта защита исчезает, как только кто-то добавит JSON_UNESCAPED_SLASHES, а <!-- в значении всё равно меняет то, как браузер разбирает скрипт. Флаги записывают <, >, &, ' и " как \u003C, \u003E, \u0026, \u0027 и \u0022, а JavaScript читает их обратно как те же символы.