php json schema model generator
verging property metadata
JSON スキーマ ファイルから PHP モデル クラスを生成します。これには検証が含まれ、生成されたクラスのスムーズな自動補完が含まれます。
PHP アプリケーションの簡単な例: Swagger アノテーションと JSON スキーマ モデルを使用して API を定義し、文書化します。ここで、リクエスト データ (配列など) に手動でアクセスする代わりに、コントローラー アクションでモデルを使用したいとします。さらに、スキーマはモデルの検証ルールをすでに定義しています。このルールを手動で作成したコードに複製する必要があるのでしょうか?代わりに、このライブラリで生成されたモデルをインスタンス化し、モデルにリクエスト データをフィードするミドルウェアをセットアップできます。これで、コントローラーのアクションで使用できる検証済みのモデルが完成しました。ネストされたオブジェクトを操作する場合は完全に自動補完されます。わーい！
php-json-schema-model-generator をインストールする推奨される方法は、Composer を使用することです。
$ composer require --dev wol-soft/php-json-schema-model-generator
$ composer require wol-soft/php-json-schema-model-generator-production
php-json-schema-model-generator のすべての依存関係を運用環境の依存関係に追加しないようにするには、ライブラリを開発依存関係として追加し、wol-soft/php-json-schema-model-generator-production ライブラリを含めることをお勧めします。 。実稼働ライブラリは、生成されたコードを実行するためのすべてのクラスを提供します。クラスの生成は、開発環境で実行されるステップであるか、アプリケーションのビルド ステップとして実行される必要があります (これが推奨されるワークフローです)。
詳細についてはドキュメントを確認してください。
モデルを生成するための基本オブジェクトはModelGeneratorです。ジェネレーターを作成したら、それ以上の構成を行わずに、そのオブジェクトを使用してモデル クラスを生成できます。
( new ModelGenerator ())
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );generateModelsメソッドの最初のパラメーターは、 SchemaProviderInterface を実装するクラスである必要があります。プロバイダーは JSON スキーマ ファイルをフェッチし、ジェネレーターに提供します。次のプロバイダーが利用可能です。
| プロバイダー | 説明 |
|---|---|
| 再帰ディレクトリプロバイダー | 指定されたソース ディレクトリからすべての *.json ファイルを取得します。各ファイルには最上位に JSON スキーマ オブジェクト定義が含まれている必要があります |
| OpenAPIv3プロバイダー | Open API v3 仕様ファイルの#/components/schemas sectionで定義されているすべてのオブジェクトを取得します |
2 番目のパラメーターは、既存の空のディレクトリを指す必要があります ( generateModelDirectoryヘルパー メソッドを使用して宛先ディレクトリを作成できます)。このディレクトリには、ジェネレーターの終了後に生成された PHP クラスが含まれます。
オプションのパラメーターとして、 GeneratorConfigurationオブジェクトをセットアップして (利用可能なすべてのオプションについてはドキュメントを確認してください)、ジェネレーターを構成したり、メソッドgenerateModelDirectory を使用してモデル ディレクトリを生成したりできます (ディレクトリが存在しない場合はディレクトリを生成します)。存在する場合、含まれるすべてのファイルとフォルダーはクリーンな生成プロセスのために削除されます):
$ generator = new ModelGenerator (
( new GeneratorConfiguration ())
-> setNamespacePrefix ( ' MyAppModel ' )
-> setImmutable ( false )
);
$ generator
-> generateModelDirectory ( __DIR__ . ' /result ' );
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );ジェネレーターは、指定されたソース ディレクトリを再帰的にチェックし、見つかったすべての *.json ファイルをモデルに変換します。ソース ディレクトリ内のすべての JSON スキーマ ファイルは、オブジェクトのスキーマを提供する必要があります。
ディレクトリ./tests/manualには、使用法を示す簡単な例がいくつか含まれています。 composer update経由でライブラリの依存関係をインストールした後、 php ./tests/manual/test.php実行してサンプルを生成し、いくつかの JSON スキーマ ファイルを試してライブラリを探索できます。
簡単な例を見てみましょう。お名前と任意の年齢を入れたシンプルなモデルを作成します。結果として得られる JSON スキーマ:
{
"$id" : " Person " ,
"type" : " object " ,
"properties" : {
"name" : {
"type" : " string "
},
"age" : {
"type" : " integer " ,
"minimum" : 0
}
},
"required" : [
" name "
]
}この JSON スキーマを使用してクラスを生成すると、 Personという名前のクラスは次のインターフェイスを提供します。
// 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 ;次に、生成されたモデルの動作を見てみましょう。
// 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 );より複雑な例外メッセージ。 allO の構成からは次のようになります。
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
クラス生成プロセスは基本的に 3 ～ 4 つのステップに分かれています。
ライブラリは PHPUnit 経由でテストされます。
composer update経由でライブラリの依存関係をインストールした後、 ./vendor/bin/phpunit (Linux) またはvendorbinphpunit.bat (Windows) を使用してテストを実行できます。テスト名は、 --testdox出力の使用に合わせて最適化されます。ほとんどのテストは、JSON スキーマ ファイルを設定し、スキーマからクラスを生成し、その後、生成されたクラスの動作をテストするアトミック統合テストです。
テストの実行中に、JSON スキーマ ファイルと PHP クラスが書き込まれるディレクトリ PHPModelGeneratorTest が tmp に作成されます。
JSON スキーマから PHP クラスを作成するテストが失敗した場合、JSON スキーマと生成されたクラスはディレクトリ./failed-classesにダンプされます。
ライブラリのドキュメントは Sphinx で生成されます。
ドキュメントを生成するには、Sphinx をインストールし、docs ディレクトリに入り、 make html (Linux) またはmake.bat html (Windows) を実行します。生成されたドキュメントは、ディレクトリ./docs/buildで利用できます。
Read the Docs でホストされているドキュメントは、プッシュされるたびに更新されます。
