في هذا الدرس 6تصفّح المواضيع
إن إرجاع نماذج Eloquent الخام مباشرة من المتحكم يربط عقد الواجهة البرمجية العامة بهيكلة جداول قاعدة البيانات الداخلية وقد يعرض الحقول الحساسة للتسريب. توفر موارد Eloquent API طبقة تحويل وسيطة وأنيقة تفصل بين نماذج البيانات ومخرجات JSON المرسلة للعملاء.
- فصل هيكلة القاعدة (Schema Decoupling): إمكانية تعديل أسماء أعمدة الجداول داخلياً دون كسر تطبيقات الهواتف أو الواجهات الأمامية.
- التغليف القياسي للبيانات (Data Envelope Wrapping): تغليف الموارد المفردة والمجموعات تلقائياً داخل مفتاح data موحد في أعلى الاستجابة.
- القائمة البيضاء للحقول (Explicit Field Whitelisting): لا يظهر في مخرجات JSON سوى الخصائص المصرح بها صراحة داخل دالة toArray.
// Without Resource (leaks internal schema):
// return Post::findOrFail($id);
// With Eloquent API Resource:
use App\Http\Resources\PostResource;
return new PostResource(Post::findOrFail($id));يمكنك توليد كلاس تحويل جديد باستخدام الأمر php artisan make:resource الذي ينشئ الملف داخل مجلد app/Http/Resources. داخل دالة toArray الخاصة بالمورد، يمرر المتغير $this الوصول للخصائص والدوال مباشرة إلى كائن نموذج Eloquent الأساسي.
- مولد Artisan (Artisan Generator): نفذ الأمر php artisan make:resource PostResource لبناء كلاس تحويل لنموذج مفرد.
- الوسيط الشفاف للنموذج (Transparent Model Proxy): استدع خصائص النموذج مثل $this->id و $this->title مباشرة داخل دالة toArray.
- تنسيق الطوابع الزمنية (Formatted Timestamps): حوّل تواريخ Carbon إلى صيغة ISO-8601 القياسية قبل إرسالها لعملاء JSON.
namespace App\Http\Resources;
use Illuminate\Http\Resources\Json\JsonResource;
class PostResource extends JsonResource {
public function toArray($request): array {
return ['id' => $this->id];
}
}لتحويل مجموعة من النماذج أو نتائج استعلام مرقم، مرر البيانات إلى الدالة الثابتة PostResource::collection. عند تمرير كائن ترقيم ناتج عن دالة paginate، يحتفظ Laravel تلقائياً بكائني links و meta الوصفية ويلحقهما بجانب مصفوفة data.
- دالة المجموعة الثابتة (Static Collection Method): تحوّل PostResource::collection كل عنصر في المجموعة وفق نفس قواعد المورد المفرد.
- البيانات الوصفية للترقيم (Pagination Metadata): تمرير نتائج paginate يضيف تلقائياً رقم الصفحة الحالية والإجمالي وروابط التنقل.
- كلاسات المجموعات المخصصة (Dedicated Collection Classes): استخدم الخيار --collection لتوليد كلاس ResourceCollection عند الحاجة لإضافة بيانات وصفية عامة.
// In PostController@index:
public function index()
{
$posts = Post::with('author')->paginate(10);
return PostResource::collection($posts);
}أحياناً نحتاج إلى إظهار حقل معين في استجابة JSON فقط إذا كان المستخدم مديراً أو عند تحقق شرط منطقي محدد. تساعد دالة $this->when على استبعاد المفتاح نهائياً من الاستجابة عندما تكون نتيجة الشرط غير متحققة.
- التضمين الشرطي (Conditional Inclusion): تدرج دالة $this->when الحقل وقيمته فقط عندما يتحقق الشرط المنطقي الأول.
- التقييم الكسول بالإغلاق (Lazy Value Closures): مرر دالة مغلقة كوسيط ثانٍ في $this->when لكي لا تُحسب القيمة إلا عند تحقق الشرط.
- دمج عدة حقول (Merging Multiple Fields): استخدم دالة $this->mergeWhen لإدراج مصفوفة كاملة من الحقول الإدارية عند تحقق الشرط.
public function toArray(Request $request): array
{
$isAdmin = $request->user()?->isAdmin();
return [
'id' => $this->id,
'secret' => $this->when($isAdmin, 'xyz'),
];
}إن استدعاء علاقة Eloquent مباشرة داخل كلاس المورد قد يؤدي لتشغيل استعلامات تحميل كسول غير مقصودة لكل سجل في المجموعة. يضمن استخدام دالة $this->whenLoaded عدم تضمين العلاقة الفرعية إلا إذا تم تحميلها مسبقاً عبر دالة with.
- منع استعلامات N+1 (Preventing N+1 Queries): يتجنب تشغيل استعلامات إضافية أثناء تحويل JSON إذا لم يقم المتحكم بالتحميل المسبق.
- تركيب الموارد المتداخلة (Composable Resource Trees): ادمج الموارد الفرعية مع دالة whenLoaded لبناء شجرة بيانات متداخلة ونظيفة.
- بيانات الجدول الوسيط (Conditional Pivot Data): استخدم دالة $this->whenPivotLoaded لإظهار حقول الجدول الوسيط بأمان في علاقات متعدد لمتعدد.
public function toArray(Request $request): array
{
$rel = $this->whenLoaded('comments');
return [
'id' => $this->id,
'comments' => CommentResource::collection($rel),
];
}يمنحك الجمع بين كلاسات JsonResource ودوال الخصائص الشرطية ومجموعات الترقيم عقد استجابة متيناً وقابلاً للصيانة في Laravel 12. يمكنك أيضاً إلحاق بيانات وصفية إضافية في أعلى الاستجابة مثل رقم إصدار الواجهة عبر دالة additional أو دالة with.
| وجه المقارنة الهندسي | الأسلوب المتزامن أو التقليدي | معيار Laravel 12 الحديث |
|---|---|---|
| تحويل بيانات النموذج | إرجاع كائنات Eloquent الخام مباشرة من دوال المتحكم | استخدام كلاسات JsonResource لفصل قاعدة البيانات عن مخرجات JSON |
| الحقول الحساسة والشرطية | حذف الحقول يدوياً من المصفوفة داخل كل دالة في المتحكم | استخدام $this->when و $this->mergeWhen التصريحية داخل دالة toArray |
| العلاقات الفرعية المتداخلة | استدعاء العلاقة مباشرة مما يسبب مشكلة استعلامات N+1 الخفية | حماية العلاقة بدالة $this->whenLoaded مع التحميل المسبق في المتحكم |
| القوائم المرقمة | بناء مصفوفات يدوية تفقد روابط الترقيم القياسية | استخدام PostResource::collection للحفاظ على مفاتيح data و links و meta |
return PostResource::collection(Post::paginate(15))
->additional([
'meta' => ['api_version' => '1.0'],
]);ملخص الدرس
حصاد الدرسمراجعة مركّزة لأهم المفاهيم والقواعد الهندسية التي أتقنتها في هذا الدرس قبل التطبيق العملي
ماذا تعلّمت في هذا الدرس؟
أتقنت في هذا الدرس حول «تنسيق استجابات الواجهات البرمجية عبر Eloquent API Resources» مفاهيم أهمية طبقة تحويل موارد API، وإنشاء كلاسات JsonResource للنماذج، وتنسيق مجموعات الموارد والترقيم وفق معايير Laravel 12 الحديثة.
الخطوة التالية والدرس القادم
انتقل الآن إلى الدرس التالي «مصادقة الرموز وحماية واجهات API عبر Laravel Sanctum» للبناء التراكمي على ما تعلمته.
سجّل الدخول لحفظ تقدمك
تابع إنجاز المواضيع والمصطلحات والمهام، وكمّل من آخر خطوة على أي جهاز.
المصطلحات4
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 API Resources موارد API
- تحويل نماذج البيانات إلى استجابات JSON معيارية عبر Eloquent API Resources وتضمين العلاقات المشروطة بـ whenLoaded.
- للمراجعة
- 02 Why API Resources Matter أهمية طبقة تحويل موارد API
- المفهوم الهندسي والتطبيق العملي المباشر لقسم أهمية طبقة تحويل موارد API في إطار العمل Laravel 12.
- للمراجعة
- 03 Creating JsonResource Classes إنشاء كلاسات JsonResource للنماذج
- المفهوم الهندسي والتطبيق العملي المباشر لقسم إنشاء كلاسات JsonResource للنماذج في إطار العمل Laravel 12.
- للمراجعة
- 04 Formatting Resource Collections تنسيق مجموعات الموارد والترقيم
- المفهوم الهندسي والتطبيق العملي المباشر لقسم تنسيق مجموعات الموارد والترقيم في إطار العمل 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 المحلي وتحقق من النتيجة.
-
بدّل بين الحالات الثلاث في المحاكي التفاعلي ضمن قسم «إنشاء كلاسات JsonResource للنماذج» وقارن مخرجات التنفيذ.
تأشير المهمة إقرار منك بإتمامها، وليس تصحيحًا آليًا للكود. يُحفظ تقدمك في حسابك.
اختبر فهمك.
ووصلها للإتقان.
كل سؤال خطوة لقدّام. اختار، اكتب كود، وشوف نتيجتك فورًا.
أكمل المهام، واجمع كل الإجابات الصحيحة. أقل من 100%؟ راجع وأعد المحاولة.
الأسئلة متاحة للاطلاع. سجّل الدخول للتفاعل وحفظ تقدمك.
لمحة عن التحدي8 أسئلة تنتظرك ＋
ما الهدف الهندسي الأساسي من أهمية طبقة تحويل موارد API في إطار العمل Laravel 12؟
يسهم أهمية طبقة تحويل موارد API في تنظيم منطق التطبيق بأسلوب معياري آمن وقابل للصيانة في Laravel 12.
يساعد الالتزام باصطلاحات Laravel 12 الرسمية في قسم «إنشاء كلاسات JsonResource للنماذج» على رفع جودة الكود وسهولة اختباره آلياً.
صواب؛ الالتزام بالمعايير القياسية في Laravel 12 يجعل الكود واضحاً وسهل الفحص والصيانة.
أي آلية في Laravel 12 تتولى إدارة تنسيق مجموعات الموارد والترقيم بشكل مباشر ومنظم؟
توفر طبقة إطار العمل وحاوية الخدمات في Laravel 12 الأدوات القياسية لإدارة تنسيق مجموعات الموارد والترقيم.
لماذا يُعد تطبيق الخصائص الشرطية داخل موارد API مهماً عند بناء تطبيقات Laravel 12 جاهزة للإنتاج؟
لأنه يمنع الأخطاء البرمجية الخفية ويوحد سلوك التطبيق بين بيئتي التطوير والإنتاج.
في Laravel 12، يُنصح بكتابة مفاتيح الإنتاج السرية مباشرة داخل ملفات الكود المصدري المرفوعة إلى Git بدلاً من ملفات البيئة.
خطأ؛ يجب حفظ المفاتيح والبيانات السرية في متغيرات البيئة وعدم رفعها أبداً إلى مستودع Git.
ما المزايا الهندسية التي يحققها تطبيق تضمين العلاقات بدالة whenLoaded في Laravel 12؟ (اختر كل ما ينطبق)
يوفر فصلاً واضحاً للمسؤوليات، وأماناً أعلى أثناء التنفيذ، وتعاوناً أسهل بين أفراد الفريق.
يوظف إطار العمل Laravel 12 ميزات PHP 8 الحديثة مثل تحديد أنواع القيم المرجعة لجعل الكود أكثر وضوحاً وأماناً.
صواب؛ يعتمد Laravel 12 بشكل كامل على الصياغة الحديثة للغة PHP 8.2+ وسلامة الأنواع.
ما الفرق الجوهري بين معيار Laravel 12 الحديث والملفات اليدوية التقليدية في ملخص دوال موارد Eloquent API؟
يوفر Laravel 12 واجهات قياسية موحدة وحماية مدمجة تغني عن الكود اليدوي المعرض للأخطاء.