dto generator

Генерировать классы DTO с нулевыми зависимостями времени выполнения

Этот пакет позволяет генерировать чистые и независимые DTO-классы (также называемые «объектами значения») с помощью кратко объявленной схемы в PHP-коде.

Установка

Вам нужен только этот пакет в среде разработки, поскольку сгенерированные классы ничего не используют из кода этой библиотеки. Вот почему предпочтительным способом является включение его как require-dev :

 $ composer require --dev klkvsk/dto-generator

Требования

• PHP 8.1+: запустить генератор в разработке
• PHP 7.4 или 8.x: для использования сгенерированного кода в производстве

Использование

1. Создать схему

Схема-это обычный PHP-файл в любом месте вашего проекта. Файл должен вернуть объект Schema с верхнего уровня.

Пример схемы:

 <?php
use Klkvsk  DtoGenerator  Schema as dto ;
use Klkvsk  DtoGenerator  Schema  Types as t ;

return dto schema (
    namespace: ' MyProjectData ' ,
    objects: [
        new dto  object (
            name: ' Person ' ,
            fields: [
                dto field ( ' name ' , t string (), required: true ),
                dto field ( ' age ' , t int (), required: true ),
            ]
        ),
    ]
);

2. Сгенерировать файлы

Генерация кода выполняется с помощью команды dto-gen :

 $ ./vendor/bin/dto-gen [schema-file]

По умолчанию генератор ищет файлы, именованные или заканчивающиеся dto.schema.php , но вы можете предоставить файлы схемы вручную в качестве аргументов.

Генератор попытается угадать правильный путь для вывода, посмотрев на пути автозагрузки в composer.json. Если в нем указано картирование PSR-4 для "MyProject\": "src/" то приведенный выше файл будет размещен в src/Data/Person.php .

Чтобы переопределить это поведение, вы можете напрямую указать outputDir :

 dto schema (namespace: " MyProject \ Data " , outputDir: " src/generated/ " , ...);

Функции

Совместимость с обратной стороны

Чтобы сгенерировать код, нацеленную на некоторую минимальную версию PHP, используйте:

 ./vendor/bin/dto-gen --target 7.4

Эта опция включает или отключает некоторые новые языковые функции в полученном коде.

Перечисления

Можно генерировать не только DTO, но и связанные перечисления:

 dto schema(
    objects: [
        dto enum (
            name: ' PostStatus '
            cases: [ ' draft ' , ' published ' , ' deleted ' ]
        ),
        dto object(
            name: ' Post ' ,
            fields: [
                dto field ( ' status ' , t enum ( ' PostStatus ' ), required: true ),
                . . .
            ]
        )
    ]
)

Для PHP> = 8,0 нативные перечисления будут сгенерированы, для более старых версий используется очень похожая реализация на основе классов.

Типовая система

DTO служат целью, чтобы ваши данные сильно набрали. Типы для схемы:

• tint , tbool , tstring , tfloat - основные скалярные типы
• tenum , tobject - для ссылки на другие объекты DTO
• tdate - Использование DateTimeImtable
• texternal - для ссылки на любые другие классы не -DTO
• tlist_(T) - оборачивает тип t, чтобы объявить t []
• tmixed - если вы действительно не знаете

(где t является псевдонимом для KlkvskDtoGeneratorSchemaTypes )

Кроме того, вы можете расширить класс абстрактного Type для ваших нужд.

Гидратация и проверка

DTOS может быть создан с помощью обычного конструктора или с методом <DTO>::create(array $data) .

Метод create принимает ассоциативный массив с данными. Затем эти данные фильтруют (если они требуют некоторой очистки заранее) и импортируются (преобразуются в правильные типы). После этого метод вызывает конструктор по умолчанию, передавая им импортированные поля. Поля конструктора, подтвержденные не только по типу, но и по пользовательской логике.

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

1. filter готовит данные для импорта
2. importer отбрасывает значение для правильного типа или экземпляра вложенного объекта
3. Проверки validator , которые импортируемая стоимость соответствует указанным критериям

Закрытие filter и importer должно вернуть обработанное значение. Если null возвращается, дальнейшие закрытия не называются.

validator возвращает true/false, а на false InvalidArgumentException выбрасывается автоматически. Кроме того, вы можете сделать свое исключение и ничего не вернуть.

Закрытие filter типа и validator определены в схеме:

 dtofield('age', tint(),
    filters: [ fn ($x) => preg_replace('/[^0-9]+/', $x) ],
    validators: [ fn ($x) => $x > 0 && $x < 100 ]
)

Закрытие importer типа предопределено для всех типов, кроме tobject :

 dtofield('file', texternal(SplFileInfo::class, fn ($x) => new SplFileInfo($x))

Вы можете указать пользовательский импортер, если вы расширяете Type для ваших собственных потребностей.

Примеры

См. / Пример / Dir для примера схемы и сгенерированных классов для разных версий PHP.

Лицензия

Лицензия MIT (MIT). Пожалуйста, смотрите файл лицензии для получения дополнительной информации.