dto generator

Generar clases de DTO con dependencias de tiempo de ejecución cero

Este paquete le permite generar clases DTO limpias e independientes (también llamadas "objetos de valor") mediante un esquema declarado brevemente en el código PHP.

Instalación

Solo necesita este paquete en el entorno de desarrollo, ya que las clases generadas no usan nada del código de esta biblioteca. Es por eso que la forma preferida es incluirlo como require-dev :

 $ composer require --dev klkvsk/dto-generator

Requisitos

• PHP 8.1+: Ejecutar el generador en el desarrollo
• Php 7.4 u 8.x: utilizar el código generado en la producción

Uso

1. Crear archivo de esquema

El esquema es un archivo PHP regular en cualquier lugar de su proyecto. El archivo debe devolver un objeto Schema desde el nivel superior.

Ejemplo de esquema:

 <?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. Generar archivos

La generación de código se realiza con el comando dto-gen :

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

De manera predeterminada, el generador busca archivos nombrados o terminando con dto.schema.php , pero puede proporcionar archivos de esquema manualmente como argumentos.

El generador intentará adivinar la ruta correcta para la salida al observar las rutas de AutOload en composer.json. Si establece la asignación de PSR-4 para "MyProject\": "src/" entonces el archivo anterior se colocará en src/Data/Person.php .

Para anular este comportamiento, puede especificar outputDir directamente:

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

Características

Compatibilidad con retroceso

Para generar código dirigido a una versión mínima de PHP, use:

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

Esta opción habilita o deshabilita algunas características de idioma más nuevas en el código resultante.

Enumeraciones

Es posible generar no solo DTO, sino también enums relacionados:

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

Para PHP> = 8.0 se generarán enums nativos, para versiones anteriores se utiliza una implementación basada en clases muy similar.

Sistema tipo

Los DTO tienen un propósito para mantener sus datos fuertemente escritos. Los tipos para el esquema son:

• tint , tbool , tstring , tfloat - tipos escalar básicos
• tenum , tobject - para hacer referencia a otros objetos DTO
• tdate - usando DateTimeMutable
• texternal - para hacer referencia a cualquier otra clase que no sea DTO
• tlist_(T) - envuelve el tipo t para declarar t []
• tmixed - si realmente no lo sabes

(Donde t es un alias para KlkvskDtoGeneratorSchemaTypes )

Además, puede extender la clase Type abstracto para sus necesidades.

Hidratación y validación

Los DTO se pueden crear con un constructor regular o con el método <DTO>::create(array $data) .

El método create acepta una matriz asociativa con datos. Esos datos se filtran (si necesita algo de limpieza de antemano) y se importa (convertido a los tipos adecuados). Después de eso, el método llama a un constructor predeterminado, pasando los campos importados a él. El constructor obtiene campos validados no solo por tipo, sino por una lógica personalizada.

Por lo tanto, hay tres etapas de manipulación de datos, cada una puede describirse en el esquema con llamadas:

1. filter prepara los datos que se importan
2. importer emite valor para corregir el tipo o instancias de un objeto anidado
3. verificaciones validator que el valor importado cumple con los criterios especificados

Los cierres filter y importer deben devolver el valor procesado. Si se devuelve un null , no se llaman más cierres.

validator Devuelve True/False, y en falso una InvalidArgumentException se arroja automáticamente. Además, puede lanzar su propia excepción y no devolver nada.

Los cierres de filter de tipo y validator se definen en el esquema:

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

El cierre del tipos importer está predefinido para todos los tipos, excepto tobject :

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

Puede especificar un importador personalizado si extiende Type para sus propias necesidades.

Ejemplos

Consulte / Ejemplo / Dir para el esquema de ejemplo y las clases generadas para diferentes versiones de PHP.

Licencia

La licencia MIT (MIT). Consulte el archivo de licencia para obtener más información.