كيفية إنشاء أوامر مخصصة في Laravel 11 باستخدام PHP Artisan

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

سنوضح في هذا المقال كيفية إنشاء أمر Artisan جديد باستخدام الأمر make:command الذي يؤدي لإنشاء صنف جديد في المجلد app/Console/Commands والمستخدَم لإعداد عمليات التهجير Migrations وقوائم الوِجهات Route وإنشاء الأرتال Queueing والأصناف والمهام الأخرى.

نظرة عامة على PHP Artisan

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

هناك عدة أوامر مدمجة مع Artisan، ويمكننا عرض قائمة بهذه الأوامر من خلال كتابة أمر php artisan list في الطرفية Terminal، إذ يوفر هذا الأمر قائمةً بجميع الأوامر المتاحة.

تساعد هذه الأوامر المطورين على العمل بكفاءة أكبر، فباستخدام أوامر Laravel Artisan المختلفة سنتمكن من إنشاء وظائف الاستيثاق Auth والمتحكم Controller والنموذج والبريد والتهجير والعديد من الوظائف الأخرى بسرعة وبوقت أقل.

تشغيل تطبيق لارافيل باستخدام خادم PHP Artisan

يتيح الأمر serve إمكانية تشغيل التطبيقات على خادم تطوير PHP بسهولة، ويمكن للمطورين استخدام Laravel Artisan لإنشاء واختبار ميزات التطبيق المختلفة، إذ يمكن بدء تشغيل الخادم المحلي على العنوان http://localhost:8000 بكتابة الأمر php artisan serve، مما يسهل اختبار وتطوير التطبيقات بسرعة؛ كما يمكن تخصيص الخادم لاستخدام مضيف ومنفذ مختلف.

يتكامل أمر php artisan serve مع نظام تطوير لارافيل Laravel Ecosystem الذي يتضمن ميزات عديدة مثل تهجير قواعد البيانات Migration، وجدولة المهام، وإدارة الأرتال Queues.

إنشاء أوامر مخصصة وتشغيلها

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

الخطوة 1: إنشاء أمر جديد

يمكننا إنشاء أمر جديد باسم customcommand عبر استخدام الأمر make:command الذي سينشئ صنف أوامر جديد تلقائيًا في المجلد app/Console/Commands، وسيتولّد هذا المجلد إن لم يكن موجودًا مسبقًا.

لنكتب الآن الأمر التالي في طرفية Artisan:

php artisan make:command customcommand

قد يبدو ملف الشيفرة البرمجية CustomCommand.php الخاص بهذا الأمر كما يلي:

namespace App\Console\Commands;

use Illuminate\Console\Command;

class CustomCommand extends Command

{

protected $signature = 'custom:command';

protected $description = 'Description of the custom command';

public function __construct()

{

parent::__construct();

}

public function handle()

{

// نضع المنطق البرمجي للأمر هنا

}

}

الخطوة 2: تعريف الأمر

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

لنلقِ نظرةً على الأمر التالي:

protected $signature = 'user:update {id} {--name=} {--email=}';

يتوقّع هذا الأمر لأن يدخل المستخدم وسيطًا للمعرّف ID وخيارات الاسم والبريد الإلكتروني الاختيارية.

الخطوة 3: دخل وخرج الأمر

يوفّر لارافيل طرقًا سهلةً للحصول على قيم الوسطاء والخيارات عند تشغيل الأمر، لذا من المهم استخدام التابعين ‎$this->argument()‎ و ‎$this->option()‎ ضمن التابع handle الخاص بالأمر. وإن لم يكن الوسيط أو الخيار الذي نبحث عنه موجودًا، فسيعيد هذان التابعان القيمة null.

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

$name = $this->ask('What is your name?', 'Taylor');

والأمر الآتي لطلب التأكيد:

if ($this->confirm('Do you wish to continue?')) {

// متابعة

}

يمكن جعل موجّه التأكيد يعيد القيمة true دائمًا من خلال تمرير القيمة true كوسيط ثانٍ للتابع confirm.

الخطوة 4: تسجيل الأوامر

يسجّل لارافيل جميع الأوامر الموجودة في المجلد app/Console/Commands افتراضيًا، ويمكننا إعداده للبحث في مزيد من المجلدات عن أوامر PHP Artisan، وذلك من خلال استخدام التابع withCommands في ملف bootstrap/app.php الخاص بتطبيقنا.

->withCommands([

__DIR__.'/../app/Domain/Orders/Commands',

])

سيجد حاوي الخدمات جميع الأوامر ويسجلها في تطبيقنا باستخدام Artisan.

الخطوة 5: تنفيذ الطلبات

قد نرغب في تشغيل أمر Artisan خارج واجهة سطر الأوامر من وجهة Route أو متحكم Controller مثلًا، حيث يمكن ذلك باستخدام التابع call مع الصنف Facade من Artisan؛ ويحتوي هذا التابع على وسيطين هما:

1. اسم الأمر أو صنفه
2. قائمة بمعاملات الأمر

ويعيد هذا التابع رمز الخروج.

يمكن أيضًا تمرير أمر Artisan بالكامل إلى التابع call كسلسلة نصية كما يلي:

Artisan::call('mail:send 1 --queue=default');

يمكن استخدام التابع queue مع الصنف Facade من Artisan لإرسال أوامر Artisan إلى عمّال الرتل، ثم نعالَج هذه الأوامر في الخلفية، ونتأكّد من ضبط الرتل وتشغيل مستمع الرتل قبل استخدام هذا التابع.

use Illuminate\Support\Facades\Artisan;

Route::post('/user/{user}/mail', function (string $user) {

Artisan::queue('mail:send', [

'user' => $user, '--queue' => 'default'

]);

// ...

});

الخطوة 6: معالجة الإشارات

يمكن لأوامر Artisan من لارافيل معالجة إشارات النظام مثل إشارات SIGINT، حيث يمكن دمج معالجة الإشارات مع الأمر الخاص بنا باستخدام التابع trap كما يلي:

$this->trap(SIGINT, function () {

$this->info('Command interrupted');

});

الخطوة 7: تخصيص الملفات الجذرية Stub

يمكن تخصيص ملفات القوالب التي يستخدمها أمر make:command من Artisan لتسهيل إنشاء الأوامر ذات البنى المتناسقة، لذا نحتاج إلى نشر الملفات الجذرية في مشروعنا كما يلي:

php artisan stub:publish

الخطوة 8: الأحداث

هناك ثلاثة أحداث يرسلها Artisan عند تشغيل الأوامر وهي:

1. Illuminate\Console\Events\ArtisanStarting
2. Illuminate\Console\Events\CommandStarting
3. Illuminate\Console\Events\CommandFinished

استخدم التابع event لإطلاق حدث كما يلي:

event(new CustomCommandExecuted($this));

إنشاء عمليات التهجير Migrations باستخدام الأمر make:migration

يُعَد الأمر php artisan make:migration من أوامر Artisan في لارافيل، ويُستخدَم لإنشاء ملف تهجير جديد. عمليات التهجير هي مخططات أولية لمخطط قاعدة البيانات الخاصة بنا، وتحدّد بنية الجداول والأعمدة والفهارس والعلاقات.

في ما يلي خطوات هذه العملية:

1. إنشاء عملية تهجير: يؤدي تشغيل الأمر make:migration إلى إنشاء ملف PHP جديد في المجلد database/migrations
2. تحديد التغييرات: يحتوي ملف التهجير على التابعين up و down، حيث يحدّد التابع up التغييرات التي تطرأ على قاعدة البيانات، مثل إنشاء الجداول أو إضافة الأعمدة، ويلغي التابع down هذه التغييرات
3. تشغيل عملية التهجير: استخدام الأمر php artisan migrate لتطبيق التغييرات على قاعدة البيانات

يؤدي الأمر التالي مثلًآ إلى إنشاء ملف جديد بالاسم create_users_table في المجلد database/migrations، ويمكن بعد ذلك تحديد بنية جدول users ضمن ملف التهجير.

Bash

php artisan make:migration create_users_table

فوائد الأمر make:migration

تتمثل فوائد الأمر make:migration فيما يلي:

• التحكم في الإصدارات: من خلال تعقّب تغييرات قاعدة البيانات بمرور الوقت
• التعاون: مشاركة بنية قاعدة البيانات مع أعضاء الفريق بسهولة
• بذر أو توليد البيانات Seeding لقاعدة البيانات: ملء قاعدة البيانات بالبيانات التجريبية باستخدام مولّد البيانات Seeder
• التراجع عن تغييرات قاعدة البيانات: يمكن عكس تغييرات قاعدة البيانات بسهولة إن لزم الأمر

تساعد عمليات التهجير على إبقاء مخطط قاعدة البيانات واضحًا ومنظمًا، مما يسهّل عملية إدارة التطبيق وتحديثه.

قائمة أوامر Laravel Artisan

تُعَد واجهة سطر أوامر Artisan في لارافيل أداةً مفيدةً للعمل مع التطبيقات، فهي تحتوي على أوامر لمهام مختلفة مثل إنشاء الشيفرة البرمجية وإدارة بيئة التطبيق.

تكون قائمة أوامر Laravel PHP Artisan الكاملة شاملة، حيث يمكننا استخدام أمر PHP Artisan list لجلبها، ولكن سنفصّل فيما يلي الأوامر الأساسية ضمن فئات في Laravel 11.

تتمثل الأوامر الأساسية في الآتي:

• cache: إدارة ذاكرة التطبيق المخبئية مثل المسح والنسيان وإلخ
• config: تخزين ملفات الضبط Configuration مؤقتًا أو مسحها أو نشرها
• down: تعطيل التطبيق مؤقتًا
• env: إدارة متغيرات البيئة
• key: توليد مفتاح تطبيق جديد
• migrate: تشغيل عمليات تهجير قاعدة البيانات
• optimize: تحسين التطبيق للإنتاج
• queue: إدارة نظام الرتل
• route: سرد الوِجهات Routes أو مسحها
• storage: إدارة مجلد التخزين
• vendor: إدارة اعتماديات مدير الحزم Composer

أما أوامر توليد الشيفرة البرمجية، فتتمثل في ما يلي:

• make: توليد بنى الشيفرة البرمجية المختلفة للمتحكم والنموذج والتهجير وإلخ
• model: إنشاء نماذج Eloquent
• migration: إنشاء ملفات التهجير
• seed: توليد بيانات وهمية لقاعدة البيانات

في حين أن أوامر الاختبار تكون كالآتي:

• test: تشغيل اختبارات التطبيق
• dusk: تشغيل اختبارات المتصفح باستخدام Dusk

إلى جانب وجود بعض الأوامر الإضافية التي يمكن اعتمادها، وتتمثل في:

• auth: إدارة العمليات المتعلقة بالاستيثاق Authentication
• breeze: تثبيت نظام استيثاق Breeze
• config: إدارة ملفات الضبط
• horizon: إدارة نظام رتل Laravel Horizon
• passport: إدارة خادم OAuth2
• sanctum: إدارة واجهة برمجة التطبيقات API لاستيثاق الرموز Token
• telescope: إدارة أداة تنقيح أخطاء Telescope

الخلاصة

بهذا نكون قد وضّحنا في هذا المقال كيفية إنشاء أوامر مخصصة باستخدام أمر Artisan الذي هو أداة PHP وتتيح تطوير أوامر مختلفة بناءً على احتياجات مشروعنا.

ترجمة -وبتصرّف- للقسم How to Create Custom Commands in Laravel 11 with PHP Artisan لصاحبته Hafsa Tahir.

اقرأ أيضًا

• إنشاء أوامر مخصصة في Laravel 11 باستخدام PHP Artisan
• نصائح لتحسين أداء تطبيقات لارافيل
• أفضل الحزم البرمجية لتحسين تطبيقات لارافيل