README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Parser Json

Безопасный разбор и сериализация JSON для PHP 8.1+: всегда бросает исключение при ошибке (не тихий null), лимит глубины вложенности, безопасные дефолты кодирования и типизированные помощники. Исключения не содержат исходных данных — безопасно для логов с персональными данными. Единственная зависимость — ext-json.

Установка

composer require cloud-castle/parser-json

Требуется PHP 8.1+ и расширение ext-json.

Быстрый старт

<?php

use CloudCastle\Parser\Json\Json;

// Разбор в ассоциативные массивы — при ошибке бросается MalformedJsonException.
$data = Json::decode('{"user":{"id":42},"tags":["a","b"]}');

// Гарантированно массив на верхнем уровне (иначе исключение).
$list = Json::toArray('[1,2,3]');

// Разбор объектов как stdClass.
$object = Json::decodeObject('{"id":42}');

// Сериализация с безопасными дефолтами (читаемый юникод, без экранирования слэшей).
$json = Json::encode(['url' => 'http://a/b', 'имя' => 'Значение']);
// {"url":"http://a/b","имя":"Значение"}

// Человекочитаемый вывод с отступами.
echo Json::pretty(['a' => 1, 'b' => [2, 3]]);

// Проверка без исключения.
if (Json::isValid($input)) {
    // ...
}

// Ограничение глубины вложенности (защита от глубоких структур).
$safe = Json::decode($untrusted, depth: 8);

Возможности

Fail-loud: любая ошибка разбора или сериализации — исключение (MalformedJsonException/EncodingException), а не молчаливый null/false, который легко пропустить.
Лимит глубины вложенности (по умолчанию 512) — защита от переполнения стека на злонамеренно/случайно глубоких структурах.
Безопасные дефолты кодирования: JSON_UNESCAPED_UNICODE (читаемый юникод) и JSON_UNESCAPED_SLASHES (без лишнего экранирования).
Исключения не содержат исходных данных — только причину сбоя, чтобы персональные и финансовые данные из JSON не утекли в логи и трассировки.
Типизированные помощники: toArray() гарантирует массив, decodeObject() — объектную форму, isValid() — проверку без исключения.
Единственная зависимость — расширение ext-json.

Сравнение с аналогами

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	symfony	nette	laminas	json¹
Исключение при любой ошибке (не тихий null/false)	✅	✅	✅	✅	❌
Лимит глубины вложенности (защита от глубоких структур)	✅	✅	✅	❌	✅
Типизированные помощники (toArray/decodeObject)	✅	❌	❌	❌	❌
Исключения не содержат исходных данных (безопасно для логов с ПД)	✅	❌	❌	❌	❌
Ноль зависимостей сверх ext-json	✅	❌	❌	❌	✅
Всего	🏆 5	2	2	1	2

2. Безопасность и корректность

Свойство	🏆 CloudCastle	symfony	nette	laminas	json¹
Fail-loud: исключение вместо пропущенного null по умолчанию	✅	✅	✅	✅	❌
Лимит глубины (защита от переполнения стека на глубоком JSON)	✅	✅	✅	❌	✅
Исключения не раскрывают исходные данные (нет утечки ПД в логи)	✅	❌	❌	❌	❌
Читаемый юникод без искажения (JSON_UNESCAPED_UNICODE)	✅	✅	✅	❌	❌
Проверка типа результата (toArray отвергает неожиданный корень)	✅	❌	❌	❌	❌
Всего	🏆 5	3	3	1	1

3. Производительность

encode + decode структуры данных, 100 000 раз (минимум из 4).

Решение	Время (мс)	Итог
json¹	212,7	базовый уровень (не библиотека)
🏆 CloudCastle	221,6	быстрейшее среди библиотек
nette	225,5	аналог
symfony	259,9	аналог
laminas	300,9	аналог

4. Потребление памяти

Пик памяти на 100 000 операций (изолированный процесс, только целевая библиотека).

Решение	Пиковая память (KB)	Итог
🏆 CloudCastle	6 980	легчайшее среди библиотек
symfony	6 980	аналог
nette	6 980	аналог
laminas	6 980	аналог
json¹	6 980	базовый уровень (не библиотека)

¹ Базовый уровень (нативные вызовы/примитивы без полноты решения) показан для контекста и не претендует на победу среди библиотек-аналогов.

Вывод: CloudCastle Parser Json — самый функциональный и безопасный среди рассмотренных JSON-обёрток и при этом самый быстрый среди библиотек (быстрее symfony/serializer, nette/utils, laminas-json; вплотную к «голому» ext-json, который взят за базовый уровень). Единственный, кто совмещает fail-loud, лимит глубины, безопасные дефолты и типизированные помощники при исключениях без утечки данных. Рекомендуется везде, где JSON приходит из недоверенного источника (API, конфиги, очереди) и важна предсказуемая обработка ошибок без риска утечки персональных данных в логи.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/parser-json
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия