php json schema model generator
verging property metadata
يُنشئ فئات نماذج PHP من ملفات JSON-Schema بما في ذلك التحقق من الصحة وتوفير إكمال تلقائي سلس للفئات التي تم إنشاؤها.
مثال بسيط من تطبيق PHP: يمكنك تعريف وتوثيق واجهة برمجة التطبيقات (API) باستخدام التعليقات التوضيحية المبهجة ونماذج مخطط JSON. أنت الآن تريد استخدام النماذج في إجراءات وحدة التحكم الخاصة بك بدلاً من الوصول يدويًا إلى بيانات الطلب (على سبيل المثال، عناصر المصفوفة). بالإضافة إلى ذلك، يحدد مخططك بالفعل قواعد التحقق من صحة النماذج. لماذا تكرر هذه القواعد في التعليمات البرمجية المكتوبة يدويًا؟ بدلاً من ذلك، يمكنك إعداد برنامج وسيط يقوم بإنشاء مثيل للنماذج التي تم إنشاؤها باستخدام هذه المكتبة وتغذية النموذج ببيانات الطلب. الآن لديك نموذج تم التحقق من صحته والذي يمكنك استخدامه في إجراء وحدة التحكم الخاصة بك. مع الإكمال التلقائي الكامل عند العمل مع الكائنات المتداخلة. ياي!
الطريقة الموصى بها لتثبيت 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 . بعد إنشاء المولد، يمكنك استخدام الكائن لإنشاء فئات النموذج الخاصة بك دون أي تكوين إضافي:
( new ModelGenerator ())
-> generateModels ( new RecursiveDirectoryProvider ( __DIR__ . ' /schema ' ), __DIR__ . ' /result ' );يجب أن تكون المعلمة الأولى لأسلوب generatorModels عبارة عن فئة تطبق SchemaProviderInterface . يقوم الموفر بإحضار ملفات مخطط JSON ويوفرها للمولد. يتوفر مقدمو الخدمة التاليون:
| مزود | وصف |
|---|---|
| RecursiveDirectoryProvider | جلب جميع ملفات *.json من الدليل المصدر المحدد. يجب أن يحتوي كل ملف على تعريف كائن مخطط JSON في المستوى الأعلى |
| OpenAPIv3Provider | جلب جميع الكائنات المحددة في #/components/schemas section في ملف المواصفات Open API v3 |
يجب أن تشير المعلمة الثانية إلى دليل موجود وفارغ (يمكنك استخدام الأسلوب المساعد generateModelDirectory لإنشاء الدليل الوجهة الخاص بك). سيحتوي هذا الدليل على فئات PHP التي تم إنشاؤها بعد انتهاء المولد.
كمعلمة اختيارية، يمكنك إعداد كائن GeneratorConfiguration (راجع المستندات لمعرفة جميع الخيارات المتاحة) لتكوين المولد الخاص بك و/أو استخدام الطريقة generatorModelDirectory لإنشاء دليل النموذج الخاص بك (سيتم إنشاء الدليل إذا لم يكن موجودًا؛ إذا إذا كان موجودًا، ستتم إزالة جميع الملفات والمجلدات المضمنة لعملية إنشاء نظيفة):
$ 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 على بعض الأمثلة السهلة التي توضح الاستخدام. بعد تثبيت تبعيات المكتبة عبر composer update يمكنك تنفيذ php ./tests/manual/test.php لإنشاء الأمثلة والتلاعب ببعض ملفات JSON-Schema لاستكشاف المكتبة.
دعونا نلقي نظرة على مثال سهل. نقوم بإنشاء نموذج بسيط لشخص له اسم وعمر اختياري. مخطط 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 );رسائل استثناء أكثر تعقيدًا على سبيل المثال. من تركيبة 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 (Linux) أو vendorbinphpunit.bat (Windows). تم تحسين أسماء الاختبار لاستخدام مخرجات --testdox . معظم الاختبارات عبارة عن اختبارات التكامل الذري والتي ستقوم بإعداد ملف JSON-Schema وإنشاء فئة من المخطط واختبار سلوك الفئة التي تم إنشاؤها بعد ذلك.
أثناء التنفيذ، ستقوم الاختبارات بإنشاء دليل PHPModelGeneratorTest في tmp حيث سيتم كتابة ملفات JSON-Schema وفئات PHP.
إذا فشل الاختبار الذي يقوم بإنشاء فئة PHP من مخطط JSON في مخطط JSON وسيتم تفريغ الفئة (الفئات) التي تم إنشاؤها إلى الدليل ./failed-classes
يتم إنشاء مستندات المكتبة باستخدام Sphinx.
لإنشاء الوثائق، قم بتثبيت Sphinx، وأدخل دليل المستندات وقم بتنفيذ make html (Linux) أو make.bat html (Windows). ستكون الوثائق التي تم إنشاؤها متاحة في الدليل ./docs/build .
يتم تحديث الوثائق المستضافة في Read the Docs في كل دفعة.
