في هذا الدرس 6تصفّح المواضيع
يعتمد إطار Laravel 12 هيكلة رشيقة يتم فيها تفعيل مسارات الواجهات البرمجية عند الحاجة عبر أمر install:api في Artisan. يقوم هذا الأمر بإنشاء ملف routes/api.php وتسجيل البادئة /api تلقائياً داخل bootstrap/app.php مع تطبيق مجموعة البرمجيات الوسيطة عديمة الحالة.
- المعمارية عديمة الحالة (Stateless Architecture): لا تحتفظ مسارات API بحالة الجلسة على الخادم أو ملفات تعريف CSRF بين الطلبات.
- البادئة التلقائية (Automatic Prefixing): يُسبق كل مسار معرّف داخل ملف routes/api.php بالبادئة /api تلقائياً.
- الربط في التمهيد (Bootstrap Wiring): يربط إعداد withRouting في ملف bootstrap/app.php ملف مسارات API بأنبوب البرمجيات الوسيطة.
// Terminal: php artisan install:api
// bootstrap/app.php
return Application::configure(basePath: __DIR__)
->withRouting(
api: __DIR__.'/../routes/api.php',
)->create();عند بناء واجهات JSON البرمجية، لا نحتاج إلى دوال عرض النماذج المرئية مثل create و edit لأن تطبيق العميل يتولى رسم واجهته بنفسه. يتيح تمرير الخيار --api مع أمر make:controller توليد متحكم نظيف يضم الدوال الخمس المخصصة للبيانات فقط.
- خمس دوال للبيانات (Five Data Actions): يولّد دوال index و store و show و update و destroy المخصصة لتبادل بيانات JSON.
- استبعاد قوالب العرض (No HTML Views): يستثني دالتي create و edit ليبقى المتحكم مركزاً بالكامل على معالجة البيانات.
- تنظيم نطاق الأسماء (Namespace Organization): توضع متحكمات الواجهة البرمجية عرفياً داخل المجلد الفرعي App\Http\Controllers\Api.
// php artisan make:controller Api/PostController --api
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Models\Post;
class PostController extends Controller {}بدلاً من كتابة خمسة مسارات منفصلة لكل مورد، تقوم دالة Route::apiResource بربط جميع أفعال HTTP وعناوين URI بمتحكم الواجهة البرمجية في سطر واحد. يمكنك أيضاً تسجيل عدة موارد برمجية دفعة واحدة عبر تمرير مصفوفة ترابطية إلى دالة Route::apiResources.
- التسجيل بسطر واحد (Single-Line Registration): يربط أفعال GET و POST و PUT/PATCH و DELETE بالدوال الخمس القياسية في المتحكم.
- ربط معاملات المسار (Route Parameter Binding): يولّد تلقائياً معامل المسار بصيغة المفرد مثل {post} لدعم الربط الضمني للنموذج.
- التسجيل المجمّع (Batch Registration): تتيح دالة Route::apiResources تسجيل عدة متحكمات موارد بنظافة داخل ملف routes/api.php.
use App\Http\Controllers\Api\PostController;
use App\Http\Controllers\Api\CommentController;
use Illuminate\Support\Facades\Route;
Route::apiResource('posts', PostController::class);
Route::apiResources([
'comments' => CommentController::class,
]);تتواصل واجهات RESTful البرمجية بدقة عبر إقران البيانات المهيكلة بصيغة JSON مع رموز حالة HTTP المعبرة عن نتيجة العملية. تتيح دالة response->json إرجاع السجلات المنشأة حديثاً مع الرمز 201، أو تأكيد الحذف الفارغ عبر response->noContent بالرمز 204.
- الرمز 200 للنجاح (HTTP 200 OK): الحالة الافتراضية عند إرجاع قائمة السجلات أو بيانات المورد بعد تحديثه.
- الرمز 201 للإنشاء (HTTP 201 Created): يُرجع من دالة store فور حفظ سجل جديد بنجاح داخل قاعدة البيانات.
- الرمز 204 بدون محتوى (HTTP 204 No Content): يُرجع من دالة destroy عند حذف السجل بنجاح دون الحاجة لجسم استجابة.
public function store(Request $request)
{
$post = Post::create($request->only('title'));
return response()->json($post, 201);
}
// In destroy(Post $post):
// $post->delete();
// return response()->noContent();عندما يرسل عميل الواجهة البرمجية رأس الرسالة Accept: application/json، يحول Laravel أخطاء التحقق والاستثناءات تلقائياً إلى استجابة JSON مهيكلة بدلاً من إعادة التوجيه لصفحة ويب. تُرجع أخطاء التحقق رمز الحالة 422 مع مصفوفة تفصيلية برسائل الخطأ لكل حقل.
- التفاوض عبر رأس الرسالة (Accept Header Negotiation): إرسال الرأس Accept: application/json يوجه معالج الاستثناءات لإرجاع الأخطاء بصيغة JSON.
- استجابة التحقق 422 (HTTP 422 Validation Response): تُرجع رسالة عامة مع كائن errors مفهرس بأسماء الحقول التي فشل التحقق منها.
- خطأ عدم العثور 404 (HTTP 404 Model Not Found): يُرجع الربط الضمني للنموذج استجابة JSON بالرمز 404 تلقائياً إذا لم يوجد السجل.
public function update(Request $request, Post $post)
{
$data = $request->validate([
'title' => ['required', 'string', 'max:120'],
]);
$post->update($data);
return response()->json($post, 200);
}إن إتقان الربط بين أفعال HTTP وأنماط الروابط ودوال المتحكم ورموز الحالة يضمن توافق واجهتك البرمجية في Laravel مع المعايير الهندسية القياسية. راجع دورة حياة نقطة النهاية الكاملة للمورد البرمجي قبل الانتقال لتنسيق المخرجات عبر موارد Eloquent API.
| وجه المقارنة الهندسي | الأسلوب المتزامن أو التقليدي | معيار Laravel 12 الحديث |
|---|---|---|
| تسجيل المسارات البرمجية | تعريف 5 مسارات منفصلة يدوياً لكل مورد في الملف | تصريح موحد عبر Route::apiResource في ملف routes/api.php |
| توليد كلاس المتحكم | متحكم ويب كامل يحتوي على دالتي create و edit غير المستخدمتين | استخدام الخيار --api لتوليد الدوال الخمس الخاصة ببيانات JSON |
| رموز حالة الإنشاء والحذف | إرجاع الرمز العام 200 لجميع عمليات الإضافة والحذف | تخصيص الرمز 201 للإنشاء والرمز 204 للحذف عبر noContent |
| مخرجات فشل التحقق | إعادة توجيه 302 لصفحة HTML عند حدوث خطأ في المدخلات | إرجاع استجابة JSON تلقائية بالرمز 422 عند إرسال رأس الرسالة Accept |
// Inspect registered API routes:
// php artisan route:list --path=api
Route::prefix('v1')->group(function () {
Route::apiResource('posts', PostController::class);
});ملخص الدرس
حصاد الدرسمراجعة مركّزة لأهم المفاهيم والقواعد الهندسية التي أتقنتها في هذا الدرس قبل التطبيق العملي
ماذا تعلّمت في هذا الدرس؟
أتقنت في هذا الدرس حول «بناء مسارات RESTful API ومتحكمات JSON في Laravel» مفاهيم تفعيل مسارات API عديمة الحالة، وإنشاء متحكمات موارد API القياسية، وتسجيل مسارات apiResource الموحدة وفق معايير Laravel 12 الحديثة.
الخطوة التالية والدرس القادم
انتقل الآن إلى الدرس التالي «تنسيق استجابات الواجهات البرمجية عبر Eloquent API Resources» للبناء التراكمي على ما تعلمته.
سجّل الدخول لحفظ تقدمك
تابع إنجاز المواضيع والمصطلحات والمهام، وكمّل من آخر خطوة على أي جهاز.
المصطلحات4
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 API Controllers مسارات API
- تفعيل مسارات الواجهات البرمجية بالأمر install:api وإنشاء متحكمات API وإرجاع استجابات JSON القياسية مع رموز حالة HTTP.
- للمراجعة
- 02 Enabling Stateless API Routing تفعيل مسارات API عديمة الحالة
- المفهوم الهندسي والتطبيق العملي المباشر لقسم تفعيل مسارات API عديمة الحالة في إطار العمل Laravel 12.
- للمراجعة
- 03 Generating API Resource Controllers إنشاء متحكمات موارد API القياسية
- المفهوم الهندسي والتطبيق العملي المباشر لقسم إنشاء متحكمات موارد API القياسية في إطار العمل Laravel 12.
- للمراجعة
- 04 Registering API Resource Endpoints تسجيل مسارات apiResource الموحدة
- المفهوم الهندسي والتطبيق العملي المباشر لقسم تسجيل مسارات apiResource الموحدة في إطار العمل Laravel 12.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
الاختصارات4
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 MVC MVC
- Model View Controller
- النمط المعماري الذي يفصل بين نماذج البيانات Models، وطبقات العرض Views، والمتحكمات Controllers في Laravel.
- للمراجعة
- 02 CLI CLI
- Command Line Interface
- واجهة سطر الأوامر التي تعمل عبر أداة php artisan لتوليد الملفات وإدارة التطبيق.
- للمراجعة
- 03 HTTP HTTP
- Hypertext Transfer Protocol
- بروتوكول نقل النص الفائق الذي ينظم طلبات المتصفح واستجابات خادم Laravel.
- للمراجعة
- 04 PSR PSR
- PHP Standards Recommendations
- المعايير القياسية للغة PHP مثل التحميل التلقائي PSR-4 التي يلتزم بها إطار العمل Laravel.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
مهامك قبل الاختبار
خطوة صغيرة كل مرة. وإنجاز تقدر ترجع له.
-
اكتب ونفّذ المثال البرمجي المشروح في قسم «تفعيل مسارات API عديمة الحالة» داخل مشروع Laravel 12 المحلي وتحقق من النتيجة.
-
بدّل بين الحالات الثلاث في المحاكي التفاعلي ضمن قسم «إنشاء متحكمات موارد API القياسية» وقارن مخرجات التنفيذ.
تأشير المهمة إقرار منك بإتمامها، وليس تصحيحًا آليًا للكود. يُحفظ تقدمك في حسابك.
اختبر فهمك.
ووصلها للإتقان.
كل سؤال خطوة لقدّام. اختار، اكتب كود، وشوف نتيجتك فورًا.
أكمل المهام، واجمع كل الإجابات الصحيحة. أقل من 100%؟ راجع وأعد المحاولة.
الأسئلة متاحة للاطلاع. سجّل الدخول للتفاعل وحفظ تقدمك.
لمحة عن التحدي8 أسئلة تنتظرك ＋
ما الهدف الهندسي الأساسي من تفعيل مسارات API عديمة الحالة في إطار العمل Laravel 12؟
يسهم تفعيل مسارات API عديمة الحالة في تنظيم منطق التطبيق بأسلوب معياري آمن وقابل للصيانة في Laravel 12.
يساعد الالتزام باصطلاحات Laravel 12 الرسمية في قسم «إنشاء متحكمات موارد API القياسية» على رفع جودة الكود وسهولة اختباره آلياً.
صواب؛ الالتزام بالمعايير القياسية في Laravel 12 يجعل الكود واضحاً وسهل الفحص والصيانة.
أي آلية في Laravel 12 تتولى إدارة تسجيل مسارات apiResource الموحدة بشكل مباشر ومنظم؟
توفر طبقة إطار العمل وحاوية الخدمات في Laravel 12 الأدوات القياسية لإدارة تسجيل مسارات apiResource الموحدة.
لماذا يُعد تطبيق إرجاع استجابات JSON ورموز الحالة مهماً عند بناء تطبيقات Laravel 12 جاهزة للإنتاج؟
لأنه يمنع الأخطاء البرمجية الخفية ويوحد سلوك التطبيق بين بيئتي التطوير والإنتاج.
في Laravel 12، يُنصح بكتابة مفاتيح الإنتاج السرية مباشرة داخل ملفات الكود المصدري المرفوعة إلى Git بدلاً من ملفات البيئة.
خطأ؛ يجب حفظ المفاتيح والبيانات السرية في متغيرات البيئة وعدم رفعها أبداً إلى مستودع Git.
ما المزايا الهندسية التي يحققها تطبيق التحقق من بيانات طلبات API في Laravel 12؟ (اختر كل ما ينطبق)
يوفر فصلاً واضحاً للمسؤوليات، وأماناً أعلى أثناء التنفيذ، وتعاوناً أسهل بين أفراد الفريق.
يوظف إطار العمل Laravel 12 ميزات PHP 8 الحديثة مثل تحديد أنواع القيم المرجعة لجعل الكود أكثر وضوحاً وأماناً.
صواب؛ يعتمد Laravel 12 بشكل كامل على الصياغة الحديثة للغة PHP 8.2+ وسلامة الأنواع.
ما الفرق الجوهري بين معيار Laravel 12 الحديث والملفات اليدوية التقليدية في مرجع مسارات ومتحكمات RESTful API؟
يوفر Laravel 12 واجهات قياسية موحدة وحماية مدمجة تغني عن الكود اليدوي المعرض للأخطاء.