Download the PHP package skiexx/laravel-data-scramble without Composer

On this page you can find all versions of the php package skiexx/laravel-data-scramble. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of skiexx/laravel-data-scramble

Informations about the package laravel-data-scramble

Laravel Data Scramble

Demo-проект

Бесплатное расширение для dedoc/scramble, которое автоматически генерирует OpenAPI-схемы из классов spatie/laravel-data.

Пакет анализирует ваши Data, Resource и Dto классы, используемые как входные параметры контроллеров (вместо FormRequest) и как возвращаемые типы (вместо JsonResource), и строит полноценную OpenAPI-документацию для каждого маршрута.

Возможности

Требования

Установка

Сервис-провайдер регистрируется автоматически через Laravel auto-discovery. Расширение Scramble также регистрируется автоматически при загрузке пакета.

Публикация конфигурации (опционально)

Файл конфигурации будет создан в config/skiexx-data-scramble.php.

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

После установки пакет начинает работать сразу. Никаких дополнительных настроек не требуется.

Пример контроллера

Пример Data-класса

Этот класс автоматически сгенерирует OpenAPI-схему:

Конфигурация

Поддерживаемые типы

Скалярные типы

PHP-тип OpenAPI-тип
string type: string
int type: integer
float type: number
bool type: boolean
array type: array
mixed без ограничений

Даты

PHP-тип OpenAPI
Carbon\Carbon type: string, format: date-time
Carbon\CarbonImmutable type: string, format: date-time
DateTime type: string, format: date-time
DateTimeImmutable type: string, format: date-time
DateTimeInterface type: string, format: date-time
DateInterval type: string, format: duration

Перечисления (Enum)

Backed enum автоматически преобразуется в соответствующий тип с перечислением допустимых значений:

Результат:

Для int-backed enum будет использован type: integer.

Вложенные Data-объекты

Вложенные объекты автоматически создают $ref-ссылки в #/components/schemas/:

Результат:

Коллекции Data-объектов

Результат:

Маппинг атрибутов валидации

Пакет автоматически преобразует атрибуты валидации spatie/laravel-data в соответствующие ограничения OpenAPI:

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

Атрибут string integer/number array
#[Min(n)] minLength: n minimum: n minItems: n
#[Max(n)] maxLength: n maximum: n maxItems: n
#[Between(a,b)] minLength + maxLength minimum + maximum minItems + maxItems
#[Size(n)] minLength = maxLength = n minimum = maximum = n minItems = maxItems = n

Форматы

Атрибут OpenAPI
#[Email] format: email
#[Url] format: uri
#[Uuid] format: uuid
#[Ulid] format: ulid
#[IP] format: ip
#[IPv4] format: ipv4
#[IPv6] format: ipv6
#[Date] format: date
#[Json] contentMediaType: application/json
#[Image] format: binary
#[File] format: binary

Паттерны

Атрибут OpenAPI pattern
#[Regex('/pat/')] значение регулярного выражения
#[Alpha] ^[a-zA-Z]+$
#[AlphaDash] ^[a-zA-Z0-9_-]+$
#[AlphaNumeric] ^[a-zA-Z0-9]+$
#[Lowercase] ^[a-z]+$
#[Uppercase] ^[A-Z]+$
#[Digits(n)] ^\d{n}$
#[DigitsBetween(a,b)] ^\d{a,b}$
#[StartsWith('a','b')] ^(a\|b)
#[EndsWith('a','b')] (a\|b)$

Прочие

Атрибут Эффект
#[Nullable] nullable: true
#[MultipleOf(n)] расширение x-multipleOf: n (для number)

Атрибуты без прямого аналога в OpenAPI (Exists, Unique, Same, Different, Confirmed и др.) молча пропускаются.

Переименование свойств

Пакет полностью поддерживает механизм маппинга имен spatie/laravel-data.

На уровне класса

На уровне свойства

Поддерживаемые маперы

Обработка специальных свойств

Nullable

Default-значения

Hidden

Поведение настраивается через skip_hidden в конфигурации.

Computed

Свойство fullName получит readOnly: true в OpenAPI-схеме. Поведение настраивается через computed_as_readonly.

Lazy

Lazy-свойства по умолчанию считаются необязательными. Поведение настраивается через lazy_as_optional.

Интерфейс OpenApiSchema

Для случаев, когда автоматическая генерация схемы не подходит, вы можете определить схему вручную через интерфейс OpenApiSchema.

Ручное определение схемы

Этот интерфейс можно повесить на любой класс -- он не обязан наследовать Data. Расширение Scramble распознает его автоматически.

Автогенерация через HasOpenApiSchema

Если класс наследует Data и вы хотите реализовать OpenApiSchema без ручного описания всех свойств, используйте трейт HasOpenApiSchema:

Трейт автоматически генерирует массив схемы на основе свойств класса. Это полезно, когда вы хотите, чтобы другие части вашего приложения могли вызвать UserData::openApiSchema() для получения схемы программно.

Трейты форматов

Пакет предоставляет набор трейтов, которые можно использовать на классах, реализующих OpenApiSchema, для стандартных типов:

Трейт OpenAPI type OpenAPI format
StringFormat string --
IntegerFormat integer --
NumberFormat number --
BooleanFormat boolean --
ArrayFormat array --
DateFormat string date-time
UuidFormat string uuid
EmailFormat string email

Пример использования

Результат:

Data-классы как входные параметры контроллера

Пакет автоматически распознает Data-классы, используемые как параметры методов контроллера, и правильно генерирует OpenAPI-параметры:

Пример

Результат — query parameters:

Для POST-запросов

Результат — request body (application/json).

Поддержка #[FromRouteParameter]

Используйте встроенный атрибут laravel-data для свойств, которые берутся из маршрута:

Результат:

Свойство userId не попадает в body — оно отображается как path parameter с именем user (из атрибута #[FromRouteParameter('user')]).

Поддержка #[FromRouteParameterProperty]

Для получения свойства модели из route parameter:

Свойства с #[FromRouteParameterProperty] также исключаются из query/body и не попадают в документацию как параметры запроса.

Маппинг имен для входных параметров

При использовании #[MapInputName] или #[MapName], имена параметров в OpenAPI будут соответствовать маппингу:

Атрибут ResponseData

Когда контроллер возвращает анонимный JsonResource для обертки ответа в { "data": ... }, Scramble не может определить реальный тип данных. Атрибут #[ResponseData] решает эту проблему.

Проблема

Решение

Параметры атрибута

Параметр Тип По умолчанию Описание
dataClass string (обязательный) FQCN Data-класса
collection bool false Массив объектов { "data": [{...}] }
paginated bool false LengthAwarePaginator с meta + links
cursorPaginated bool false CursorPaginator с meta
status int 200 HTTP status code (например 201 для POST Create)
wrapped bool true Обертка { "data": ... }, для paginated всегда true

Примеры использования

Одиночный объект

Результат:

Коллекция

Результат:

Пагинация (LengthAwarePaginator)

Результат включает полную структуру пагинации Laravel:

Cursor-пагинация

Результат:

Кастомный status code

Без обертки

Если ответ не обернут в { "data": ... }:

Результат -- прямая ссылка на схему без обертки:

Для коллекции без обертки:

Результат:

Примечание: для paginated и cursorPaginated параметр wrapped игнорируется -- обертка с data, meta и links применяется всегда, так как это стандартный формат ответа Laravel-пагинатора.

Продвинутая настройка

Ручная регистрация расширения

Если вам нужно контролировать момент регистрации или регистрировать расширение только для определенного API:

Подмена резолверов

Если вам нужно изменить логику генерации схемы, вы можете создать собственное расширение, наследующее LaravelDataTypeToSchemaExtension:

Зарегистрируйте своё расширение:

Подмена ValidationAttributeMap

Для добавления поддержки собственных атрибутов валидации или изменения маппинга существующих:

Собственный DataClassSchemaResolver

Для полного контроля над процессом генерации схемы:

И используйте его в своем расширении:

Использование с несколькими API Scramble

Если вы используете несколько API-документаций в Scramble:

Разработка

Docker-окружение

Проект включает Docker-конфигурацию для разработки без локальной установки PHP:

Стандарты кода

Архитектура

Как это работает

  1. Scramble при генерации документации вызывает shouldHandle() на каждом расширении для каждого типа, найденного в контроллерах.

  2. LaravelDataTypeToSchemaExtension проверяет, является ли тип наследником BaseData (Data, Resource, Dto) или реализует OpenApiSchema.

  3. DataClassSchemaResolver получает метаданные класса через DataConfig::getDataClass() и для каждого свойства:

    • Проверяет, не скрыто ли оно (#[Hidden])
    • Определяет имя через NameMappingResolver (с учетом #[MapOutputName])
    • Определяет тип через PropertyTypeResolver (скаляры, даты, enum, вложенные Data)
    • Применяет ограничения через ValidationConstraintResolver (Min, Max, Email и др.)
    • Обрабатывает nullable, lazy, computed, default

  4. reference() создает $ref-ссылку через ClassBasedReference, чтобы вложенные объекты не дублировались inline, а были вынесены в #/components/schemas/.

  5. ResponseDataOperationExtension работает на уровне операций (после ResponseExtension): читает #[ResponseData] атрибут с метода контроллера и заменяет response schema, которую Scramble сгенерировал для анонимного JsonResource, на правильную схему с указанным Data-классом, оберткой и пагинацией.

Лицензия

MIT

All versions of laravel-data-scramble with dependencies

PHP Build Version
Package Version
Requires php Version ^8.4
spatie/laravel-package-tools Version ^1.16
illuminate/contracts Version ^12.0
dedoc/scramble Version ^0.13
spatie/laravel-data Version ^4.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package skiexx/laravel-data-scramble contains the following files

Loading the files please wait ...