README

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

CloudCastle Parser Neon

Безопасный разбор и сериализация NEON для PHP 8.1+ без внешних зависимостей. Block-структуры, inline-выражения [a, b] / {k: v}, типизированные скаляры. Разбирает только данные — никаких entity-вызовов (Foo(...)) и объектов, что исключает инъекции. Fail-loud, исключения не раскрывают исходных данных.

Установка

composer require cloud-castle/parser-neon

Требуется PHP 8.1+.

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

<?php

use CloudCastle\Parser\Neon\Neon;

// Разбор NEON в структуру PHP (block + inline).
$config = Neon::decode(<<<NEON
name: demo
debug: false
hosts:
  - a.local
  - b.local
limits: {cpu: 4, memory: 512}
NEON);
// ['name' => 'demo', 'debug' => false, 'hosts' => [...], 'limits' => ['cpu' => 4, ...]]

// Сериализация обратно в NEON.
$neon = Neon::encode(['app' => ['name' => 'demo', 'workers' => 4]]);

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

Возможности

Block + inline NEON: отображения, списки, вложенность по отступам, inline-выражения [a, b] и {k: v} с любой вложенностью, типизированные скаляры (bool/null/int/float), кавычки, комментарии.
Только данные: разбор возвращает массивы и скаляры — никаких entity-вызовов (Foo(...)) и объектов (в отличие от nette/neon), то есть нет инъекций.
Fail-loud: ошибка разбора или сериализации — исключение (ParseException/EncodingException), а не тихий null/false.
Исключения не содержат исходных данных — только причину и номер строки.
Двунаправленность: decode() (NEON → структура) и encode() (структура → NEON).
Нулевые зависимости — чистый PHP.

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

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

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

Возможность	🏆 CloudCastle	nette	symfony	spyc	preg¹
Разбор block-конфига (отображения/списки/вложенность)	✅	✅	✅	✅	❌
Inline-выражения `[a, b]` / `{k: v}`	✅	✅	✅	❌	❌
Разбор в чистые данные (массивы/скаляры, без объектов)	✅	✅	✅	✅	✅
Fail-loud: исключение при ошибке разбора	✅	✅	✅	❌	❌
Ноль зависимостей (только PHP)	✅	❌	❌	✅	✅
Всего	🏆 5	4	4	3	2

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

Свойство	🏆 CloudCastle	nette	symfony	spyc	preg¹
Не создаёт объекты при разборе (nette/neon создаёт Entity)	✅	❌	✅	✅	✅
Нет entity-вызовов/тегов — нет инъекций и выполнения кода	✅	❌	❌	✅	✅
Fail-loud: исключение вместо тихого null/false	✅	✅	✅	❌	❌
Исключения не раскрывают исходные данные (нет утечки ПД)	✅	❌	❌	❌	❌
Ноль зависимостей (малая поверхность атаки)	✅	❌	❌	✅	✅
Всего	🏆 5	1	2	3	3

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

разбор конфигурационного документа, 20 000 раз (минимум из 4).

Решение	Время (мс)	Итог
preg¹	31,5	базовый уровень (не библиотека)
🏆 CloudCastle	716,6	быстрейшее среди библиотек
spyc	985,8	аналог
symfony	1 697,7	аналог
nette	1 821,4	аналог

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

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

Решение	Пиковая память (KB)	Итог
🏆 CloudCastle	7 111	легчайшее среди библиотек
nette	7 111	аналог
spyc	7 111	аналог
preg¹	7 111	базовый уровень (не библиотека)
symfony	7 161	аналог

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

Вывод: CloudCastle Parser Neon — самый безопасный среди рассмотренных (единственный отклоняет entity-вызовы и не создаёт объекты, тогда как nette/neon инстанцирует Entity для Foo(...)) и самый быстрый среди библиотек (быстрее nette/neon, symfony/yaml, spyc; наивный regex-разбор — базовый уровень). NEON как формат реализует по сути только nette/neon; symfony/yaml и spyc приведены как парсеры близких конфиг-форматов на общем block-документе. Это намеренное безопасное подмножество NEON для конфигураций: нужны entity и полная спека NEON — берите nette/neon; важна защита от инъекций и нулевые зависимости — этот пакет.

Разработка

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

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

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

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

Лицензия