php json schema model generator
verging property metadata
Génère des classes de modèles PHP à partir de fichiers JSON-Schema, y compris la validation et fournit une complétion automatique fluide pour les classes générées.
Exemple simple d'une application PHP : vous définissez et documentez une API avec des annotations swagger et des modèles JSON-Schema. Vous souhaitez maintenant utiliser des modèles dans les actions de votre contrôleur au lieu d'accéder manuellement aux données de la demande (par exemple, des éléments de tableau). De plus, votre schéma définit déjà les règles de validation pour les modèles. Pourquoi dupliquer ces règles dans votre code écrit manuellement ? Au lieu de cela, vous pouvez configurer un middleware qui instancie les modèles générés avec cette bibliothèque et alimenter le modèle avec les données de la demande. Vous disposez désormais d'un modèle validé que vous pouvez utiliser dans l'action de votre contrôleur. Avec complétion entièrement automatique lorsque vous travaillez avec des objets imbriqués. Ouais!
La méthode recommandée pour installer php-json-schema-model-generator consiste à utiliser Composer :
$ composer require --dev wol-soft/php-json-schema-model-generator
$ composer require wol-soft/php-json-schema-model-generator-production
Pour éviter d'ajouter toutes les dépendances du php-json-schema-model-generator à vos dépendances de production, il est recommandé d'ajouter la bibliothèque en tant que dépendance de développement et d'inclure la bibliothèque wol-soft/php-json-schema-model-generator-production . La bibliothèque de production fournit toutes les classes pour exécuter le code généré. La génération des classes doit être soit une étape effectuée dans l'environnement de développement, soit une étape de construction de votre application (ce qui est le flux de travail recommandé).
Consultez la documentation pour plus de détails.
L'objet de base pour générer des modèles est le ModelGenerator . Après avoir créé un générateur, vous pouvez utiliser l'objet pour générer vos classes de modèle sans aucune configuration supplémentaire :
( new ModelGenerator ())
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );Le premier paramètre de la méthode generateModels doit être une classe implémentant SchemaProviderInterface . Le fournisseur récupère les fichiers de schéma JSON et les fournit au générateur. Les fournisseurs suivants sont disponibles :
| Fournisseur | Description |
|---|---|
| Fournisseur d'annuaire récursif | Récupère tous les fichiers *.json du répertoire source donné. Chaque fichier doit contenir une définition d'objet de schéma JSON au niveau supérieur |
| Fournisseur OpenAPIv3 | Récupère tous les objets définis dans la #/components/schemas section d'un fichier de spécifications Open API v3 |
Le deuxième paramètre doit pointer vers un répertoire existant et vide (vous pouvez utiliser la méthode d'assistance generateModelDirectory pour créer votre répertoire de destination). Ce répertoire contiendra les classes PHP générées une fois le générateur terminé.
En tant que paramètre facultatif, vous pouvez configurer un objet GeneratorConfiguration (consultez la documentation pour toutes les options disponibles) pour configurer votre générateur et/ou utiliser la méthode generateModelDirectory pour générer votre répertoire modèle (généra le répertoire s'il n'existe pas ; si s'il existe, tous les fichiers et dossiers contenus seront supprimés pour un processus de génération propre) :
$ generator = new ModelGenerator (
( new GeneratorConfiguration ())
-> setNamespacePrefix ( ' MyAppModel ' )
-> setImmutable ( false )
);
$ generator
-> generateModelDirectory ( __DIR__ . ' /result ' );
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );Le générateur vérifiera récursivement le répertoire source donné et convertira tous les fichiers *.json trouvés en modèles. Tous les fichiers JSON-Schema contenus dans le répertoire source doivent fournir le schéma d'un objet.
Le répertoire ./tests/manual contient quelques exemples simples qui montrent l'utilisation. Après avoir installé les dépendances de la bibliothèque via composer update vous pouvez exécuter php ./tests/manual/test.php pour générer les exemples et jouer avec certains fichiers JSON-Schema pour explorer la bibliothèque.
Jetons un coup d'œil à un exemple simple. Nous créons un modèle simple pour une personne avec un nom et un âge facultatif. Notre schéma JSON résultant :
{
"$id" : " Person " ,
"type" : " object " ,
"properties" : {
"name" : {
"type" : " string "
},
"age" : {
"type" : " integer " ,
"minimum" : 0
}
},
"required" : [
" name "
]
} Après avoir généré une classe avec ce schéma JSON, notre classe portant le nom Person fournira l'interface suivante :
// the constructor takes an array with data which is validated and applied to the model
public function __construct( array $ modelData );
// the method getRawModelDataInput always delivers the raw input which was provided on instantiation
public function getRawModelDataInput(): array ;
// getters to fetch the validated properties. Age is nullable as it's not required
public function getName(): string ;
public function getAge(): ? int ;
// setters to change the values of the model after instantiation (only generated if immutability is disabled)
public function setName( string $ name ): Person ;
public function setAge(? int $ age ): Person ;Voyons maintenant le comportement du modèle généré :
// Throws an exception as the required name isn't provided.
// Exception: 'Missing required value for name'
$ person = new Person ([]);
// Throws an exception as the name provides an invalid value.
// Exception: 'Invalid type for name. Requires string, got int'
$ person = new Person ([ ' name ' => 12 ]);
// Throws an exception as the age contains an invalid value due to the minimum definition.
// Exception: 'Value for age must not be smaller than 0'
$ person = new Person ([ ' name ' => ' Albert ' , ' age ' => - 1 ]);
// A valid example as the age isn't required
$ person = new Person ([ ' name ' => ' Albert ' ]);
$ person -> getName (); // returns 'Albert'
$ person -> getAge (); // returns NULL
$ person -> getRawModelDataInput (); // returns ['name' => 'Albert']
// If setters are generated the setters also perform validations.
// Exception: 'Value for age must not be smaller than 0'
$ person -> setAge (- 10 );Messages d'exception plus complexes, par exemple. à partir d'une composition allOf peut ressembler à :
Invalid value for Animal declined by composition constraint.
Requires to match 3 composition elements but matched 1 elements.
- Composition element #1: Failed
* Value for age must not be smaller than 0
- Composition element #2: Valid
- Composition element #3: Failed
* Value for legs must not be smaller than 2
* Value for legs must be a multiple of 2
Le processus de génération de classe se divise essentiellement en trois ou quatre étapes :
La bibliothèque est testée via PHPUnit.
Après avoir installé les dépendances de la bibliothèque via composer update vous pouvez exécuter les tests avec ./vendor/bin/phpunit (Linux) ou vendorbinphpunit.bat (Windows). Les noms des tests sont optimisés pour l'utilisation de la sortie --testdox . La plupart des tests sont des tests d'intégration atomique qui créeront un fichier de schéma JSON, généreront une classe à partir du schéma et testeront ensuite le comportement de la classe générée.
Pendant l'exécution, les tests créeront un répertoire PHPModelGeneratorTest dans tmp dans lequel les fichiers de schéma JSON et les classes PHP seront écrits.
Si un test qui crée une classe PHP à partir d'un schéma JSON échoue au schéma JSON et la ou les classes générées seront vidées dans le répertoire ./failed-classes
La documentation de la bibliothèque est générée avec Sphinx.
Pour générer la documentation, installez Sphinx, entrez dans le répertoire docs et exécutez make html (Linux) ou make.bat html (Windows). La documentation générée sera disponible dans le répertoire ./docs/build .
La documentation hébergée sur Read the Docs est mise à jour à chaque poussée.
