README

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

CloudCastle Parser Yaml

Безопасный разбор и сериализация блочного YAML для PHP 8.1+ без внешних расширений. Разбирает только данные: никаких тегов, якорей и инстанцирования объектов — это исключает YAML-инъекции и выполнение кода на недоверенном вводе. Fail-loud, исключения не раскрывают исходных данных. Нулевые зависимости.

Установка

composer require cloud-castle/parser-yaml

Требуется PHP 8.1+ (без расширения ext-yaml).

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

<?php

use CloudCastle\Parser\Yaml\Yaml;

// Разбор YAML в структуру PHP.
$config = Yaml::parse(<<<YAML
name: demo
debug: false
hosts:
  - a.local
  - b.local
database:
  driver: pgsql
  port: 5432
YAML);
// ['name' => 'demo', 'debug' => false, 'hosts' => ['a.local', 'b.local'], ...]

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

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

Возможности

Block YAML: отображения, списки, вложенность по отступам, типизированные скаляры (bool/null/int/float), одинарные и двойные кавычки, комментарии.
Только данные: разбор возвращает массивы и скаляры — никаких объектов, тегов (!!php/object) и якорей, то есть нет YAML-инъекций и выполнения кода.
Fail-loud: ошибка разбора или сериализации — исключение (ParseException/DumpException) с номером строки, а не тихий null/false.
Исключения не содержат исходных данных — только причину и номер строки, чтобы персональные данные из конфигурации не утекли в логи.
Двунаправленность: parse() (YAML → структура) и dump() (структура → YAML).
Нулевые зависимости — чистый PHP, без ext-yaml.

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

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

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

Возможность	🏆 CloudCastle	symfony	spyc	dallgoot	preg¹
Разбор block YAML (отображения/списки/вложенность)	✅	✅	✅	✅	❌
Типизированные скаляры (bool/null/int/float)	✅	✅	✅	✅	❌
Разбор в чистые данные (массивы/скаляры, без объектов)	✅	✅	✅	❌	✅
Fail-loud: исключение при ошибке разбора	✅	✅	❌	✅	❌
Ноль зависимостей (только PHP)	✅	❌	✅	✅	✅
Всего	🏆 5	4	4	4	2

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

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

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

разбор YAML-документа в структуру, 20 000 раз (минимум из 4).

Решение	Время (мс)	Итог
preg¹	40,7	базовый уровень (не библиотека)
🏆 CloudCastle	1 021,4	быстрейшее среди библиотек
spyc	1 537,7	аналог
symfony	2 812,4	аналог
dallgoot	2 945	аналог

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

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

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

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

Вывод: CloudCastle Parser Yaml — самый безопасный среди рассмотренных YAML-инструментов (только данные, без объектов/тегов/якорей и утечки данных в ошибках) и самый быстрый среди библиотек (быстрее symfony/yaml, spyc, dallgoot/yaml; наивный regex-разбор взят за базовый уровень). Это намеренное безопасное подмножество YAML для конфигураций: если нужны якоря, поточный стиль ([a, b]), многострочные блоки и полная спека YAML — берите symfony/yaml; если важна защита от инъекций, предсказуемость и нулевые зависимости при разборе недоверенных конфигов — этот пакет.

Разработка

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

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

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

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

Лицензия