dto generator

Gerar classes DTO com zero de dependências de tempo de execução

Este pacote permite gerar classes dto limpas e independentes (também chamadas de "Objetos de Valor") por esquema declarado brevemente no código PHP.

Instalação

Você só precisa deste pacote em ambiente de desenvolvimento, pois as classes geradas não usam nada do código desta biblioteca. É por isso que a maneira preferida é incluí-lo como require-dev :

 $ composer require --dev klkvsk/dto-generator

Requisitos

• Php 8.1+: para executar o gerador em desenvolvimento
• Php 7.4 ou 8.x: para usar o código gerado na produção

Uso

1. Crie arquivo de esquema

O esquema é um arquivo PHP regular em qualquer lugar do seu projeto. O arquivo deve retornar um objeto Schema do nível superior.

Exemplo 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. Gere arquivos

A geração de código é feita com o comando dto-gen :

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

Por padrão, o gerador pesquisa arquivos nomeados ou terminando com dto.schema.php , mas você pode fornecer arquivos de esquema manualmente como argumentos.

O gerador tentará adivinhar o caminho certo para a saída, analisando os caminhos automáticos no composer.json. Se ele esteclar o mapeamento do PSR-4 para "MyProject\": "src/" , o arquivo acima será colocado em src/Data/Person.php .

Para substituir esse comportamento, você pode especificar outputDir diretamente:

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

Características

Compatibilidade de volta

Para gerar o código direcionado a alguma versão mínima do PHP, use:

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

Esta opção permite ou desativa alguns recursos de idioma mais recentes no código resultante.

Enumerações

É possível gerar não apenas DTOs, mas também enumes 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 enumes nativos serão gerados, para versões mais antigas, é usada uma implementação de classe muito semelhante.

Sistema de tipo

Os DTOs têm um objetivo de manter seus dados digitados fortemente. Os tipos de esquema são:

• tint , tbool , tstring , tfloat - tipos básicos básicos
• tenum , tobject - para referenciar outros objetos DTO
• tdate - usando o DATETimeImutable
• texternal - para referenciar quaisquer outras classes não -DTO
• tlist_(T) - envolve o tipo t para declarar t []
• tmixed - se você realmente não sabe

(onde t é um alias para KlkvskDtoGeneratorSchemaTypes )

Além disso, você pode estender a classe Type abstrato para suas necessidades.

Hidratação e validação

Os DTOs podem ser criados com um construtor regular ou com o método <DTO>::create(array $data) .

O método create aceita uma matriz associativa com dados. Esses dados são filtrados (se precisar de alguma limpeza com antecedência) e importados (convertidos em tipos adequados). Depois disso, o método chama um construtor padrão, passando campos importados para ele. O construtor obtém campos validados não apenas por tipo, mas por uma lógica personalizada.

Portanto, existem três estágios de manipulação de dados, cada um pode ser descrito em esquema com callables:

1. filter prepara dados a serem importados
2. importer lança valor para corrigir o tipo ou instancia um objeto aninhado
3. Verificações validator que o valor importado atende aos critérios especificados

O fechamento filter e importer deve retornar o valor processado. Se um null for devolvido, outros fechamentos não serão chamados.

validator retorna true/false e, em false, um InvalidArgumentException é lançado automaticamente. Além disso, você pode lançar sua própria exceção e não retornar nada.

Os fechamentos de filter de tipo e validator são definidos no esquema:

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

O fechamento do importer de tipo é predefinido para todos os tipos, exceto tobject :

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

Você pode especificar um importador personalizado se estender Type para suas próprias necessidades.

Exemplos

Veja / exemplo / dir para o esquema de exemplo e classes geradas para diferentes versões PHP.

Licença

A licença do MIT (MIT). Consulte o arquivo de licença para obter mais informações.