Json в Битрикс D7: кодирование и декодирование

Обмен данными с внешними API, AJAX-обработчики, сохранение структурированных данных в текстовое поле — всё это регулярно требует кодирования и декодирования JSON. Разберём Bitrix\Main\Web\Json и чем он отличается от стандартных функций PHP.

Базовое кодирование и декодирование

<?php

use Bitrix\Main\Web\Json;

$jsonString = Json::encode(['name' => 'Товар', 'price' => 1500]);

$data = Json::decode($jsonString);
echo $data['name'];

Функционально класс — обёртка над стандартными json_encode и json_decode, но с более явной обработкой ошибок и настройками по умолчанию, подходящими для большинства сценариев внутри проекта на Битриксе.

Обработка ошибок декодирования

<?php

use Bitrix\Main\Web\Json;
use Bitrix\Main\ArgumentException;

try {
    $data = Json::decode($responseFromExternalApi);
} catch (ArgumentException $e) {
    AddMessage2Log('Некорректный JSON от внешнего API: ' . $e->getMessage(), 'integration');
    $data = null;
}

В отличие от стандартного json_decode, который при ошибке молча возвращает null без явного сигнала об ошибке (требуя отдельной проверки через json_last_error()), Json::decode выбрасывает исключение при некорректном JSON — это делает ошибку декодирования сложнее пропустить незамеченной в коде, обрабатывающем ответы внешних API.

Нужна помощь с Битрикс?

Кодирование не-ASCII символов

<?php

echo Json::encode(['name' => 'Товар']);
// результат содержит кириллицу как есть, без escape-кодов вида Товар

По умолчанию класс кодирует кириллицу и другие не-ASCII символы как есть, без escape-последовательностей вида \uXXXX, что делает результат человекочитаемым при отладке и логировании — стандартный json_encode без явного флага JSON_UNESCAPED_UNICODE экранирует такие символы, из-за чего лог с JSON-данными на русском языке превращается в нечитаемую последовательность кодов без дополнительной настройки.

Использование в AJAX-обработчиках

<?php

use Bitrix\Main\Web\Json;

header('Content-Type: application/json');

$result = ['success' => true, 'data' => $items];

echo Json::encode($result);

Для AJAX-обработчиков компонентов, унаследованных от Bitrix\Main\Engine\Controller, штатный механизм сам сериализует возвращаемый результат в JSON — прямой вызов Json::encode в этом случае избыточен и нужен только при написании обработчика "вручную" вне этого механизма, где ответ формируется напрямую в теле скрипта.

Хранение структурированных данных в текстовом поле базы

<?php

$settings = ['theme' => 'dark', 'notifications' => true];

CUserOptions::SetOption('my.module', 'settings', Json::encode($settings));

$stored = CUserOptions::GetOption('my.module', 'settings');
$settings = Json::decode($stored);

Сохранение произвольной структуры данных (настройки пользователя, конфигурация виджета) как JSON-строки в обычном текстовом поле — практичный способ избежать создания отдельной таблицы под каждую небольшую структуру данных, не требующую собственной SQL-схемы и полноценных запросов выборки по отдельным полям.

Когда JSON в поле базы — плохая идея

Хранение структуры в JSON-поле избавляет от отдельной таблицы, но лишает возможности фильтровать и сортировать по отдельным полям этой структуры средствами SQL напрямую — если данные требуют регулярной выборки по конкретному значению внутри структуры (не просто чтения целиком), это признак того, что структуре место в отдельной полноценной таблице с собственными колонками, а не в одном текстовом JSON-поле.

Частые ошибки

Ошибка декодирования JSON от внешнего API не перехватывается. Необработанное исключение прерывает выполнение скрипта в неожиданном месте.
Прямой вызов Json::encode в контроллере, унаследованном от Engine\Controller. Избыточно — штатный механизм сериализует результат сам.
JSON-поле используется там, где нужна фильтрация по отдельным значениям. Признак того, что структуре нужна отдельная таблица, а не одно текстовое поле.

Итог

Bitrix\Main\Web\Json даёт удобную обёртку над стандартным JSON-кодированием PHP с явными исключениями при ошибке декодирования и человекочитаемым выводом кириллицы без дополнительных флагов. Для хранения небольших структурированных данных в текстовом поле базы это практичный инструмент — до тех пор, пока не требуется регулярная фильтрация по отдельным значениям внутри самой структуры.

Теги: D7 Разработка