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

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

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

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

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

هنالك عدة أوامر مدمجة مع Artisan ويمكن عرض قائمة بهذه الأوامر من خلال كتابة أمر php artisan list في طرفية Artisan كما في الصورة التالية:

تساعدنا هذه الأوامر على العمل بكفاءة أكبر، حيث سنتمكن على سبيل المثال من إنشاء وظائف الاستيثاق Authentication، والمتحكمات Controllers، والنماذج Models، وإنشاء عمليات التهجير Migrations وغيرها من الوظائف المتقدمة بسهولة وخلال وقت أقل.

أساسيات أوامر Laravel Artisan

يُعَد الصنف Illuminate\Console\Application أساسًا في Artisan فهو الذي يحدد كيفية التعامل مع الأوامر، كما أنه يوسّع الصنف Symfony\Component\Console\Application، وهذا يسهّل على مطوري إطار عمل سيمفوني Symfony التعامل مع Artisan لأنهم سيجدون بيئة عمل مألوفة.

فيما يلي مثال على تعريف أمر بسيط:

namespace App\Console\Commands;

use Illuminate\Console\Command;

class ExampleCommand extends Command

{

protected $signature = 'example:run {name}';

protected $description = 'Runs an example command';

public function handle()

{

$name = $this->argument('name');

$this->info("Hello, {$name}!");

}

}

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

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

 php artisan serve

وهذا يسهل اختبار وتطوير التطبيقات بسرعة، كما يمكننا تخصيص الخادم لاستخدام مضيف ومنفذ مختلف.

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

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

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

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

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

php artisan make:command customcommand

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

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، يحتوي هذا التابع على وسيطين الأول هو اسم الأمر أو اسم الصنف المرتبط بالأمر، والوسيط الثاني هو قائمة بمعاملات الأمر، ويعيد هذا التابع رمز الخروج ليشير إلى ما إذا كان الأمر قد نجح أم لا.

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

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

ترتيب أوامر Artisan ضمن رتل

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

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 عند تشغيل الأوامر وهي:

الحدث Illuminate\Console\Events\ArtisanStarting
الحدث Illuminate\Console\Events\CommandStarting
الحدث Illuminate\Console\Events\CommandFinished

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

event(new CustomCommandExecuted($this));

إنشاء عمليات التهجير Migrations

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

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

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

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

php artisan make:migration create_users_table

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

التحكم في الإصدارات من خلال تعقّب تغييرات قاعدة البيانات بمرور الوقت
التعاون ومشاركة بنية قاعدة البيانات مع أعضاء الفريق بسهولة
بذر أو توليد البيانات Seeding لقاعدة البيانات لملئها بالبيانات التجريبية باستخدام Seeder
التراجع عن تغييرات قاعدة البيانات بسهولة عند الحاجة
إبقاء مخطط قاعدة البيانات واضحًا ومنظمًا، مما يسهّل إدارة تطبيقنا وتحديثه

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

تحتوي واجهة سطر أوامر Artisan في لارافيل على أوامر لمهام مختلفة مثل إنشاء الشيفرة البرمجية وإدارة بيئة التطبيق ويمكن مطالعة القائمة الشاملة لكافة الأوامر بكتابة الأمر PHP Artisan list كما وضحنا سابقًا، ولكن سنفصّل فيما يلي الأوامر الأساسية الموجودة ضمن لارافيل 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 الذي يوفر إمكانية تطوير أوامر مختلفة واستدعاءها بناءً على احتياجات مشروعنا.

بعض الأسئلة الشائعة

لنتعرف على أبرز الأسئلة الشائعة حول أوامر Artisan

1. ما الغرض من أوامر PHP Artisan في لارافيل

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

2. لماذا نستخدم أمر PHP Artisan Serve

يشغّل أمر PHP Artisan serve خادم تطوير محلي لتطبيق لارافيل الخاص بنا بسرعة، ويُعَد مثاليًا لإنشاء النماذج الأولية السريعة والاختبار أثناء التطوير.

3. كيف نشغّل أوامر PHP Artisan في cpanel

نفتح الطرفية Terminal من cPanel وننتقل إلى مجلد مشروع لارافيل الخاص بنا، ثم نشغّل الأمر باستخدام PHP كما يلي:

 ‎/usr/local/bin/php artisan {command}‎

تحتاج للتأكد من وضع مسار PHP الصحيح للخادم مكان ‎/usr/local/bin/php، والذي يمكننا العثور عليه في MultiPHP Manager ضمن cPanel.

4. هل يمكن تعديل أو توسيع أوامر Artisan الموجودة مسبقًا في لارافيل

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

5. هل يمكن استخدام أوامر Artisan المخصصة لأتمتة المهام الشائعة في لارافيل

نعم، يمكننا استخدام أوامر Artisan المخصصة في لارافيل لأتمتة المهام الشائعة مثل تشغيل عمليات التهجير، وتوليد بيانات لقاعدة البيانات وتوليد الشيفرة البرمجية وتطبيق المهام المجدولة وتنفيذ أي منطق برمجي مخصص.

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