php json schema model generator
verging property metadata
Genera clases de modelo PHP a partir de archivos JSON-Schema, incluida la validación y proporciona una finalización automática fluida para las clases generadas.
Ejemplo simple de una aplicación PHP: define y documenta una API con anotaciones arrogantes y modelos de esquema JSON. Ahora desea utilizar modelos en las acciones de su controlador en lugar de acceder manualmente a los datos de la solicitud (por ejemplo, elementos de matriz). Además, su esquema ya define las reglas de validación para los modelos. ¿Por qué duplicar estas reglas en su código escrito manualmente? En su lugar, puede configurar un middleware que cree instancias de los modelos generados con esta biblioteca y alimente el modelo con los datos de la solicitud. Ahora tienes un modelo validado que puedes usar en tu acción de controlador. Con finalización automática completa cuando se trabaja con objetos anidados. ¡Hurra!
La forma recomendada de instalar php-json-schema-model-generator es a través de Composer:
$ composer require --dev wol-soft/php-json-schema-model-generator
$ composer require wol-soft/php-json-schema-model-generator-production
Para evitar agregar todas las dependencias de php-json-schema-model-generator a sus dependencias de producción, se recomienda agregar la biblioteca como una dependencia de desarrollo e incluir la biblioteca wol-soft/php-json-schema-model-generator-production. . La biblioteca de producción proporciona todas las clases para ejecutar el código generado. La generación de las clases debe ser un paso realizado en el entorno de desarrollo o como un paso de compilación de su aplicación (que es el flujo de trabajo recomendado).
Consulte los documentos para obtener más detalles.
El objeto base para generar modelos es ModelGenerator . Después de haber creado un Generador, puede usar el objeto para generar sus clases de modelo sin ninguna configuración adicional:
( new ModelGenerator ())
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );El primer parámetro del método generateModels debe ser una clase que implemente SchemaProviderInterface . El proveedor recupera los archivos de esquema JSON y los proporciona al generador. Los siguientes proveedores están disponibles:
| Proveedor | Descripción |
|---|---|
| Proveedor de directorio recursivo | Recupera todos los archivos *.json del directorio fuente indicado. Cada archivo debe contener una definición de objeto de esquema JSON en el nivel superior |
| Proveedor OpenAPIv3 | Recupera todos los objetos definidos en la #/components/schemas section de un archivo de especificaciones Open API v3 |
El segundo parámetro debe apuntar a un directorio existente y vacío (puede usar el método auxiliar generateModelDirectory para crear su directorio de destino). Este directorio contendrá las clases PHP generadas una vez finalizado el generador.
Como parámetro opcional, puede configurar un objeto GeneratorConfiguration (consulte los documentos para conocer todas las opciones disponibles) para configurar su Generador y/o usar el método generateModelDirectory para generar el directorio de su modelo (generará el directorio si no existe; si existe, todos los archivos y carpetas contenidos se eliminarán para un proceso de generación limpio):
$ generator = new ModelGenerator (
( new GeneratorConfiguration ())
-> setNamespacePrefix ( ' MyAppModel ' )
-> setImmutable ( false )
);
$ generator
-> generateModelDirectory ( __DIR__ . ' /result ' );
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );El generador verificará el directorio fuente dado de forma recursiva y convertirá todos los archivos *.json encontrados en modelos. Todos los archivos JSON-Schema dentro del directorio de origen deben proporcionar un esquema de un objeto.
El directorio ./tests/manual contiene algunos ejemplos sencillos que muestran el uso. Después de instalar las dependencias de la biblioteca mediante composer update puede ejecutar php ./tests/manual/test.php para generar los ejemplos y jugar con algunos archivos JSON-Schema para explorar la biblioteca.
Echemos un vistazo a un ejemplo sencillo. Creamos un modelo sencillo para una persona con un nombre y una edad opcional. Nuestro esquema JSON resultante:
{
"$id" : " Person " ,
"type" : " object " ,
"properties" : {
"name" : {
"type" : " string "
},
"age" : {
"type" : " integer " ,
"minimum" : 0
}
},
"required" : [
" name "
]
} Después de generar una clase con este esquema JSON, nuestra clase con el nombre Person proporcionará la siguiente interfaz:
// 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 ;Ahora echemos un vistazo al comportamiento del modelo generado:
// 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 );Mensajes de excepción más complejos, por ejemplo. de una composición allOf puede verse así:
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
El proceso de generación de clases básicamente se divide en tres o cuatro pasos:
La biblioteca se prueba a través de PHPUnit.
Después de instalar las dependencias de la biblioteca mediante composer update puede ejecutar las pruebas con ./vendor/bin/phpunit (Linux) o vendorbinphpunit.bat (Windows). Los nombres de las pruebas están optimizados para el uso de la salida --testdox . La mayoría de las pruebas son pruebas de integración atómica que configurarán un archivo de esquema JSON y generarán una clase a partir del esquema y luego probarán el comportamiento de la clase generada.
Durante la ejecución, las pruebas crearán un directorio PHPModelGeneratorTest en tmp donde se escribirán los archivos JSON-Schema y las clases PHP.
Si una prueba que crea una clase PHP a partir de un esquema JSON falla, el esquema JSON y las clases generadas se volcarán al directorio ./failed-classes
Los documentos de la biblioteca se generan con Sphinx.
Para generar la documentación instale Sphinx, ingrese al directorio docs y ejecute make html (Linux) o make.bat html (Windows). La documentación generada estará disponible en el directorio ./docs/build .
La documentación alojada en Read the Docs se actualiza con cada envío.
