README

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

CloudCastle Parser Yaml

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

Установка

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)) {
    // ...
}

// Разбор из локального файла.
$config = Yaml::parseFile('/path/to/config.yaml');

// Автоопределение источника: локальный путь или URL. Загрузка по URL
// делегируется PSR-18 клиенту (лимит размера, таймауты и защита от SSRF —
// на стороне клиента, например cloud-castle/http-client).
$config = Yaml::parseFrom('https://example.com/config.yaml', $httpClient, $requestFactory);
$config = Yaml::parseFrom('/path/to/config.yaml'); // тот же метод — локальный файл

Возможности

Block YAML: отображения, списки, вложенность по отступам, типизированные скаляры (bool/null/int/float), одинарные и двойные кавычки, комментарии.
Только данные: разбор возвращает массивы и скаляры — никаких объектов, тегов (!!php/object) и якорей, то есть нет YAML-инъекций и выполнения кода.
Fail-loud: ошибка разбора или сериализации — исключение (ParseException/DumpException) с номером строки, а не тихий null/false.
Исключения не содержат исходных данных — только причину и номер строки, чтобы персональные данные из конфигурации не утекли в логи.
Двунаправленность: parse() (YAML → структура) и dump() (структура → YAML).
Загрузка из файла и по URL: parseFile() (локальный файл) и parseFrom() (автоопределение локального пути или URL). Сеть не встроена — загрузка по URL идёт через инъектируемый PSR-18 клиент, где и задаются лимит размера, таймауты и защита от SSRF (например, cloud-castle/http-client).
Разбор без внешних библиотек — ядро на чистом PHP, без ext-yaml; лёгкие PSR-контракты (PSR-18/17) нужны только для загрузки по URL.

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

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

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

Возможность	🏆 CloudCastle	symfony	spyc	dallgoot	preg¹
Разбор block YAML (отображения/списки/вложенность)	✅	✅	✅	✅	❌
Типизированные скаляры (bool/null/int/float)	✅	✅	✅	✅	❌
Разбор в чистые данные (массивы/скаляры, без объектов)	✅	✅	✅	❌	✅
Fail-loud: исключение при ошибке разбора	✅	✅	❌	✅	❌
Разбор ядром без внешних библиотек (PSR-контракты лишь для URL)	✅	❌	✅	✅	✅
Загрузка из файла/URL с контролем размера и SSRF (PSR-18)	✅	❌	❌	❌	❌
Всего	🏆 6	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¹	42,2	базовый уровень (не библиотека)
🏆 CloudCastle	1 033,6	быстрейшее среди библиотек
spyc	1 577,5	аналог
symfony	2 892,4	аналог
dallgoot	3 003,8	аналог

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

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

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

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

Вывод: 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

Лицензия