php json schema model generator
verging property metadata
Generiert PHP-Modellklassen aus JSON-Schemadateien, einschließlich Validierung und Bereitstellung einer flüssigen automatischen Vervollständigung für die generierten Klassen.
Einfaches Beispiel aus einer PHP-Anwendung: Sie definieren und dokumentieren eine API mit Swagger-Annotationen und JSON-Schema-Modellen. Jetzt möchten Sie Modelle in Ihren Controller-Aktionen verwenden, anstatt manuell auf die Anforderungsdaten zuzugreifen (z. B. Array-Sachen). Darüber hinaus definiert Ihr Schema bereits die Validierungsregeln für die Modelle. Warum sollten Sie diese Regeln in Ihren manuell geschriebenen Code duplizieren? Stattdessen können Sie eine Middleware einrichten, die mit dieser Bibliothek generierte Modelle instanziiert und das Modell mit den Anforderungsdaten füttert. Jetzt verfügen Sie über ein validiertes Modell, das Sie in Ihrer Controller-Aktion verwenden können. Mit vollständiger automatischer Vervollständigung beim Arbeiten mit verschachtelten Objekten. Juhuu!
Die empfohlene Methode zur Installation des php-json-schema-model-generators ist Composer:
$ composer require --dev wol-soft/php-json-schema-model-generator
$ composer require wol-soft/php-json-schema-model-generator-production
Um zu vermeiden, dass alle Abhängigkeiten des php-json-schema-model-generators zu Ihren Produktionsabhängigkeiten hinzugefügt werden, wird empfohlen, die Bibliothek als Entwicklungsabhängigkeit hinzuzufügen und die wol-soft/php-json-schema-model-generator-produktionsbibliothek einzuschließen . Die Produktionsbibliothek stellt alle Klassen zur Ausführung des generierten Codes bereit. Das Generieren der Klassen sollte entweder ein Schritt in der Entwicklungsumgebung oder ein Build-Schritt Ihrer Anwendung sein (was der empfohlene Arbeitsablauf ist).
Weitere Informationen finden Sie in den Dokumenten.
Das Basisobjekt zum Generieren von Modellen ist der ModelGenerator . Nachdem Sie einen Generator erstellt haben, können Sie das Objekt ohne weitere Konfiguration zum Generieren Ihrer Modellklassen verwenden:
( new ModelGenerator ())
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );Der erste Parameter der Methode „generateModels“ muss eine Klasse sein, die SchemaProviderInterface implementiert. Der Anbieter ruft die JSON-Schemadateien ab und stellt sie für den Generator bereit. Folgende Anbieter stehen zur Verfügung:
| Anbieter | Beschreibung |
|---|---|
| RecursiveDirectoryProvider | Ruft alle *.json-Dateien aus dem angegebenen Quellverzeichnis ab. Jede Datei muss auf der obersten Ebene eine JSON-Schema-Objektdefinition enthalten |
| OpenAPIv3Provider | Ruft alle im #/components/schemas section einer Open API v3-Spezifikationsdatei definierten Objekte ab |
Der zweite Parameter muss auf ein vorhandenes und leeres Verzeichnis verweisen (Sie können die Hilfsmethode generateModelDirectory verwenden, um Ihr Zielverzeichnis zu erstellen). Dieses Verzeichnis enthält die generierten PHP-Klassen, nachdem der Generator fertig ist.
Als optionalen Parameter können Sie ein GeneratorConfiguration- Objekt einrichten (sehen Sie sich die Dokumente für alle verfügbaren Optionen an), um Ihren Generator zu konfigurieren und/oder die Methode „generateModelDirectory“ zum Generieren Ihres Modellverzeichnisses zu verwenden (erzeugt das Verzeichnis, wenn es nicht existiert; wenn es existiert, werden alle enthaltenen Dateien und Ordner für einen sauberen Generierungsprozess entfernt):
$ generator = new ModelGenerator (
( new GeneratorConfiguration ())
-> setNamespacePrefix ( ' MyAppModel ' )
-> setImmutable ( false )
);
$ generator
-> generateModelDirectory ( __DIR__ . ' /result ' );
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );Der Generator überprüft rekursiv das angegebene Quellverzeichnis und konvertiert alle gefundenen *.json-Dateien in Modelle. Alle JSON-Schema-Dateien im Quellverzeichnis müssen ein Schema eines Objekts bereitstellen.
Das Verzeichnis ./tests/manual enthält einige einfache Beispiele, die die Verwendung zeigen. Nachdem Sie die Abhängigkeiten der Bibliothek über composer update installiert haben, können Sie php ./tests/manual/test.php ausführen, um die Beispiele zu generieren, und mit einigen JSON-Schema-Dateien herumspielen, um die Bibliothek zu erkunden.
Schauen wir uns ein einfaches Beispiel an. Wir erstellen ein einfaches Modell für eine Person mit einem Namen und einem optionalen Alter. Unser resultierendes JSON-Schema:
{
"$id" : " Person " ,
"type" : " object " ,
"properties" : {
"name" : {
"type" : " string "
},
"age" : {
"type" : " integer " ,
"minimum" : 0
}
},
"required" : [
" name "
]
} Nachdem wir eine Klasse mit diesem JSON-Schema generiert haben, stellt unsere Klasse mit dem Namen Person die folgende Schnittstelle bereit:
// 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 ;Schauen wir uns nun das Verhalten des generierten Modells an:
// 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 );Komplexere Ausnahmemeldungen, z. aus einer allOf-Komposition könnte wie folgt aussehen:
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
Der Klassengenerierungsprozess gliedert sich grundsätzlich in drei bis vier Schritte:
Die Bibliothek wird über PHPUnit getestet.
Nach der Installation der Abhängigkeiten der Bibliothek per composer update können Sie die Tests mit ./vendor/bin/phpunit (Linux) oder vendorbinphpunit.bat (Windows) ausführen. Die Testnamen sind für die Verwendung der --testdox Ausgabe optimiert. Bei den meisten Tests handelt es sich um atomare Integrationstests, die eine JSON-Schemadatei einrichten, eine Klasse aus dem Schema generieren und anschließend das Verhalten der generierten Klasse testen.
Während der Ausführung der Tests wird in tmp ein Verzeichnis PHPModelGeneratorTest erstellt, in das JSON-Schema-Dateien und PHP-Klassen geschrieben werden.
Wenn ein Test, der eine PHP-Klasse aus einem JSON-Schema erstellt, fehlschlägt, werden das JSON-Schema und die generierten Klassen im Verzeichnis ./failed-classes abgelegt
Die Dokumente für die Bibliothek werden mit Sphinx generiert.
Um die Dokumentation zu generieren, installieren Sie Sphinx, geben Sie das Verzeichnis docs ein und führen Sie make html (Linux) oder make.bat html (Windows) aus. Die generierte Dokumentation steht im Verzeichnis ./docs/build zur Verfügung.
Die bei Read the Docs gehostete Dokumentation wird bei jedem Push aktualisiert.
