Download the PHP package on1kel/oas-core without Composer

on1kel/oas-core

OpenAPI core для PHP: неизменяемые (immutable) модели OAS 3.x, быстрый парсер с поддержкой $ref, сериализация/денормализация, обход дерева (visitor/walker), профили версий и базовые правила валидации.

Пакет предоставляет ядро, общее для разных версий спецификации OpenAPI 3.x. Поддержка различий версии (например, 3.1 vs 3.2) вынесена в профили (SpecProfile).

Возможности

• 🧩 Модели OpenAPI: типизированные value-объекты (например, On1kel\\OAS\\Core\\Model\\OpenApiDocument, Info, PathItem, Components и т.д.).
• 📥 Парсинг: преобразование массива/JSON в объектную модель, включая разрешение $ref (внутренних и внешних).
• 📤 Сериализация: обратная операция — модель → массив/JSON.
• 🧭 Определение версии: извлечение openapi: "MAJOR.MINOR[.patch]" и выбор соответствующего профиля.
• 🚶 Обход дерева: Traverse\\Walker + NodeVisitor с JSON Pointer путями каждого узла.
• ✅ Валидация: базовый валидатор с набором правил (например, UniqueOperationIdRule, ReferenceNoSiblingsRule, и др.).
• 🔌 PSR-совместимость: использует psr/http-client и psr/http-factory для загрузки внешних $ref.
• 🧱 Иммутабельность: модели неизменяемы.

Установка

Требования: PHP ^8.2, расширения ext-json, ext-ctype. Зависимости времени выполнения: psr/http-client, psr/http-factory.

Лицензия: MIT.

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

1) Профили версий

Ядро опирается на интерфейс профиля On1kel\\OAS\\Contract\\Profile\\SpecProfile. Реализации профилей (например, для OAS 3.1/3.2) могут поставляться отдельными пакетами вашего проекта. Ниже — минимальный пример профиля для демонстрации (под нужды проекта реализуйте полноценную версию):

Зарегистрируйте профиль и выберите его по содержимому документа:

2) Разрешение $ref и парсинг

3) Сериализация модели → массив/JSON

4) Обход дерева (Walker + Visitor)

5) Валидация

Архитектура (обзор)

• Модели (On1kel\OAS\Model\*): строгие неизменяемые классы, отражающие структуру OpenAPI.
• Парсинг (Parsing\DocumentParser): преобразует массив → модели; разрешает $ref через RefResolver.
• Ссылки (Ref\*): DefaultRefFetcher грузит внешние ресурсы по PSR-клиенту; RefResolver управляет стеком, глубиной и циклами.
• Сериализация (Serialize\*): DefaultNormalizer и DefaultSerializer преобразуют модели обратно.
• Профили (Contract\Profile\*, Version\*): SpecProfile, ProfileRegistry, VersionDetector, ParseOptions.
• Обход (Traverse\Walker, Contract\Traverse\NodeVisitor): DFS-проход с JSON Pointer.
• Валидация (Validation\*): композиция правил, зависящих от профиля и строгого/мягкого режима (Strictness).

Скрипты разработчика

Доступны composer-скрипты:

• composer test — PHPUnit ^11.2
• composer phpstan — статический анализ на максимальном уровне
• composer cs:check / composer cs:fix — PHP CS Fixer
• composer infection — мутационное тестирование (порог MSI настраивается скриптом)

Пример: чтение из файла и полный цикл

Полезные классы (быстрые ссылки)

• On1kel\OAS\Model\OpenApiDocument — корневой объект.
• On1kel\OAS\Parsing\DocumentParser — парсинг и $ref.
• On1kel\OAS\Ref\RefResolver, On1kel\OAS\Ref\DefaultRefFetcher — разрешение ссылок, загрузка по URI.
• On1kel\OAS\Serialize\DefaultSerializer, DefaultNormalizer, DefaultDenormalizer, TypeRegistry — сериализация/денормализация.
• On1kel\OAS\Version\ProfileRegistry, VersionDetector, ParseOptions — профили и выбор версии.
• On1kel\OAS\Contract\Traverse\NodeVisitor, Traverse\Walker — обход дерева.
• On1kel\OAS\Validation\CompositeValidator и правила в Validation\Rule\* — валидация.

Ограничения и заметки

• Реализации SpecProfile умышленно отделены от ядра: подключайте собственные профили или сторонние пакеты под нужные версии OAS.
• Для внешних $ref требуется доступный PSR-18 клиент и PSR-17 фабрики.
• Защита от бесконечных циклов $ref: глубина управляется через ParseOptions::withMaxRefDepth(...) и исключения Ref\Exception\*.

Лицензия

MIT © on1kel