flight php swagger تنزيل - flight php swagger تنزيل كود المصدر

flight php swagger

بايثون

v0.6.2

تنزيل

حزمة الطيران/التباهي

إطار عمل صغير للطيران مزود بـ Swagger وPHPUnit وغيرها من الأدوات المساعدة المفيدة. تم تصميمه للمساعدة في بدء تطوير واجهات برمجة التطبيقات المبنية باستخدام الأدوات المذكورة أعلاه من خلال تضمين إعداد المشروع الأساسي ومسارات الاختبار والنماذج، بالإضافة إلى قالب اختبارات الوحدة.

ابدء

المتطلبات الأساسية

يفترض هذا الدليل أنك تستخدم حاليًا (أو تخطط لاستخدام) التقنيات التالية في مشروعك:

PHP 7.1+
الملحن
Xdebug (مطلوب إذا كنت تخطط لاستخدام PHPUnit)

التثبيت

أولاً، تأكد من أنك قمت بتثبيت وتكوين خادم ويب قيد التشغيل (مثل Apache) باستخدام PHP 7.1 أو أعلى.
استخدم composer لتنزيل الهيكل العظمي للمشروع، وتثبيت كافة التبعيات المطلوبة، وإجراء اختبارات وحدة العينة:
composer create-project tribeos/flight-php-swagger path/to/project

تمكين إعادة كتابة عنوان URL

نظرًا لأن الطيران يعتمد على وحدة mod_rewrite الخاصة بـ Apache 2 لكي يعمل، فيجب عليك أولاً تمكينه عبر a2enmod ثم إعادة تشغيل الخادم:

sudo a2enmod rewrite

sudo systemctl restart apache2

بعد ذلك، يجب عليك أيضًا تحرير ملف التكوين الافتراضي لـ Apache، لأنه يحظر في البداية استخدام ملف .htaccess لتطبيق قواعد إعادة الكتابة. عادةً ما يوجد ملف التكوين في /etc/apache2/apache2.conf . فيه، حدد موقع الكتلة التي تشير إلى الدليل /var/www وتأكد من تعيين AllowOverride على All وأنك Require all granted .

 <الدليل /var/www/>فهارس الخيارات FollowSymLinksAllowOverride AllRequire تم منح كل شيء
</الدليل>

بعد حفظ التغييرات، أعد تشغيل خادم Apache.

في حال كان لديك، أو تريد، تكوينات متعددة للموقع، يمكنك أيضًا تمكين إعادة كتابة القواعد على أساس كل موقع، عن طريق تحرير ملف التكوين المطلوب في /etc/apache2/sites-available . يمكنك الرجوع إلى البرنامج التعليمي التالي لمزيد من المعلومات.

ملاحظة : تفترض التعليمات المذكورة أعلاه أنك تستخدم توزيعة Ubuntu. في حالة استخدام نظام تشغيل مختلف، يرجى الرجوع إلى البرنامج التعليمي المناسب حول تمكين وحدة إعادة الكتابة.

ويندوز (وامب/XAMPP)
سينت أو إس

قم بتثبيت ملحقات PHP المفقودة

يتطلب المشروع وتبعياته تثبيت ملحقات PHP معينة. يمكن أن تكون الإضافات الشائعة التي قد تكون مفقودة بعضًا مما يلي:

مشكلة	حل
`mbstring`	`sudo apt install php-mbstring`
القضايا ذات الصلة `zip` `unzip`	`sudo apt install zip unzip php-zip`

ملاحظة : كما هو الحال مع قسم Apache 2 السابق، تتعلق هذه التعليمات بتوزيعات Ubuntu. ارجع إلى أمر بديل مناسب في حالة استخدام نظام تشغيل مختلف.

هيكل المشروع

بمجرد الانتهاء من التثبيت، ستجد هذا الهيكل في مشروعك:

path/to/project
├── app 
│   ├── models
│   │   └── SampleModel.php
│   ├── routes
│   │   ├── FlightSetup.php
│   │   └── SampleRoute.php
│   └── utils
│       └── Validator.php
├── config
│   ├── config.php
│   └── config.sample.php
├── docs
├── logs
│   └──  .htaccess
├── tests
│   ├── build
│   └── unit
│       └── SampleTest.php
├── vendor
├── .gitignore
├── .htaccess
├── autoload.php
├── composer.json
├── composer.lock
├── index.php
├── LICENSE
├── phpunit.xml
└── README.md

ملخص لمكونات المشروع الرئيسية:

app : مجلد التطبيق الرئيسي

models : النماذج المستخدمة للطلبات/الاستجابات
routes : تعريف مسارات API
utils : أدوات مساعدة للتطبيق، مثل أدوات التحقق من الصحة وأجهزة تسجيل البيانات

config : ملف (ملفات) التكوين
docs : ملفات وثائق Swagger
logs : تخزين السجلات
tests : مجلد اختبارات التطبيق

build : أي ملفات مجمعة تنتج عنها اختبارات النموذج (تغطية التعليمات البرمجية، وما إلى ذلك)
src : اختبار الملفات المصدرية

vendor : موقع جميع المكتبات ورمز الطرف الثالث
autoload.php : ملف تمهيدي يقوم بتحميل تبعيات Composer، ويتضمن جميع ملفات المشروع الأخرى
index.php : نقطة دخول واجهة برمجة التطبيقات (API).
phpunit.xml : تكوين اختبار PHPUnit

العمل في المشروع

تكوين المشروع

تتم معالجة كافة التكوينات الرئيسية المتعلقة بالمشروع (ووثائق Swagger) داخل ملف config/config.php . قم بتغيير/إضافة ثوابت التكوين وفقًا لاحتياجات مشروعك.

هناك ملف مهم آخر وهو ملف index.php ، والذي يعمل كنقطة دخول لواجهة برمجة التطبيقات (API). فهو يتطلب الملف autoload.php ، الذي يحتوي على التعليمات البرمجية لتحميل تبعيات Composer، بالإضافة إلى جميع ملفات المشروع الضرورية الأخرى. علاوة على ذلك، فإنه يبدأ إطار عمل الطيران. الملفات التي يتم استيرادها افتراضيًا هي جميع models routes والأدوات utils ، بالإضافة إلى ملف تكوين المشروع ( config/config.php ) وملف تكوين Swagger-PHP ( docs/swagger.php ) vendor/autoload.php . تغيير/إضافة الملفات المراد استيرادها وفقًا لاحتياجات مشروعك.

رحلة جوية

Flight عبارة عن إطار PHP قابل للتوسيع وسهل الاستخدام يسمح بإنشاء واجهات برمجة تطبيقات الويب RESTful بسرعة. فهو يمكّنك من إنشاء نقاط نهاية مفصلة ووظيفية لواجهة برمجة التطبيقات (API)، إلى جانب وظائف البرامج الوسيطة والقدرة على تجاوز/إنشاء أساليب مخصصة.

 رحلة::route('GET /sample/@value', function($value) {
    Flight::json([ 'sample_value' => $value ]);
});

تتم جميع عمليات التوجيه في المشروع عبر الطيران. يتم التعامل مع إعداد الرحلة الأولي ( FlightSetup.php )، بالإضافة إلى جميع مسارات المشروع داخل مجلد routes ، ويمكن تغييرها لتناسب احتياجاتك.

تتوفر وثائق الاستخدام الشاملة والأمثلة حول الطيران على صفحة الطيران الرئيسية - منطقة "التعلم". لمزيد من التفاصيل حول إطار عمل Flight نفسه، يمكنك زيارة مستودع GitHub الخاص به.

اختيال-PHP

بعد إنشاء مسار في مجلد routes ، يمكنك البدء في كتابة وإنشاء وثائق OpenAPI لواجهة RESTful API الخاصة بك.

تتم كتابة التوثيق داخل DocBlocks ، المعروف أيضًا باسم كتل تعليق PHP، أعلى المسار المقابل.

 /** * @OAGet( * path = "/sample/route"، * العلامات = {"sample"}، * ملخص = "نموذج المسار."، * @OAResponse ( * الاستجابة = 200، * الوصف = "A" نموذج استجابة." * ), *security={ * {"api_key": {}} * } * )*/

يمكنك تحديد المسار والعلامات والملخص القصير والمعلمات وقيم المعلمات الافتراضية ونص الطلب والاستجابات المتاحة ومصادقة الأمان والعديد من الخيارات الأخرى لكل نقطة نهاية RESTful.

يمكن العثور على تكوينات Swagger العامة، مثل اسم المشروع، ومؤلف (مؤلفي) المشروع، وعنوان URL لخادم API، ومجلدات المواصفات، وما إلى ذلك وتكوينها في config/config.php ، ضمن منطقة "ثوابت تكوين Swager" .

يأتي الهيكل العظمي للمشروع مقترنًا بمجلد docs ، الذي يحتوي على جميع الملفات الضرورية لتوثيق Swagger (ملفات إعداد PHP وHTML وCSS). يتم الوصول إلى الوثائق عن طريق الانتقال إلى المسار الجذر ( / ) لمشروعك عبر المتصفح.

لمزيد من المعلومات حول Swagger بشكل عام، ومعيار OpenAPI، قم بالرجوع إلى الصفحة الرئيسية الرسمية لـ Swagger. تتوفر وثائق الاستخدام الشاملة والأمثلة المتعلقة بتنفيذ PHP على الصفحة الرئيسية الرسمية لـ swagger-php.

مرافق المشروع

المسجل

يأتي المشروع مرفقًا مع http-logger، وهو عبارة عن مسجل طلب HTTP واستجابة وأخطاء، والذي سيقوم (افتراضيًا) بتسجيل كل طلب وارد والاستجابة المقابلة له في logs/debug.log ، كقيم مفصولة بعلامات جدولة (TSV). يمكن العثور على معلومات المسجل التفصيلية وتفاصيل التكوين على صفحة GitHub الخاصة به.

يتطلب المسجل موقع ملف السجل (الذي يتم تكوينه افتراضيًا عبر ثابت في config/config.php ). علاوة على ذلك، من أجل الاستفادة الكاملة من إمكانيات المسجل، يجب تعطيل معالج الأخطاء الداخلي في Flight (في حالة تمكينه، فإنه سيكتشف أنواعًا معينة من الأخطاء قبل http-logger).

 /* تعطيل مُسجل الأخطاء الداخلي الخاص بـ FlightPHP. */Flight::set('flight.handle_errors', false);
HttpLogger::create('file', 'full+h', LOG_FILE, false);/* الحصول على المسجل واستخدامه */$logger = HttpLogger::get();$logger->log();

يتم تضمين المُسجل عبر routes/FlightSetup.php ، ويتم تكوينه داخل وظيفة برنامج الطيران الوسيط Flight::after() ، والتي تعمل بعد كل طلب (حتى تتمكن من جلب الاستجابة المناسبة). يمكنك تغيير وظائف المسجل، بالإضافة إلى المسارات التي سيشاهدها، عند الكشف عنها.

`Flight::output()`

Flight::output() هي طريقة مخصصة تم تعيينها تجمع بين وظائف Flight::json() (مخرجات استجابة JSON) ومسجل HTTP المخصص. سيتم تسجيل أي استجابة لواجهة برمجة التطبيقات (API) يتم إرسالها عبر هذه الطريقة تلقائيًا، وفقًا للتفضيلات المحددة في المسجل. يتم تعريف الطريقة وتكوينها في routes/FlightSetup.php .

يكون ذلك مفيدًا عندما تريد وظيفة التسجيل لأزواج الطلب/الاستجابة الخاصة بك دون استخدام برنامج الرحلة الوسيط للاعتراض.

يأخذ Flight::output() معلمتين: البيانات الفعلية التي سيتم إرسالها ( مطلوبة )، ورمز الاستجابة ( اختياري ، 200 افتراضيًا).

 Flight::output(['sample_message' => 'نموذج الاستجابة.'], 301);

`Flight::validate()`

يستخدم Flight::validate() تحليلات Swagger-PHP لتحديد ما إذا كان نص الطلب الذي تم تمريره صالحًا (يحتوي على جميع السمات المطلوبة) وفقًا لمواصفات نموذج OpenAPI المتوقعة.

يتم الإعلان عن جميع النماذج كفئات، ويتم تعيين سماتها للعامة. يتم تعريف النماذج في app/models ، وتتبع البنية التالية:

 /** * @OASchema( * ) */class SampleModel {/** * @OAProperty( * description="نموذج سمة نص الطلب.", * example="Sample string." * مطلوب=true * ) * @ سلسلة فار */public $sample_attribute;
}

في هذا المثال الملموس، يُستخدم description لإعطاء نظرة عامة موجزة عن خاصية النموذج، ويحدد required ما إذا كانت الخاصية إلزامية أم لا، ويعينها example قيمة افتراضية. لمزيد من المعلومات حول مخططات النماذج، راجع وثائق Swagger-PHP.

تم الإعلان عن فئة التحقق من صحة النموذج وتعريفها في utils/Validator.php ، وتم تضمينها كطريقة طيران مخصصة في routes/FlightSetup.php . يستغرق الأمر معلمتين: الفئة التي سيتم التحقق من صحة نص الطلب على أساسها، ونص الطلب نفسه.

 Flight::validate(SampleModel::class, Flight::request()->data->getData());

يجب استدعاء الأسلوب داخل مسار واجهة برمجة التطبيقات (API)، قبل استدعاء أي طرق إضافية. إذا كان النموذج صالحًا، فسيستمر الطلب في التنفيذ. في حالة فشل النموذج في التحقق من صحته، فسوف يقوم بإخراج رمز استجابة 400 Bad Request ، مما يؤدي إلى إنهاء الطلب.

ملاحظة : تعتمد Flight::validate() على Flight::output() ، لذلك إذا كنت تخطط لإزالة طريقة الإخراج المخصصة من المشروع، فيجب عليك إعادة كتابة طريقة التحقق من الصحة المعينة كما هو مطلوب.

اختبار المشروع

يأتي المشروع متضمنًا مع PHPUnit، وهو إطار اختبار لـ PHP والذي، بالإضافة إلى اختبار نفسه، يسمح أيضًا بإنشاء تغطية التعليمات البرمجية.

إعداد الاختبار

كل الإعدادات المتعلقة بالاختبار باستخدام PHPUnit موجودة في phpunit.xml . هناك العديد من الخيارات المتاحة للإعداد:

موقع ملفات الاختبار داخل علامة testsuites ، يمكن تحديد الموقع الذي سيتم فحصه للاختبارات. بشكل افتراضي، هذا هو tests/unit . عند تحديد دليل اختبار (عبر علامة directory )، سيتم تشغيل ملفات الاختبار بالترتيب الأبجدي أثناء تنفيذ الاختبار. إذا لزم الأمر، يمكننا أيضًا تحديد ملفات الاختبار بترتيب مخصص عبر علامة file .

    <testsuites>
        <testsuite name="sample-test-suite">
            <directory suffix="Test.php">tests/src/</directory><!-- افتراضيًا، سيتم تشغيل ملفات الاختبار بترتيب الملفات الأبجدي. إذا كنت تريد تعيين ترتيب معين للتنفيذ، فحدد ملفات الاختبار الفردية--><!-- <file>tests/src/SampleTest.php</file> --></testsuite>
    </testsuites>

أنواع تقارير تغطية الاختبار يمكن إنشاء أنواع مختلفة من تقارير الاختبار بعد إجراء الاختبارات. يتم تعريف أنواع السجل في علامة logging . توجد جميع ملفات الاختبار المترجمة افتراضيًا داخل tests/build .

    <logging><!-- أنواع سجلات الاختبار --><log type="testdox-html" target="tests/build/testdox.html"/>
        <نوع السجل = "tap" target = "tests/build/report.tap"/>
        <نوع السجل = "junit" target = "tests/build/report.junit.xml"/>
        <log type="coverage-html" target="tests/build/coverage"/>
        <log type="coverage-text" target="tests/build/coverage.txt"/>
        <log type="coverage-clover" target="tests/build/logs/clover.xml"/>
    </تسجيل>

الملفات التي سيتم تضمينها/استبعادها من تغطية التعليمات البرمجية يمكنك أيضًا اختيار الملفات التي سيتم تضمينها في (أو استبعادها) من تقرير تغطية التعليمات البرمجية. ويتم ذلك من خلال علامة filter ، داخل علامة whitelist . افتراضيًا، يغطي إعداد PHPUnit الخاص بالمشروع الملفات الموجودة في دليل app ، باستثناء models routes (حيث لا تحتوي هذه المجلدات على تعليمات برمجية يمكن اختبارها بشكل فعال لتغطية التعليمات البرمجية). يمكنك أيضًا تحديد مجلدات وملفات التضمين/الاستبعاد المخصصة.

    <فلتر>
        <whitelist><!-- اسم المجلد الذي سيتم استخدامه لتغطية التعليمات البرمجية --><directory suffix=".php">app/</directory>
            <exclude><!-- الملفات/المجلدات المستبعدة من تغطية التعليمات البرمجية (ملفات PHP بدون طرق قابلة للاختبار). تحرير وفقا لاحتياجات المشروع الخاص بك. --><directory suffix=".php">التطبيق/النماذج</directory>
                <directory suffix=".php">التطبيق/المسارات</directory>
            </استبعاد>
        </القائمة البيضاء>
    </فلتر>

كتابة الاختبارات

يجب أن تكون جميع اختبارات الوحدات مكتوبة افتراضيًا داخل دليل tests/unit . يجب أن تنتهي أسماء ملفات الاختبار بـ Test.php ، بحيث يمكن اكتشافها بواسطة PHPUnit (كما هو محدد في phpunit.xml )، على سبيل المثال SampleTest.php .

يتم تعريف فئة الاختبار على أنها توسيع لفئة TestCase ، ويمكن أن تتضمن طرق اختبار مختلفة. عند تسمية الاختبارات، يمكنك استخدام الاصطلاح التالي: test + وصف الاختبار في حالة الجمل (على سبيل المثال، testThisIsASampleTest ). سيسمح هذا بتحويل اسم حالة الاختبار إلى جملة وصفية أثناء تنفيذ الاختبار، مما يوفر نظرة عامة إضافية للمطور حول ما يجب أن يفعله الاختبار.

 /* الاختبارات/unit/SampleTest.php */<?phpuse PHPUnitFrameworkTestCase;class SampleTest Extends TestCase {public function testThisIsASampleTest() {$this->assertTrue(true);
    }
}

تنفيذ الاختبار

لتنفيذ جميع الاختبارات، قم بتشغيل vendor/bin/phpunit --testdox داخل الدليل الجذر للمشروع.

 root@ubuntu:/path/to/project$ sales/bin/phpunit --testdox
PHPUnit 7.5.16 بقلم سيباستيان بيرجمان والمساهمين.

عينة
  هذا اختبار عينة

لتشغيل ملف اختبار واحد فقط، أدخل المسار الخاص به: vendor/bin/phpunit --testdox tests/unit/SampleTest.php

العلامة --testdox اختيارية، ولكن يوصى بها، لأنها ستولد جملًا وصفية حول الاختبارات بناءً على أسمائها (كما تمت مناقشته في القسم أعلاه)، مما يسهل فهم ما يحدث داخل الاختبارات.

بعد تنفيذ الاختبارات، يتم إنشاء تقرير تغطية الكود داخل دليل tests/build/coverage ، ويمكن الاطلاع عليه من خلال فتح هذا المسار عبر المتصفح.