php json schema model generator
verging property metadata
Menghasilkan kelas model PHP dari file JSON-Schema termasuk validasi dan menyediakan penyelesaian otomatis yang lancar untuk kelas yang dihasilkan.
Contoh sederhana dari aplikasi PHP: Anda mendefinisikan dan mendokumentasikan API dengan anotasi angkuh dan model JSON-Schema. Sekarang Anda ingin menggunakan model dalam tindakan pengontrol Anda alih-alih mengakses data permintaan secara manual (mis. array). Selain itu, skema Anda sudah menentukan aturan validasi untuk model. Mengapa menduplikasi aturan ini ke dalam kode yang ditulis secara manual? Sebagai gantinya, Anda dapat menyiapkan middleware yang membuat instance model yang dihasilkan dengan pustaka ini dan memberi makan model dengan data permintaan. Sekarang Anda memiliki model tervalidasi yang dapat Anda gunakan dalam tindakan pengontrol Anda. Dengan penyelesaian otomatis penuh saat bekerja dengan objek bersarang. Hore!
Cara yang disarankan untuk menginstal php-json-schema-model-generator adalah melalui Composer:
$ composer require --dev wol-soft/php-json-schema-model-generator
$ composer require wol-soft/php-json-schema-model-generator-production
Untuk menghindari penambahan semua dependensi php-json-schema-model-generator ke dependensi produksi Anda, disarankan untuk menambahkan pustaka sebagai dependensi-dev dan menyertakan pustaka wol-soft/php-json-schema-model-generator-production . Perpustakaan produksi menyediakan semua kelas untuk menjalankan kode yang dihasilkan. Pembuatan kelas harus berupa langkah yang dilakukan di lingkungan pengembangan atau sebagai langkah pembangunan aplikasi Anda (yang merupakan alur kerja yang disarankan).
Lihat dokumen untuk lebih jelasnya.
Objek dasar untuk menghasilkan model adalah ModelGenerator . Setelah Anda membuat Generator, Anda dapat menggunakan objek tersebut untuk menghasilkan kelas model Anda tanpa konfigurasi lebih lanjut:
( new ModelGenerator ())
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );Parameter pertama metode generateModels harus berupa kelas yang mengimplementasikan SchemaProviderInterface . Penyedia mengambil file skema JSON dan menyediakannya untuk generator. Penyedia berikut tersedia:
| Penyedia | Keterangan |
|---|---|
| Penyedia Direktori Rekursif | Mengambil semua file *.json dari direktori sumber tertentu. Setiap file harus berisi definisi objek Skema JSON di tingkat atas |
| Penyedia OpenAPIv3 | Mengambil semua objek yang ditentukan di #/components/schemas section pada file spesifikasi Open API v3 |
Parameter kedua harus mengarah ke direktori yang ada dan kosong (Anda dapat menggunakan metode pembantu generateModelDirectory untuk membuat direktori tujuan). Direktori ini akan berisi kelas PHP yang dihasilkan setelah generator selesai dibuat.
Sebagai parameter opsional, Anda dapat menyiapkan objek GeneratorConfiguration (lihat dokumen untuk semua opsi yang tersedia) untuk mengonfigurasi Generator Anda dan/atau menggunakan metode generateModelDirectory untuk menghasilkan direktori model Anda (akan menghasilkan direktori jika tidak ada; jika jika ada, semua file dan folder yang ada di dalamnya akan dihapus untuk proses pembuatan yang bersih):
$ generator = new ModelGenerator (
( new GeneratorConfiguration ())
-> setNamespacePrefix ( ' MyAppModel ' )
-> setImmutable ( false )
);
$ generator
-> generateModelDirectory ( __DIR__ . ' /result ' );
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );Generator akan memeriksa direktori sumber tertentu secara rekursif dan mengonversi semua file *.json yang ditemukan menjadi model. Semua file JSON-Schema di dalam direktori sumber harus menyediakan skema objek.
Direktori ./tests/manual berisi beberapa contoh mudah yang menunjukkan penggunaannya. Setelah menginstal dependensi perpustakaan melalui composer update Anda dapat menjalankan php ./tests/manual/test.php untuk menghasilkan contoh dan bermain-main dengan beberapa file JSON-Schema untuk menjelajahi perpustakaan.
Mari kita lihat contoh mudahnya. Kami membuat model sederhana untuk seseorang dengan nama dan usia opsional. Skema JSON yang kami hasilkan:
{
"$id" : " Person " ,
"type" : " object " ,
"properties" : {
"name" : {
"type" : " string "
},
"age" : {
"type" : " integer " ,
"minimum" : 0
}
},
"required" : [
" name "
]
} Setelah membuat kelas dengan Skema JSON ini, kelas kita dengan nama Person akan menyediakan antarmuka berikut:
// 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 ;Sekarang mari kita lihat perilaku model yang dihasilkan:
// 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 );Pesan pengecualian yang lebih kompleks misalnya. dari komposisi allOf mungkin terlihat seperti:
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
Proses pembuatan kelas pada dasarnya dibagi menjadi tiga hingga empat langkah:
Perpustakaan diuji melalui PHPUnit.
Setelah menginstal dependensi perpustakaan melalui composer update Anda dapat menjalankan pengujian dengan ./vendor/bin/phpunit (Linux) atau vendorbinphpunit.bat (Windows). Nama pengujian dioptimalkan untuk penggunaan keluaran --testdox . Sebagian besar pengujian adalah pengujian integrasi atom yang akan menyiapkan file Skema JSON dan menghasilkan kelas dari skema dan menguji perilaku kelas yang dihasilkan setelahnya.
Selama eksekusi, pengujian akan membuat direktori PHPModelGeneratorTest di tmp tempat file JSON-Schema dan kelas PHP akan ditulis.
Jika pengujian yang membuat kelas PHP dari Skema JSON gagal, Skema JSON dan kelas yang dihasilkan akan dibuang ke direktori ./failed-classes
Dokumen untuk perpustakaan dibuat dengan Sphinx.
Untuk menghasilkan dokumentasi instalasi Sphinx, masuk ke direktori docs dan jalankan make html (Linux) atau make.bat html (Windows). Dokumentasi yang dihasilkan akan tersedia di direktori ./docs/build .
Dokumentasi yang dihosting di Read the Docs diperbarui setiap kali push.
