dto generator

Générer des classes DTO avec des dépendances d'exécution zéro

Ce package vous permet de générer des classes DTO propres et indépendantes (également appelées "objets de valeur") par schéma brièvement déclaré dans le code PHP.

Installation

Vous n'avez besoin que de ce package dans l'environnement de développement, car les classes générées n'utilisent rien à partir du code de cette bibliothèque. C'est pourquoi la manière préférée est de l'inclure en tant que require-dev :

 $ composer require --dev klkvsk/dto-generator

Exigences

• PHP 8.1+: pour exécuter un générateur en développement
• PHP 7.4 ou 8.x: utiliser du code généré en production

Usage

1. Créer un schéma-fichier

Le schéma est un fichier PHP régulier partout dans votre projet. Le fichier doit renvoyer un objet Schema du niveau supérieur.

Exemple de schéma:

 <?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. Générer des fichiers

La génération de code se fait avec la commande dto-gen :

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

Par défaut, le générateur recherche des fichiers nommés ou se terminant par dto.schema.php , mais vous pouvez fournir des fichiers de schéma manuellement sous forme d'arguments.

Générateur essaiera de deviner le bon chemin pour la sortie en examinant les chemins Autoload dans Composer.json. S'il indique le mappage PSR-4 pour "MyProject\": "src/" alors le fichier ci-dessus sera placé dans src/Data/Person.php .

Pour remplacer ce comportement, vous pouvez spécifier directement outputDir :

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

Caractéristiques

Compatibilité arrière

Pour générer du code ciblant une version minimale de PHP, utilisez:

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

Cette option permet ou désactive certaines fonctionnalités linguistiques plus récentes dans le code résultant.

Énumérations

Il est possible de générer non seulement des DTO, mais aussi des énumérations liées:

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

Pour PHP> = 8.0, les énumérements natifs seront générés, pour les versions plus anciennes, une implémentation très similaire basée sur une classe est utilisée.

Système de type

Les DTO servent à garder vos données fortement typées. Les types de schéma sont:

• tint , tbool , tstring , tfloat - types scalaires de base
• tenum , tobject - pour faire référence à d'autres objets DTO
• tdate - Utilisation de Datetimeimutable
• texternal - pour référence à toute autre classe non-DTO
• tlist_(T) - enveloppe autour du type t pour déclarer t []
• tmixed - si tu ne sais vraiment pas

(où t est un alias à KlkvskDtoGeneratorSchemaTypes )

En outre, vous pouvez étendre la classe Type abstrait pour vos besoins.

Hydratation et validation

Les DTO peuvent être créés avec un constructeur régulier ou avec <DTO>::create(array $data) .

Méthode create accepte un tableau associatif avec les données. Ces données sont ensuite filtrées (si elles ont besoin de nettoyage à l'avance) et importées (converties en types appropriés). Après cela, la méthode appelle un constructeur par défaut, passant des champs importés. Le constructeur obtient des champs validés non seulement par type, mais par une logique personnalisée.

Ainsi, il y a trois étapes de la manipulation des données, chacune peut être décrite dans le schéma avec callmables:

1. filter prépare les données à importer
2. importer jette la valeur pour corriger le type ou instancier un objet imbriqué
3. Les vérifications validator que la valeur importée répond aux critères spécifiés

Les fermetures filter et importer doivent renvoyer la valeur traitée. Si un null est retourné, d'autres fermetures ne sont pas appelées.

validator Renvoie True / False, et sur FAUX, un InvalidArgumentException est lancé automatiquement. En outre, vous pouvez lancer votre propre exception et ne rien retourner.

Les fermetures du filter de type et validator sont définies dans le schéma:

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

La fermeture de importer de type est prédéfinie pour tous les types sauf tobject :

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

Vous pouvez spécifier un importateur personnalisé si vous étendez Type pour vos propres besoins.

Exemples

Voir / exemple / dir pour l'exemple de schéma et les classes générées pour différentes versions PHP.

Licence

La licence MIT (MIT). Veuillez consulter le fichier de licence pour plus d'informations.