انتقل إلى محتوى الدرس
ابدأ رحلتك
الدرس 11
دورة إطار العمل Laravel

المتحكمات أحادية الإجراء القابلة للاستدعاء في LaravelLaravel Single Action Invokable Controllers

بناء متحكمات مخصصة لإجراء واحد باستخدام الدالة السحرية __invoke لتنظيم العمليات المعقدة وفق أحدث معايير إطار العمل Laravel 12 مع أمثلة وتطبيقات عملية متدرجة.
ابدأ التعلّم استكشف الأمثلة
أقسام الدرس
6
الأمثلة
6
اللغة
العربية
تاريخ النشر
غير محدد
المشاهدات
0
محتوى الدرس
في هذا الدرس 6تصفّح المواضيع

Concept of Single Action Classes مفهوم المتحكمات أحادية الإجراء

لاندرج جميع العمليات في تطبيقات الويب ضمن الإجراءات التقليدية، مثل توليد تقرير مالي معقد أو معالجة إشعار دفع خارجي أو تصدير ملف مضغوط. تخصص المتحكمات أحادية الإجراء كلاساً كاملاً لعملية واحدة مركزة، مما يحقق مبدأ المسؤولية الواحدة في هندسة البرمجيات.

  • مسؤولية واحدة مركزة (Focused Responsibility): يختص الكلاس بمعالجة عملية واحدة دون تضخيم المتحكمات الأخرى.
  • تسمية تعبر عن المهمة (Task-Based Naming): يُسمى الكلاس باسم الفعل والمهمة مثل GenerateInvoicePdfController.
  • عزل الاعتماديات (Isolated Dependencies): الخدمات المحقونة في الباني تخص هذا الإجراء وحده دون غيره.
مخطط معماري يوضح المتحكمات أحادية الإجراء القابلة للاستدعاء في Laravel في إطار العمل Laravel 12
PHP 
<?php
namespace App\Http\Controllers;

class PublishCatalogController extends Controller {
    public function __invoke(): array {
        return ['status' => 'Catalog Published'];
    }
}

Understanding PHP invoke Method آلية عمل الدالة السحرية __invoke

تعتمد المتحكمات أحادية الإجراء على الدالة السحرية المدمجة في لغة PHP وهي __invoke، والتي تعمل تلقائياً عند استدعاء الكائن البرمجي كأنه دالة. وعندما يجد موجه Laravel كلاس متحكم مسجلاً في المسار بدون اسم دالة، فإنه يوجه الطلب مباشرة نحو دالة __invoke.

  • الدالة السحرية (PHP Magic Method): تُعرف بالاسم القياسي public function __invoke داخل الكلاس.
  • كائن قابل للاستدعاء (Callable Object): تجعل الكائن قابلاً للتنفيذ المباشر تماماً مثل الدوال.
  • دعم الدوال المساعدة (Helper Methods Allowed): يمكنك إضافة دوال مساعدة خاصة private لتقسيم الخطوات الداخلية.
PHP 
<?php
namespace App\Http\Controllers;
class CalculateTaxController extends Controller {
    public function __invoke(): array {
        return ['rate' => $this->rate()];
    }
    private function rate(): float { return 0.15; }
}

Creating Invokable via Artisan CLI إنشاء متحكم أحادي بالخيار invokable

يمكنك توليد كلاس متحكم أحادي الإجراء جاهز بسطر واحد عبر تمرير الخيار --invokable أو اختصاره السريع -i مع الأمر php artisan make:controller. ينشئ Artisan ملف الكلاس داخل مجلد المتحكمات متضمناً هيكل دالة __invoke تلقائياً.

  • الخيار الصريح (--invokable Flag): يولد كلاس متحكم يحتوي على دالة __invoke الجاهزة فقط.
  • الاختصار السريع (-i Shorthand): حرف مختصر يؤدي نفس الغرض بسرعة في الطرفية.
  • دعم المجلدات الفرعية (Subfolder Support): يدعم إنشاء الكلاس داخل مجلدات منظمة حسب الميزة.
PHP 
# Generate an invokable controller via full flag
php artisan make:controller SyncController --invokable

# Generate using the short -i flag
php artisan make:controller ExportOrdersController -i

Registering Invokable Class Routes تسجيل مسار المتحكم الأحادي مباشرة

يمتاز تسجيل مسار المتحكم الأحادي في ملف routes/web.php ببساطته الشديدة، إذ لا يحتاج إلى مصفوفة ثنائية تضم اسم الدالة. يكفي تمرير اسم الكلاس مع الثابت ::class مباشرة كمعامل ثانٍ لدالة المسار.

  • الإشارة المباشرة للكلاس (Direct Class Reference): تمرير اسم الكلاس متبوعاً بـ ::class مباشرة دون أقواس مصفوفة.
  • جميع طرق الطلب (Any HTTP Verb): يعمل مع كافة دوال التوجيه مثل get وpost وput وdelete.
  • دعم السلاسل البرمجية (Full Chain Support): يقبل إلحاق دوال التسمية name والقيود where كأي مسار قياسي.
PHP 
<?php
use App\Http\Controllers\ExportCsvController;
use App\Http\Controllers\SyncOrderController;
use Illuminate\Support\Facades\Route;

Route::post('/orders/sync', SyncOrderController::class)
    ->name('orders.sync');
Route::get('/export', ExportCsvController::class);

Passing Parameters to invoke تمرير معاملات الرابط لدالة __invoke

تُمرر معاملات الرابط الديناميكية الإلزامية والاختيارية مباشرة إلى معاملات دالة __invoke بنفس الطريقة المتبعة في دوال المتحكمات القياسية. كما يمكنك دمج حقن الخدمات مع معاملات الرابط داخل توقيع دالة __invoke بكل سلاسة.

  • استقبال معاملات الرابط (Route Segment Injection): تمرير قيم الأقواس المعقوفة مباشرة إلى معاملات __invoke.
  • القيم الافتراضية (Optional Defaults): دعم المعاملات الاختيارية في الرابط بإسناد قيمة افتراضية للمتغير.
  • سهولة الاختبار (Clean Testing): سهولة اختبار الكلاس بشكل مستقل نظراً لتخصصه في عملية واحدة.
PHP 
<?php
namespace App\Http\Controllers;

class ExportPdfController extends Controller {
    public function __invoke(int $id, string $f = 'A') {
        return ['invoice' => $id, 'format' => $f];
    }
}

Standard vs Invokable Controllers مقارنة المتحكم القياسي والأحادي

تجمع فرق التطوير الحديثة بين المتحكمات القياسية للعمليات الأساسية والمتحكمات أحادية الإجراء للعمليات التخصصية المستقلة. قارن بين النمطين في الجدول المرجعي التالي لاختيار البنية الأنسب لكل ميزة في مشروعك.

وجه المقارنة الهندسيالأسلوب اليدوي أو التقليديمعيار Laravel 12 الحديث
العمليات غير القياسيةتكديس عشرات الدوال الفرعية للتقارير والتصدير داخل متحكم واحدفصل كل عملية خاصة في متحكم أحادي الإجراء مستقل ومنظم
تسجيل المسارالاضطرار لكتابة مصفوفة باسم الكلاس واسم الدالة في كل مرةتمرير اسم الكلاس مباشرة مثل ExportOrdersController::class
حقن الاعتمادياتحقن خدمات كثيرة في الباني رغم استخدامها في دالة واحدة فقطقصر الخدمات المحقونة على ما يحتاجه هذا الإجراء الوحيد فقط
توليد الكلاسإنشاء الملف يدوياً وكتابة هيكل الدالة السحرية من الصفرتوليد فوري عبر الأمر php artisan make:controller -i
PHP 
<?php
use App\Http\Controllers\ExportPdfController;
use Illuminate\Support\Facades\Route;

Route::get('/pdf/{id}/{f?}', ExportPdfController::class)
    ->whereNumber('id')
    ->name('invoices.download');
خلاصة المعرفة ومحطة الانتقال

ملخص الدرس

حصاد الدرس

مراجعة مركّزة لأهم المفاهيم والقواعد الهندسية التي أتقنتها في هذا الدرس قبل التطبيق العملي

ماذا تعلّمت في هذا الدرس؟

أتقنت في هذا الدرس حول «المتحكمات أحادية الإجراء القابلة للاستدعاء في Laravel» مفاهيم مفهوم المتحكمات أحادية الإجراء، وآلية عمل الدالة السحرية __invoke، وإنشاء متحكم أحادي بالخيار invokable وفق معايير Laravel 12 الحديثة.

الخطوة التالية والدرس القادم

انتقل الآن إلى الدرس التالي «متحكمات الموارد القياسية وحقن الاعتماديات في Laravel» للبناء التراكمي على ما تعلمته.

المهام التدريبية اختبر فهمك الآن الدرس التالي: متحكمات الموارد القياسية وحقن الاعتماديات في Laravel

مشاركة

هل كان هذا الدرس مفيدًا؟

جارٍ تحميل الآراء…

ابنِ لغتك البرمجية

المصطلحات4

راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.

0 / 4 مفهومةأول بطاقة، أول خطوة
01 Invokable Actions أحادية الإجراء
بناء متحكمات مخصصة لإجراء واحد باستخدام الدالة السحرية __invoke لتنظيم العمليات المعقدة وفق أحدث معايير إطار العمل Laravel 12 مع أمثلة وتطبيقات عملية متدرجة.
للمراجعة
02 Concept of Single Action Classes مفهوم المتحكمات أحادية الإجراء
المفهوم الهندسي والتطبيق العملي المباشر لقسم مفهوم المتحكمات أحادية الإجراء في إطار العمل Laravel 12.
للمراجعة
03 Understanding PHP invoke Method آلية عمل الدالة السحرية __invoke
المفهوم الهندسي والتطبيق العملي المباشر لقسم آلية عمل الدالة السحرية __invoke في إطار العمل Laravel 12.
للمراجعة
04 Creating Invokable via Artisan CLI إنشاء متحكم أحادي بالخيار invokable
المفهوم الهندسي والتطبيق العملي المباشر لقسم إنشاء متحكم أحادي بالخيار invokable في إطار العمل Laravel 12.
للمراجعة

اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.

حروف قليلة. معنى كامل.

الاختصارات4

راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.

0 / 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.
للمراجعة

اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.

من الفهم للتطبيق

مهامك قبل الاختبار

خطوة صغيرة كل مرة. وإنجاز تقدر ترجع له.

0/2مهام منجزة

  1. اكتب ونفّذ المثال البرمجي المشروح في قسم «مفهوم المتحكمات أحادية الإجراء» داخل مشروع Laravel 12 المحلي وتحقق من النتيجة.

    مطلوبةتم الإنجاز ✓جارٍ الحفظ…
    الموضوع أو التطبيق المرتبط

  2. بدّل بين الحالات الثلاث في المحاكي التفاعلي ضمن قسم «آلية عمل الدالة السحرية __invoke» وقارن مخرجات التنفيذ.

    مطلوبةتم الإنجاز ✓جارٍ الحفظ…
    الموضوع أو التطبيق المرتبط

تأشير المهمة إقرار منك بإتمامها، وليس تصحيحًا آليًا للكود. يُحفظ تقدمك في حسابك.

مساحة التحدي

اختبر فهمك.
ووصلها للإتقان.

كل سؤال خطوة لقدّام. اختار، اكتب كود، وشوف نتيجتك فورًا.

8أسئلة 3أنواع تحديات 100%هدف الإتقان
تصحيح تلقائي. فرص بلا حدود.

أكمل المهام، واجمع كل الإجابات الصحيحة. أقل من 100%؟ راجع وأعد المحاولة.

الأسئلة متاحة للاطلاع. سجّل الدخول للتفاعل وحفظ تقدمك.

لمحة عن التحدي8 أسئلة تنتظرك
01

ما الهدف الهندسي الأساسي من مفهوم المتحكمات أحادية الإجراء في إطار العمل Laravel 12؟

يسهم مفهوم المتحكمات أحادية الإجراء في تنظيم منطق التطبيق بأسلوب معياري آمن وقابل للصيانة في Laravel 12.

02

يساعد الالتزام باصطلاحات Laravel 12 الرسمية في قسم «آلية عمل الدالة السحرية __invoke» على رفع جودة الكود وسهولة اختباره آلياً.

صواب؛ الالتزام بالمعايير القياسية في Laravel 12 يجعل الكود واضحاً وسهل الفحص والصيانة.

03

أي آلية في Laravel 12 تتولى إدارة إنشاء متحكم أحادي بالخيار invokable بشكل مباشر ومنظم؟

توفر طبقة إطار العمل وحاوية الخدمات في Laravel 12 الأدوات القياسية لإدارة إنشاء متحكم أحادي بالخيار invokable.

04

لماذا يُعد تطبيق تسجيل مسار المتحكم الأحادي مباشرة مهماً عند بناء تطبيقات Laravel 12 جاهزة للإنتاج؟

لأنه يمنع الأخطاء البرمجية الخفية ويوحد سلوك التطبيق بين بيئتي التطوير والإنتاج.

05

في Laravel 12، يُنصح بكتابة مفاتيح الإنتاج السرية مباشرة داخل ملفات الكود المصدري المرفوعة إلى Git بدلاً من ملفات البيئة.

خطأ؛ يجب حفظ المفاتيح والبيانات السرية في متغيرات البيئة وعدم رفعها أبداً إلى مستودع Git.

06

ما المزايا الهندسية التي يحققها تطبيق تمرير معاملات الرابط لدالة __invoke في Laravel 12؟ (اختر كل ما ينطبق)

يوفر فصلاً واضحاً للمسؤوليات، وأماناً أعلى أثناء التنفيذ، وتعاوناً أسهل بين أفراد الفريق.

07

يوظف إطار العمل Laravel 12 ميزات PHP 8 الحديثة مثل تحديد أنواع القيم المرجعة لجعل الكود أكثر وضوحاً وأماناً.

صواب؛ يعتمد Laravel 12 بشكل كامل على الصياغة الحديثة للغة PHP 8.2+ وسلامة الأنواع.

08

ما الفرق الجوهري بين معيار Laravel 12 الحديث والملفات اليدوية التقليدية في مقارنة المتحكم القياسي والأحادي؟

يوفر Laravel 12 واجهات قياسية موحدة وحماية مدمجة تغني عن الكود اليدوي المعرض للأخطاء.