php json schema model generator
verging property metadata
สร้างคลาสโมเดล PHP จากไฟล์ JSON-Schema รวมถึงการตรวจสอบและให้การเติมคลาสที่สร้างขึ้นโดยอัตโนมัติอย่างคล่องแคล่ว
ตัวอย่างง่ายๆ จากแอปพลิเคชัน PHP: คุณกำหนดและจัดทำเอกสาร API ด้วยคำอธิบายประกอบแบบผยองและโมเดล JSON-Schema ตอนนี้คุณต้องการใช้โมเดลในการดำเนินการกับคอนโทรลเลอร์ของคุณ แทนที่จะเข้าถึงข้อมูลคำขอด้วยตนเอง (เช่น ข้อมูลอาร์เรย์) นอกจากนี้ สคีมาของคุณยังได้กำหนดกฎการตรวจสอบความถูกต้องสำหรับโมเดลต่างๆ ไว้แล้ว เหตุใดจึงต้องทำซ้ำกฎนี้ในโค้ดที่คุณเขียนด้วยตนเอง แต่คุณสามารถตั้งค่ามิดเดิลแวร์ที่สร้างอินสแตนซ์ของโมเดลที่สร้างด้วยไลบรารีนี้ และป้อนโมเดลด้วยข้อมูลคำขอ ตอนนี้คุณมีโมเดลที่ได้รับการตรวจสอบแล้วซึ่งคุณสามารถใช้ในการทำงานของคอนโทรลเลอร์ได้ ด้วยการเติมข้อมูลอัตโนมัติเต็มรูปแบบเมื่อทำงานกับวัตถุที่ซ้อนกัน เย้!
วิธีที่แนะนำในการติดตั้ง 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 ลงในการขึ้นต่อกันของการผลิตของคุณ ขอแนะนำให้เพิ่มไลบรารีเป็นการขึ้นต่อกันของ dev และรวม wol-soft/php-json-schema-model-generator-production ไลบรารี . ไลบรารีการผลิตจัดเตรียมคลาสทั้งหมดเพื่อรันโค้ดที่สร้างขึ้น การสร้างคลาสควรเป็นขั้นตอนที่ทำในสภาพแวดล้อมการพัฒนาหรือเป็นขั้นตอนการสร้างแอปพลิเคชันของคุณ (ซึ่งเป็นเวิร์กโฟลว์ที่แนะนำ)
ตรวจสอบเอกสารสำหรับรายละเอียดเพิ่มเติม
ออบเจ็กต์พื้นฐานสำหรับการสร้างแบบจำลองคือ ModelGenerator หลังจากที่คุณสร้าง Generator แล้ว คุณสามารถใช้อ็อบเจ็กต์เพื่อสร้างคลาสโมเดลของคุณได้โดยไม่ต้องมีการกำหนดค่าเพิ่มเติม:
( new ModelGenerator ())
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );พารามิเตอร์แรกของเมธอด GenerateModels ต้องเป็นคลาสที่ใช้ SchemaProviderInterface ผู้ให้บริการดึงไฟล์สคีมา JSON และจัดเตรียมไว้สำหรับตัวสร้าง ผู้ให้บริการต่อไปนี้มีอยู่:
| ผู้ให้บริการ | คำอธิบาย |
|---|---|
| Recursive DirectoryProvider | ดึงไฟล์ *.json ทั้งหมดจากไดเร็กทอรีต้นทางที่กำหนด แต่ละไฟล์ต้องมีคำจำกัดความออบเจ็กต์ JSON Schema ที่ระดับบนสุด |
| OpenAPIv3Provider | ดึงข้อมูลออบเจ็กต์ทั้งหมดที่กำหนดไว้ใน #/components/schemas section ของไฟล์ข้อมูลจำเพาะ Open API v3 |
พารามิเตอร์ตัวที่สองต้องชี้ไปยังไดเร็กทอรีที่มีอยู่และว่างเปล่า (คุณอาจใช้เมธอดตัวช่วย 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-Schema ทั้งหมดภายในไดเรกทอรีต้นทางจะต้องมีสคีมาของออบเจ็กต์
ไดเร็กทอรี ./tests/manual manual มีตัวอย่างง่ายๆ ที่แสดงการใช้งาน หลังจากติดตั้งการขึ้นต่อกันของไลบรารีผ่าน composer update คุณสามารถดำเนินการ php ./tests/manual/test.php เพื่อสร้างตัวอย่างและลองใช้ไฟล์ JSON-Schema บางไฟล์เพื่อสำรวจไลบรารี
เรามาดูตัวอย่างง่ายๆ กัน เราสร้างแบบจำลองง่ายๆ สำหรับบุคคลที่มีชื่อและอายุที่ไม่บังคับ JSON-Schema ผลลัพธ์ของเรา:
{
"$id" : " Person " ,
"type" : " object " ,
"properties" : {
"name" : {
"type" : " string "
},
"age" : {
"type" : " integer " ,
"minimum" : 0
}
},
"required" : [
" name "
]
} หลังจากสร้างคลาสด้วย JSON-Schema นี้ คลาสของเราที่มีชื่อ 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 );ข้อความยกเว้นที่ซับซ้อนมากขึ้น เช่น จากองค์ประกอบ allOf อาจมีลักษณะดังนี้:
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
กระบวนการสร้างคลาสโดยทั่วไปแบ่งออกเป็นสามถึงสี่ขั้นตอน:
ไลบรารีได้รับการทดสอบผ่าน PHPUnit
หลังจากติดตั้งการขึ้นต่อกันของไลบรารีผ่าน composer update คุณสามารถดำเนินการทดสอบด้วย ./vendor/bin/phpunit bin/phpunit (Linux) หรือ vendorbinphpunit.bat (Windows) ชื่อการทดสอบได้รับการปรับให้เหมาะสมสำหรับการใช้งานเอาต์พุต --testdox การทดสอบส่วนใหญ่เป็นการทดสอบการรวมอะตอมมิกซึ่งจะตั้งค่าไฟล์ JSON-Schema และสร้างคลาสจากสคีมาและทดสอบพฤติกรรมของคลาสที่สร้างขึ้นในภายหลัง
ในระหว่างการดำเนินการ การทดสอบจะสร้างไดเร็กทอรี PHPModelGeneratorTest ใน tmp โดยที่ไฟล์ JSON-Schema และคลาส PHP จะถูกเขียนลงไป
หากการทดสอบที่สร้างคลาส PHP จาก JSON-Schema ล้มเหลว JSON-Schema และคลาสที่สร้างขึ้นจะถูกเทลงในไดเร็กทอรี ./failed-classes
เอกสารสำหรับห้องสมุดสร้างด้วยสฟิงซ์
หากต้องการสร้างเอกสารการติดตั้ง Sphinx ให้ป้อนไดเร็กทอรีเอกสารและดำเนินการ make html (Linux) หรือ make.bat html (Windows) เอกสารที่สร้างขึ้นจะพร้อมใช้งานในไดเร็กทอรี ./docs/build build
เอกสารที่โฮสต์ไว้ที่ Read the Docs จะได้รับการอัปเดตทุกครั้งที่กด
