کنسول Artisan

• معرفی
  • Tinker (REPL)
• دستورات نوشتن
  • تولید دستورات
  • ساختار فرماندهی
  • دستورات بستن
• تعریف انتظارات ورودی
  • استدلال ها
  • گزینه ها
  • آرایه های ورودی
  • توضیحات ورودی
• دستور I/O
  • بازیابی ورودی
  • درخواست برای ورودی
  • خروجی نوشتن
• ثبت دستورات
• اجرای دستورات به صورت برنامه ای
  • فراخوانی دستورات از دستورات دیگر
• سفارشی سازی خرد

معرفی

Artisan رابط خط فرمان است که با لاراول ارائه شده است. تعدادی از دستورات مفید را ارائه می دهد که می تواند در هنگام ساخت برنامه به شما کمک کند. برای مشاهده لیستی از تمام دستورات Artisan موجود، می توانید از list دستور زیر استفاده کنید:

php artisan list

هر دستور همچنین شامل یک صفحه "راهنما" است که آرگومان ها و گزینه های موجود دستور را نمایش و توصیف می کند. برای مشاهده صفحه راهنما، قبل از نام دستور زیر را قرار دهید help :

php artisan help migrate

Tinker (REPL)

Laravel Tinker یک REPL قدرتمند برای چارچوب لاراول است که توسط بسته PsySH پشتیبانی می شود .

نصب و راه اندازی

تمام برنامه های لاراول به طور پیش فرض شامل Tinker می شوند. با این حال، در صورت نیاز می توانید آن را به صورت دستی با استفاده از Composer نصب کنید:

composer require laravel/tinker

استفاده

Tinker به شما امکان می دهد با کل برنامه لاراول خود در خط فرمان تعامل داشته باشید، از جمله Eloquent ORM، مشاغل، رویدادها و موارد دیگر. برای ورود به محیط Tinker tinker دستور Artisan را اجرا کنید:

php artisan tinker

شما می توانید فایل پیکربندی Tinker را با استفاده از vendor:publish دستور زیر منتشر کنید:

php artisan vendor:publish --provider="Laravel\Tinker\TinkerServiceProvider"

تابع dispatch و dispatch متد کمکی روی Dispatchable کلاس به جمع آوری زباله برای قرار دادن کار در صف بستگی دارد. بنابراین، هنگام استفاده از tinker، باید از کارها استفاده کنید Bus::dispatch یا Queue::push برای ارسال کارها استفاده کنید.

دستور لیست سفید

Tinker از یک لیست سفید برای تعیین اینکه کدام دستورات Artisan مجاز است در پوسته خود اجرا شود استفاده می کند. به طور پیش فرض، می توانید دستورات clear-compiled ،،،،،، و را اجرا down کنید . اگر می خواهید دستورات بیشتری را در لیست سفید قرار دهید، می توانید آنها را به آرایه موجود در فایل پیکربندی خود اضافه کنید: env inspire migrate optimize up commands tinker.php

'commands' => [
    // App\Console\Commands\ExampleCommand::class,
],

کلاس هایی که نباید مستعار شوند

به طور معمول، Tinker به طور خودکار کلاس ها را همانطور که در Tinker نیاز دارید، نام مستعار می کند. با این حال، ممکن است بخواهید هرگز برخی از کلاس ها را مستعار نکنید. شما می توانید این کار را با لیست کردن کلاس ها در dont_alias آرایه فایل پیکربندی خود انجام دهید tinker.php :

'dont_alias' => [
    App\User::class,
],

دستورات نوشتن

علاوه بر دستورات ارائه شده با Artisan، می توانید دستورات سفارشی خود را نیز بسازید. دستورات معمولاً در app/Console/Commands دایرکتوری ذخیره می شوند. با این حال، شما آزاد هستید که مکان ذخیره سازی خود را انتخاب کنید تا زمانی که دستورات شما توسط Composer بارگیری شود.

تولید دستورات

برای ایجاد یک دستور جدید، از make:command دستور Artisan استفاده کنید. این دستور یک کلاس دستوری جدید در app/Console/Commands دایرکتوری ایجاد می کند. اگر این دایرکتوری در برنامه شما وجود ندارد نگران نباشید، زیرا اولین باری که make:command دستور Artisan را اجرا می کنید ایجاد می شود. دستور تولید شده شامل مجموعه پیش‌فرض ویژگی‌ها و متدهایی است که در همه دستورات وجود دارد:

php artisan make:command SendEmails

ساختار فرماندهی

signature پس از تولید دستور خود، باید خصوصیات و description کلاس را که هنگام نمایش دستور شما بر روی صفحه استفاده می شود را پر کنید list . زمانی که دستور شما اجرا شود متد handle فراخوانی می شود. شما می توانید منطق فرمان خود را در این متد قرار دهید.

برای استفاده مجدد بیشتر از کد، تمرین خوبی است که دستورات کنسول خود را سبک نگه دارید و به آنها اجازه دهید تا برای انجام وظایف خود به سرویس های برنامه موکول شوند. در مثال زیر، توجه داشته باشید که ما یک کلاس خدماتی را برای انجام "بالا بردن سنگین" ارسال ایمیل ها تزریق می کنیم.

بیایید به یک دستور مثال نگاهی بیندازیم. توجه داشته باشید که ما قادریم هر وابستگی لازم را به handle متد فرمان تزریق کنیم. کانتینر سرویس لاراول به طور خودکار تمام وابستگی هایی را که در امضای این متد به صورت تایپ مشخص شده اند تزریق می کند:

<?php
 
namespace App\Console\Commands;
 
use App\DripEmailer;
use App\User;
use Illuminate\Console\Command;
 
class SendEmails extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'email:send {user}';
 
    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Send drip e-mails to a user';
 
    /**
     * Create a new command instance.
     *
     * @return void
     */
    public function __construct()
    {
        parent::__construct();
    }
 
    /**
     * Execute the console command.
     *
     * @param  \App\DripEmailer  $drip
     * @return mixed
     */
    public function handle(DripEmailer $drip)
    {
        $drip->send(User::find($this->argument('user')));
    }
}

دستورات بستن

دستورات مبتنی بر بسته شدن، جایگزینی برای تعریف دستورات کنسول به عنوان کلاس ارائه می‌کنند. همانطور که مسیر Closures جایگزینی برای کنترلرها است، دستور Closures را به عنوان جایگزینی برای کلاس های فرمان در نظر بگیرید. در commands روش فایل شما app/Console/Kernel.php ، لاراول routes/console.php فایل را بارگذاری می کند:

/**
 * Register the Closure based commands for the application.
 *
 * @return void
 */
protected function commands()
{
    require base_path('routes/console.php');
}

اگرچه این فایل مسیرهای HTTP را تعریف نمی کند، نقاط ورودی (مسیرها) مبتنی بر کنسول را به برنامه شما تعریف می کند. در این فایل، می‌توانید تمام مسیرهای مبتنی بر بسته شدن خود را با استفاده از Artisan::command روش تعریف کنید. این command متد دو آرگومان را می پذیرد: امضای فرمان و یک Closure که آرگومان ها و گزینه های دستورات را دریافت می کند:

Artisan::command('build {project}', function ($project) {
    $this->info("Building {$project}!");
});

Closure به نمونه دستور زیرین محدود می شود، بنابراین شما به تمام روش های کمکی که معمولاً می توانید در یک کلاس دستور کامل به آنها دسترسی داشته باشید، دسترسی کامل دارید.

وابستگی های نوع اشاره

علاوه بر دریافت آرگومان‌ها و گزینه‌های فرمان شما، دستور Closures ممکن است وابستگی‌های دیگری را نیز تایپ کند که می‌خواهید خارج از کانتینر سرویس برطرف شوند :

use App\DripEmailer;
use App\User;
 
Artisan::command('email:send {user}', function (DripEmailer $drip, $user) {
    $drip->send(User::find($user));
});

توضیحات فرمان بستن

هنگام تعریف یک دستور مبتنی بر Closure، ممکن است از describe روشی برای اضافه کردن توضیحات به دستور استفاده کنید. php artisan list هنگامی که دستورات یا را اجرا می کنید، این توضیحات نمایش داده می شود php artisan help :

Artisan::command('build {project}', function ($project) {
    $this->info("Building {$project}!");
})->describe('Build the project');

تعریف انتظارات ورودی

هنگام نوشتن دستورات کنسول، جمع آوری ورودی از کاربر از طریق آرگومان ها یا گزینه ها معمول است. لاراول تعریف ورودی مورد انتظار کاربر را با استفاده signature از ویژگی دستورات شما بسیار راحت می کند. این signature ویژگی به شما امکان می‌دهد نام، آرگومان‌ها و گزینه‌های دستور را در یک نحو منفرد، رسا و مسیر مانند تعریف کنید.

استدلال ها

همه آرگومان ها و گزینه های ارائه شده توسط کاربر در پرانتزهای فرفری پیچیده شده اند. در مثال زیر، دستور یک آرگومان مورد نیاز user را تعریف می کند :

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'email:send {user}';

همچنین می توانید آرگومان ها را اختیاری کنید و مقادیر پیش فرض را برای آرگومان ها تعریف کنید:

// Optional argument...
email:send {user?}
 
// Optional argument with default value...
email:send {user=foo}

گزینه ها

گزینه‌ها، مانند آرگومان‌ها، شکل دیگری از ورودی کاربر هستند. -- هنگامی که گزینه ها در خط فرمان مشخص می شوند با دو خط فاصله ( ) پیشوند می شوند . دو نوع گزینه وجود دارد: آنهایی که یک مقدار دریافت می کنند و آنهایی که دریافت نمی کنند. گزینه هایی که مقداری دریافت نمی کنند به عنوان یک "سوئیچ" بولی عمل می کنند. بیایید نگاهی به نمونه ای از این نوع گزینه بیندازیم:

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'email:send {user} {--queue}';

در این مثال، --queue سوئیچ ممکن است هنگام فراخوانی دستور Artisan مشخص شود. اگر --queue سوئیچ پاس شود، مقدار گزینه خواهد بود true . در غیر این صورت، مقدار این خواهد بود false :

php artisan email:send 1 --queue

گزینه های با ارزش

در مرحله بعد، بیایید نگاهی به گزینه ای بیندازیم که انتظار یک مقدار را دارد. اگر کاربر باید مقداری را برای یک گزینه مشخص کند، پسوند نام گزینه را با یک = علامت اضافه کنید:

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'email:send {user} {--queue=}';

در این مثال، کاربر ممکن است مقداری مانند این را برای گزینه ارسال کند:

php artisan email:send 1 --queue=default

می توانید با تعیین مقدار پیش فرض پس از نام گزینه، مقادیر پیش فرض را به گزینه ها اختصاص دهید. اگر هیچ مقدار گزینه ای توسط کاربر ارسال نشود، از مقدار پیش فرض استفاده می شود:

email:send {user} {--queue=default}

میانبرهای گزینه

برای اختصاص میانبر هنگام تعریف یک گزینه، می توانید آن را قبل از نام گزینه مشخص کرده و از یک | استفاده کنید جداکننده برای جدا کردن میانبر از نام کامل گزینه:

email:send {user} {--Q|queue}

آرایه های ورودی

اگر می خواهید آرگومان ها یا گزینه هایی را برای انتظار ورودی آرایه تعریف کنید، می توانید از * کاراکتر استفاده کنید. ابتدا، بیایید به مثالی نگاه کنیم که آرگومان آرایه را مشخص می کند:

email:send {user*}

هنگام فراخوانی این متد، user آرگومان ها ممکن است به خط فرمان ارسال شوند. برای مثال، دستور زیر user مقدار ['foo', 'bar'] :

php artisan email:send foo bar

هنگام تعریف گزینه ای که انتظار ورودی آرایه را دارد، هر مقدار گزینه ارسال شده به فرمان باید با نام گزینه پیشوند شود:

email:send {user} {--id=*}
 
php artisan email:send --id=1 --id=2

توضیحات ورودی

می توانید با جدا کردن پارامتر از توضیحات با استفاده از دو نقطه، توضیحاتی را به آرگومان ها و گزینه های ورودی اختصاص دهید. اگر برای تعریف دستور خود به فضای کمی نیاز دارید، با خیال راحت این تعریف را در چندین خط پخش کنید:

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'email:send
                        {user : The ID of the user}
                        {--queue= : Whether the job should be queued}';

دستور I/O

بازیابی ورودی

در حالی که فرمان شما در حال اجرا است، بدیهی است که باید به مقادیر آرگومان ها و گزینه های پذیرفته شده توسط فرمان خود دسترسی داشته باشید. برای انجام این کار، می توانید از روش های argument و استفاده کنید option :

/**
 * Execute the console command.
 *
 * @return mixed
 */
public function handle()
{
    $userId = $this->argument('user');
 
    //
}

اگر می خواهید همه آرگومان ها را به صورت یک بازیابی کنید array ، متد را فراخوانی کنید arguments :

$arguments = $this->arguments();

گزینه ها ممکن است به آسانی آرگومان ها با استفاده از option روش بازیابی شوند. برای بازیابی همه گزینه ها به عنوان یک آرایه، options متد را فراخوانی کنید:

// Retrieve a specific option...
$queueName = $this->option('queue');
 
// Retrieve all options...
$options = $this->options();

اگر آرگومان یا گزینه وجود نداشته باشد، null برگردانده می شود.

درخواست برای ورودی

علاوه بر نمایش خروجی، ممکن است از کاربر بخواهید که در هنگام اجرای دستور شما ورودی ارائه دهد. این ask روش از کاربر سوال داده شده را درخواست می کند، ورودی او را می پذیرد و سپس ورودی کاربر را به دستور شما برمی گرداند:

/**
 * Execute the console command.
 *
 * @return mixed
 */
public function handle()
{
    $name = $this->ask('What is your name?');
}

روش secret مشابه است ask ، اما ورودی کاربر هنگام تایپ در کنسول برای آنها قابل مشاهده نخواهد بود. این روش هنگام درخواست اطلاعات حساس مانند رمز عبور مفید است:

$password = $this->secret('What is the password?');

درخواست تایید

اگر نیاز دارید که از کاربر یک تایید ساده بخواهید، می توانید از این confirm روش استفاده کنید. به طور پیش فرض، این روش برمی گردد false . با این حال، اگر کاربر وارد شود y یا yes در پاسخ به درخواست، متد برمی‌گردد true .

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

تکمیل خودکار

این anticipate روش می تواند برای ارائه تکمیل خودکار برای انتخاب های احتمالی استفاده شود. کاربر همچنان می تواند هر پاسخی را بدون توجه به نکات تکمیل خودکار انتخاب کند:

$name = $this->anticipate('What is your name?', ['Taylor', 'Dayle']);

از طرف دیگر، می توانید یک Closure را به عنوان آرگومان دوم به anticipate متد ارسال کنید. هر بار که کاربر یک کاراکتر ورودی را تایپ می کند، Closure فراخوانی می شود. بسته شدن باید یک پارامتر رشته ای را بپذیرد که تا کنون حاوی ورودی کاربر است و آرایه ای از گزینه ها را برای تکمیل خودکار بازگرداند:

$name = $this->anticipate('What is your name?', function ($input) {
    // Return auto-completion options...
});

سوالات چند گزینه ای

اگر نیاز دارید به کاربر مجموعه ای از انتخاب های از پیش تعریف شده بدهید، می توانید از این choice روش استفاده کنید. اگر گزینه ای انتخاب نشده باشد، می توانید شاخص آرایه مقدار پیش فرض را تنظیم کنید که برگردانده شود:

$name = $this->choice('What is your name?', ['Taylor', 'Dayle'], $defaultIndex);

علاوه بر این، این choice روش آرگومان های چهارم و پنجم اختیاری را برای تعیین حداکثر تعداد تلاش ها برای انتخاب یک پاسخ معتبر و اینکه آیا چندین انتخاب مجاز است می پذیرد:

$name = $this->choice(
    'What is your name?',
    ['Taylor', 'Dayle'],
    $defaultIndex,
    $maxAttempts = null,
    $allowMultipleSelections = false
);

خروجی نوشتن

برای ارسال خروجی به کنسول، از line متدهای info ، و comment ، question و استفاده کنید error . هر یک از این روش ها از رنگ های ANSI مناسب برای هدف خود استفاده می کنند. به عنوان مثال، اجازه دهید برخی از اطلاعات عمومی را به کاربر نمایش دهیم. به طور معمول، این info روش در کنسول به صورت متن سبز نمایش داده می شود:

/**
 * Execute the console command.
 *
 * @return mixed
 */
public function handle()
{
    $this->info('Display this on the screen');
}

برای نمایش پیغام خطا از error روش استفاده کنید. متن پیام خطا معمولاً با رنگ قرمز نمایش داده می شود:

$this->error('Something went wrong!');

اگر می خواهید خروجی کنسول ساده و بدون رنگ نمایش داده شود، از line روش زیر استفاده کنید:

$this->line('Display this on the screen');

طرح بندی جدول

این table روش قالب بندی صحیح چندین ردیف / ستون داده را آسان می کند. فقط سرصفحه ها و ردیف ها را به متد ارسال کنید. عرض و ارتفاع به صورت پویا بر اساس داده های داده شده محاسبه می شود:

$headers = ['Name', 'Email'];
 
$users = App\User::all(['name', 'email'])->toArray();
 
$this->table($headers, $users);

نوارهای پیشرفت

برای کارهای طولانی مدت، نشان دادن شاخص پیشرفت می تواند مفید باشد. با استفاده از شی خروجی، می توانیم نوار پیشرفت را شروع، پیشروی و متوقف کنیم. ابتدا تعداد کل مراحلی که فرآیند طی آن تکرار می شود را مشخص کنید. سپس، پس از پردازش هر مورد، نوار پیشرفت را پیش ببرید:

$users = App\User::all();
 
$bar = $this->output->createProgressBar(count($users));
 
$bar->start();
 
foreach ($users as $user) {
    $this->performTask($user);
 
    $bar->advance();
}
 
$bar->finish();

برای گزینه‌های پیشرفته‌تر، مستندات مؤلفه نوار پیشرفت Symfony را بررسی کنید .

ثبت دستورات

به دلیل load فراخوانی متد در متد هسته کنسول شما commands ، تمام دستورات داخل app/Console/Commands دایرکتوری به طور خودکار در Artisan ثبت می شوند. load در واقع، شما آزاد هستید تا با روشی که برای اسکن سایر دایرکتوری‌ها برای دستورات Artisan فراخوانی کنید، تماس بگیرید :

/**
 * Register the commands for the application.
 *
 * @return void
 */
protected function commands()
{
    $this->load(__DIR__.'/Commands');
    $this->load(__DIR__.'/MoreCommands');
 
    // ...
}

همچنین می توانید با افزودن نام کلاس آن به $commands ویژگی فایل خود، دستورات را به صورت دستی ثبت کنید app/Console/Kernel.php . هنگامی که Artisan بوت می شود، تمام دستورات لیست شده در این ویژگی توسط کانتینر سرویس حل می شود و در Artisan ثبت می شود:

protected $commands = [
    Commands\SendEmails::class
];

اجرای دستورات به صورت برنامه ای

گاهی اوقات ممکن است بخواهید دستور Artisan را خارج از CLI اجرا کنید. برای مثال، ممکن است بخواهید دستور Artisan را از یک مسیر یا کنترلر اجرا کنید. برای انجام این کار می توانید از call روش روی نما استفاده کنید. Artisan متد call نام یا کلاس فرمان را به عنوان آرگومان اول و آرایه ای از پارامترهای فرمان را به عنوان آرگومان دوم می پذیرد. کد خروج برگردانده می شود:

Route::get('/foo', function () {
    $exitCode = Artisan::call('email:send', [
        'user' => 1, '--queue' => 'default'
    ]);
 
    //
});

از طرف دیگر، می توانید کل دستور Artisan را call به عنوان یک رشته به متد ارسال کنید:

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

با استفاده از queue روش روی نما، حتی ممکن است دستورات Artisan را در صف قرار دهید تا در پس‌زمینه توسط کارگران صف Artisan پردازش شوند . قبل از استفاده از این روش، مطمئن شوید که صف خود را پیکربندی کرده اید و یک شنونده صف اجرا می کنید:

Route::get('/foo', function () {
    Artisan::queue('email:send', [
        'user' => 1, '--queue' => 'default'
    ]);
 
    //
});

همچنین می‌توانید اتصال یا صفی را که دستور Artisan باید به آن ارسال شود را مشخص کنید:

Artisan::queue('email:send', [
    'user' => 1, '--queue' => 'default'
])->onConnection('redis')->onQueue('commands');

عبور مقادیر آرایه

اگر دستور شما گزینه ای را تعریف می کند که یک آرایه را می پذیرد، می توانید یک آرایه از مقادیر را به آن گزینه ارسال کنید:

Route::get('/foo', function () {
    $exitCode = Artisan::call('email:send', [
        'user' => 1, '--id' => [5, 13]
    ]);
});

عبور از مقادیر بولی

اگر نیاز به تعیین مقدار گزینه ای دارید که مقادیر رشته را نمی پذیرد، مانند پرچم --force روی migrate:refresh دستور، باید true یا false :

$exitCode = Artisan::call('migrate:refresh', [
    '--force' => true,
]);

فراخوانی دستورات از دستورات دیگر

گاهی اوقات ممکن است بخواهید دستورات دیگری را از یک دستور Artisan موجود فراخوانی کنید. شما می توانید این کار را با استفاده از call روش انجام دهید. این call متد نام فرمان و آرایه ای از پارامترهای فرمان را می پذیرد:

/**
 * Execute the console command.
 *
 * @return mixed
 */
public function handle()
{
    $this->call('email:send', [
        'user' => 1, '--queue' => 'default'
    ]);
 
    //
}

اگر می‌خواهید فرمان کنسول دیگری را فراخوانی کنید و تمام خروجی آن را متوقف کنید، می‌توانید از این callSilent روش استفاده کنید. متد callSilent امضای مشابه متد دارد call :

$this->callSilent('email:send', [
    'user' => 1, '--queue' => 'default'
]);

سفارشی سازی خرد

دستورات کنسول Artisan make برای ایجاد کلاس‌های مختلف مانند کنترلرها، جاب‌ها، مهاجرت‌ها و تست‌ها استفاده می‌شود. این کلاس ها با استفاده از فایل های "خرد" که با مقادیر بر اساس ورودی شما پر شده اند، تولید می شوند. با این حال، ممکن است گاهی بخواهید تغییرات کوچکی در فایل های تولید شده توسط Artisan ایجاد کنید. برای انجام این کار، می‌توانید از stub:publish دستور انتشار رایج‌ترین خرده‌ها برای سفارشی‌سازی استفاده کنید:

php artisan stub:publish

stubs مقالات خرد منتشر شده در یک فهرست در ریشه برنامه شما قرار خواهند گرفت . make هر تغییری که در این خرده‌ها ایجاد کنید، زمانی که کلاس‌های مربوطه آن‌ها را با استفاده از دستورات Artisan ایجاد کنید، منعکس می‌شوند .