Feature Json

📋 JSON-формат

← Возможности · Главная · Сравнение

Serializer::json() — JSON с fail-safe поведением: исключения вместо тихого false/null, UTF-8 без экранирования, сохранение типа float, лимиты глубины и длины.

Принцип работы

json_encode/json_decode по умолчанию возвращают false/null на ошибке — такое значение легко «утекает» дальше по коду. JsonSerializer включает JSON_THROW_ON_ERROR и оборачивает результат в контрактные исключения. UTF-8 не экранируется (JSON_UNESCAPED_UNICODE), дробные числа сохраняют тип (JSON_PRESERVE_ZERO_FRACTION), глубина и длина ограничены.

use CloudCastle\Serialize\Serializer;

Serializer::json()->serialize(['город' => 'Уфа']);   // {"город":"Уфа"} — без \uXXXX
Serializer::json()->unserialize('{"a":1}');          // ['a' => 1]
Serializer::json()->unserialize('{битый');           // ← DeserializationFailedException

// Человекочитаемый вывод
Serializer::json(pretty: true)->serialize(['a' => 1]);

// Лимиты глубины и длины (DoS-защита)
Serializer::json(depth: 64, maxLength: 1_000_000)->unserialize($input);

Плюсы

• Ошибка формата — всегда исключение, никогда тихий false.
• Корректный UTF-8 без экранирования — читаемый вывод для кириллицы.
• 1.0 остаётся float после кругового цикла (не превращается в int).
• Лимит глубины отражает JSON-бомбы ([[[[...]]]]), лимит длины — гигантский ввод.
• Быстрее laminas и symfony на encode и decode (см. Сравнение).

Минусы

• JSON не сохраняет PHP-объекты — для объектов используйте ObjectMapper поверх JSON или PHP-формат с whitelist.

✅ Рекомендуется

• API-обмен и межъязыковые интеграции — JSON поверх ObjectMapper для DTO.
• Пропускать недоверенный JSON только с разумным лимитом глубины.

❌ Антипаттерны

• json_decode($input) без проверки на null — источник скрытых багов; пакет бросает исключение.
• Безлимитная глубина на пользовательском вводе — вектор исчерпания стека.