laravel api handler
v0.7.3
توفر حزمة المساعد هذه وظيفة لتحليل عنوان URL لطلب REST-API.
ملاحظة: هذا الإصدار مخصص لـ Laravel 5. عند استخدام Laravel 4، يجب عليك استخدام الإصدار 0.4.x.
قم بتثبيت الحزمة من خلال الملحن عن طريق التشغيل
composer require marcelgwerder/laravel-api-handler
بمجرد انتهاء الملحن، قم بإضافة مزود الخدمة إلى مجموعة providers في app/config/app.php :
MarcelgwerderApiHandlerApiHandlerServiceProvider::class,
الآن قم باستيراد واجهة ApiHandler إلى فصولك:
use Marcelgwerder ApiHandler Facades ApiHandler ; أو قم بتعيين اسم مستعار في app.php :
'ApiHandler' => MarcelgwerderApiHandlerFacadesApiHandler::class,
هذا كل شيء!
تحتاج أساليب العلاقات الآن إلى تعليق توضيحي @Relation لإثبات أنها طرق علاقات وليست أي طرق أخرى (راجع الإصدار رقم 11).
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} إذا قمت بتمرير مصفوفة كمعلمة ثانية إلى parseSingle ، فيجب أن يكون هناك الآن أزواج من الأعمدة/القيم. هذا يسمح لنا بتمرير شروط متعددة مثل:
ApiHandler :: parseSingle ( $ books , array ( ' id_origin ' => ' Random Bookstore Ltd ' , ' id ' => 1337 )); لتجاوز التكوين، قم بإنشاء ملف يسمى apihandler.php في مجلد التكوين الخاص بتطبيقك.
تحقق من ملف التكوين في مصدر الحزمة لمعرفة الخيارات المتاحة.
يدعم تحليل URL حاليًا:
هناك نوعان من موارد واجهة برمجة التطبيقات المدعومة، كائن واحد ومجموعة من الكائنات.
إذا كنت تتعامل مع طلب GET على مورد يمثل كائنًا واحدًا مثل /api/books/1 على سبيل المثال، فاستخدم الطريقة parseSingle .
parseSingle($queryBuilder, $identification, [$queryParams]):
id أو زوج (أزواج) عمود/قيمة المصفوفة ( array('isbn' => '1234') ) ) يستخدم كمعرف فريد للكائن. ApiHandler :: parseSingle ( $ book , 1 ); إذا كنت تتعامل مع طلب GET على مورد يمثل كائنات متعددة مثل /api/books على سبيل المثال، فاستخدم التابع parseMultiple .
parseMultiple($queryBuilder, $fullTextSearchColumns, [$queryParams]):
ApiHandler :: parseMultiple ( $ book , array ( ' title ' , ' isbn ' , ' description ' )); يقوم كل من parseSingle و parseMultiple بإرجاع كائن Result بالطرق التالية المتاحة:
getBuilder(): إرجاع $queryBuilder الأصلي مع كافة الوظائف المطبقة عليه.
getResult(): إرجاع كائن النتيجة الذي تم إرجاعه بواسطة وظائف get() أو first() الخاصة بـ Laravel.
getResultOrFail(): يُرجع الكائن الناتج الذي تُرجعه الدالة get() الخاصة بـ Laravel إذا كنت تتوقع كائنات متعددة أو firstOrFail() إذا كنت تتوقع كائنًا واحدًا.
getResponse($resultOrFail = false): يُرجع كائن Response Laravel بما في ذلك النص والرؤوس ورمز حالة HTTP. إذا كان $resultOrFail صحيحًا، فسيتم استخدام طريقة getResultOrFail() داخليًا بدلاً من getResult() .
getHeaders (): إرجاع مجموعة من الرؤوس المعدة.
getMetaProviders (): إرجاع مجموعة من كائنات موفر التعريف. يوفر كل من هذه الكائنات نوعًا معينًا من البيانات التعريفية من خلال طريقة get() الخاصة به.
cleanup($cleanup): إذا كان صحيحًا، فسيتم تنظيف المصفوفة الناتجة من العلاقات المضافة عن غير قصد. يمكن إضافة مثل هذه العلاقات تلقائيًا إذا تم الوصول إليها كخصائص في أدوات الوصول للنموذج. يمكن تحديد الإعداد الافتراضي العام لعملية التنظيف باستخدام خيار التكوين cleanup_relations الذي يكون الإعداد الافتراضي له هو false .
ApiHandler :: parseSingle ( $ books , 42 )-> cleanup ( true )-> getResponse (); يتم تفسير كل معلمة استعلام، باستثناء الوظائف المحددة مسبقًا _fields و _with و _sort و _limit و _offset و _config و _q ، كمرشح. تأكد من إزالة المعلمات الإضافية غير المخصصة للتصفية قبل تمريرها إلى parseMultiple .
/api/books?title=The Lord of the Rings
يتم دمج جميع المرشحات مع عامل التشغيل AND .
/api/books?title-lk=The Lord*&created_at-min=2014-03-14 12:55:02
المثال أعلاه سينتج عنه SQL التالي حيث:
WHERE ` title ` LIKE " The Lord% " AND ` created_at ` >= " 2014-03-14 12:55:02 " من الممكن أيضًا استخدام قيم متعددة لمرشح واحد. يتم فصل القيم المتعددة بواسطة أنبوب | . يتم دمج القيم المتعددة مع OR إلا في حالة وجود لاحقة -not ، فسيتم دمجها مع AND . على سبيل المثال جميع الكتب ذات المعرف 5 أو 6:
/api/books?id=5|6
أو جميع الكتب باستثناء الكتب ذات المعرف 5 أو 6:
/api/books?id-not=5|6
يمكن تحقيق نفس الشيء باستخدام اللاحقة -in :
/api/books?id-in=5,6
على التوالي not-in لاحقة:
/api/books?id-not-in=5,6
| لاحقة | المشغل | معنى |
|---|---|---|
| -لك | يحب | نفس مشغل SQL LIKE |
| -ليس-لك | لا أحب | نفس عامل التشغيل SQL NOT LIKE |
| -في | في | نفس عامل تشغيل SQL IN |
| -ليس في | ليس في | نفس عامل التشغيل SQL NOT IN |
| -دقيقة | >= | أكبر من أو يساوي |
| -الأعلى | <= | أصغر من أو يساوي |
| -شارع | < | أصغر من |
| -GT | > | أعظم من |
| -لا | != | لا يساوي |
طريقتان للفرز، تصاعديا وتنازليا. كل عمود يجب فرزه تنازليًا يبدأ دائمًا بـ - .
/api/books?_sort=-title,created_at
يتم دعم تطبيقين للبحث عن النص الكامل. يمكنك اختيار الخيار الذي تريد استخدامه عن طريق تغيير خيار fulltext في ملف التكوين إلى default أو native .
ملاحظة: عند استخدام معلمة _q فارغة، سيرجع البحث دائمًا نتيجة فارغة.
التنفيذ المخصص المحدود (افتراضي)
يتم تقسيم نص معين إلى كلمات رئيسية يتم البحث عنها بعد ذلك في قاعدة البيانات. عند وجود إحدى الكلمات الأساسية، يتم تضمين الصف المقابل في مجموعة النتائج.
/api/books?_q=The Lord of the Rings
يُرجع المثال أعلاه كل صف يحتوي على إحدى الكلمات الأساسية The , Lord , of , the Rings في أحد أعمدته. يتم تمرير الأعمدة التي يجب أخذها في الاعتبار عند البحث عن النص الكامل إلى parseMultiple .
تنفيذ MySQL الأصلي
إذا كان إصدار MySQL الخاص بك يدعم البحث عن النص الكامل للمحرك الذي تستخدمه، فيمكنك استخدام هذا البحث المتقدم في معالج واجهة برمجة التطبيقات.
ما عليك سوى تغيير خيار تكوين fulltext إلى native والتأكد من وجود فهرس نص كامل مناسب على الأعمدة التي تمررها إلى parseMultiple .
ستحتوي كل نتيجة أيضًا على عمود _score والذي يسمح لك بفرز النتائج وفقًا لمدى مطابقتها لمصطلحات البحث. على سبيل المثال
/api/books?_q=The Lord of the Rings&_sort=-_score
يمكنك ضبط اسم هذا العمود عن طريق تعديل إعداد fulltext_score_column في ملف التكوين.
لتحديد الحد الأقصى لعدد مجموعات البيانات في النتيجة، استخدم _limit .
/api/books?_limit=50
لتحديد إزاحة مجموعات البيانات في النتيجة، استخدم _offset .
/api/books?_offset=20&_limit=50
انتبه إلى أنه لاستخدام offset يجب عليك دائمًا تحديد limit أيضًا. يلقي MySQL خطأً في تعريف الإزاحة بلا حدود.
يدعم معالج واجهة برمجة التطبيقات أيضًا علاقات Eloquent. لذا، إذا كنت تريد الحصول على جميع الكتب مع مؤلفيها، فما عليك سوى إضافة المؤلفين إلى المعلمة _with .
/api/books?_with=author
العلاقات، يمكن أيضًا أن تكون متداخلة:
/api/books?_with=author.awards
لكي يعمل هذا، يجب عليك إضافة تعليق توضيحي @Relation إلى كل طريقة من طرق العلاقات الخاصة بك مثل:
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} يعد ذلك ضروريًا لأسباب أمنية، بحيث يمكن استدعاء أساليب العلاقة الحقيقية فقط باستخدام _with .
ملاحظة: عندما تحدد الحقول بـ _fields مع _with . تحت الغطاء، يتم تمديد الحقول بالمفاتيح الأساسية/الخارجية للعلاقة. يحتاج Eloquent إلى مفاتيح الربط للحصول على النماذج ذات الصلة.
من الممكن إضافة معلومات إضافية إلى الرد. يوجد حاليًا نوعان من الأعداد التي يمكن إضافتها إلى رؤوس الاستجابة.
total-count الذي يمثل عدد جميع عناصر المورد، أو لنكون أكثر تحديدًا، العدد الموجود في مثيل منشئ الاستعلام الذي تم تمريره في الأصل. filter-count الذي يأخذ أيضًا عوامل التصفية في الاعتبار. يمكن أن تكون مفيدة على سبيل المثال لتنفيذ ترقيم الصفحات.
/api/books?id-gt=5&_config=meta-total-count,meta-filter-count
يتم توفير جميع حقول التعريف في رأس الاستجابة بشكل افتراضي. يتم استخدام الرؤوس المخصصة التالية:
| التكوين | رأس |
|---|---|
| التعريف الإجمالي للعد | التعريف الإجمالي للعد |
| عدد مرشح التعريف | عدد مرشحات التعريف |
بشكل افتراضي، يتم تضمين بيانات التعريف في رأس الاستجابة. إذا كنت تريد جمع كل شيء معًا في نص الاستجابة، فيمكنك طلب ما يسمى "المغلف" إما عن طريق تضمين response-envelope في المعلمة _config أو عن طريق تجاوز config.php الافتراضي للحزمة.
يحتوي المغلف على البنية التالية:
{
"meta" : {
},
"data" : [
]
}
