Artisan консоль

Published November 29, 2020 • 5 mins read

Вступ

Artisan - це інтерфейс командного рядка, що входить до складу Laravel. Він надає ряд корисних команд, які можуть допомогти вам під час створення вашої програми. Щоб переглянути список усіх доступних команд Artisan, ви можете скористатися listкомандою:

php artisan list

Кожна команда також включає екран "довідки", який відображає та описує доступні аргументи та параметри команди. Щоб переглянути екран довідки, перед назвою команди слід вказати help:

php artisan help migrate



Тинкер (REPL)

Laravel Tinker - це потужний REPL для фреймворку Laravel, який працює від пакету PsySH .



Встановлення

Усі програми Laravel за замовчуванням включають Tinker. Однак ви можете встановити його вручну, якщо потрібно, використовуючи Composer:

composer require laravel/tinker
{tip} Шукаєте графічний інтерфейс для взаємодії з вашим додатком Laravel? Перевірте Тинкервелл !



Використання

Tinker дозволяє взаємодіяти з усім вашим додатком Laravel у командному рядку, включаючи Eloquent ORM, завдання, події тощо. Щоб увійти в середовище Tinker, запустіть команду tinkerArtisan:

php artisan tinker

Ви можете опублікувати файл конфігурації Tinker за допомогою vendor:publishкоманди:

php artisan vendor:publish --provider="Laravel\Tinker\TinkerServiceProvider"
{note} dispatchДопоміжна функція та dispatchметод Dispatchableкласу залежить від збору сміття для розміщення завдання в черзі. Тому, використовуючи майстер, ви повинні використовувати Bus::dispatchабо Queue::pushвідправляти завдання.



Білий список команд

Tinker використовує білий список, щоб визначити, які команди Artisan дозволяється запускати в його оболонці. За замовчуванням, ви можете запустити clear-compileddownenvinspiremigrateoptimizeі upкоманду. Якщо ви хочете додати до білого списку більше команд, ви можете додати їх до commandsмасиву у вашому tinker.phpфайлі конфігурації:

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



Класи, які не слід прізвищати

Як правило, Tinker автоматично псевдонімить класи, коли вони потрібні в Tinker. Тим не менш, ви можете ніколи не псевдонім деяких класів. Ви можете досягти цього, перелічивши класи в dont_aliasмасиві вашого tinker.phpконфігураційного файлу:

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



Написання команд

На додаток до команд, наданих Artisan, ви також можете створити власні власні команди. Команди зазвичай зберігаються в app/Console/Commandsкаталозі; однак ви можете вибрати власне місце зберігання, доки ваші команди можуть бути завантажені Composer.



Створення команд

Щоб створити нову команду, використовуйте команду make:commandArtisan. Ця команда створить новий клас команд у app/Console/Commandsкаталозі. Не хвилюйтеся, якщо цей каталог не існує у вашій програмі, оскільки він буде створений під час першого запуску команди make:commandArtisan. Сформована команда включатиме набір властивостей та методів за замовчуванням, які присутні у всіх командах:

php artisan make:command SendEmails



Структура команд

Після генерації вашої команди ви повинні заповнити властивості signatureта descriptionвластивості класу, які будуть використовуватися при відображенні вашої команди на listекрані. handleМетод буде викликатися , коли ваша команда буде виконана. Ви можете розмістити свою логіку команд у цьому методі.

{tip} Для кращого повторного використання коду корисно зберігати команди консолі легкими та дозволяти їм переходити до служб додатків для виконання своїх завдань. У наведеному нижче прикладі зауважте, що ми вводимо сервісний клас, щоб зробити важку роботу під час надсилання електронних листів.

Давайте розглянемо приклад команди. Зверніть увагу, що ми можемо вводити будь-які необхідні нам залежності в handleметод команди . Контейнер служби Laravel автоматично вводить усі залежності, наведені в підписі цього методу:

<?php

namespace App\Console\Commands;

use App\Models\User;
use App\Support\DripEmailer;
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\Support\DripEmailer  $drip
     * @return mixed
     */
    public function handle(DripEmailer $drip)
    {
        $drip->send(User::find($this->argument('user')));
    }
}



Команди закриття

Команди на основі закриття дають альтернативу визначенню консольних команд як класів. Так само, як замикання маршрутів є альтернативою контролерам, розглядайте командні замикання як альтернативу класам команд. У межах commandsметоду вашого app/Console/Kernel.phpфайлу Laravel завантажує 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}!");
});

Закриття прив’язане до базового екземпляра команди, тому ви маєте повний доступ до всіх допоміжних методів, до яких ви, як правило, зможете отримати доступ до повного класу команд.



Залежності підказки типу

На додаток до отримання аргументів і параметрів вашої команди, Закриття команд може також натякати на додаткові залежності, які ви хотіли б вирішити із контейнера служби :

use App\Models\User;
use App\Support\DripEmailer;

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



Описи команд закриття

Визначаючи команду на основі закриття, ви можете використовувати describeметод для додавання опису до команди. Цей опис відображатиметься під час запуску команд php artisan listабо php artisan help:

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



Визначення споживчих очікувань

Під час написання консольних команд звичайно збирати вхідні дані користувача за допомогою аргументів або параметрів. Laravel робить дуже зручним визначення вхідних даних, які ви очікуєте від користувача, за допомогою 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}';

Командне введення / виведення

Отримання вводу

Поки ваша команда виконується, вам, очевидно, потрібно буде отримати доступ до значень аргументів та параметрів, прийнятих вашою командою. Для цього ви можете використовувати методи argumentand 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']);

Як варіант, ви можете передати Закриття як другий аргумент anticipateметоду. Закриття буде викликатися кожного разу, коли користувач набирає введений символ. Закриття повинно приймати параметр рядка, що містить введені користувачем дані, і повертати масив параметрів для автозавершення:

$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
);

Вихідні дані

Для того, щоб відправити висновок в консоль, використовуйте lineinfocommentquestionі 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');

Ви можете використовувати newLineметод для відображення порожнього рядка:

$this->newLine();

// Write three blank lines...
$this->newLine(3);

Макети таблиць

tableМетод дозволяє легко правильно форматувати кілька рядків / стовпців даних. Просто передайте в заголовки та рядки метод. Ширина та висота будуть динамічно обчислюватися на основі даних:

$headers = ['Name', 'Email'];

$users = App\Models\User::all(['name', 'email'])->toArray();

$this->table($headers, $users);

Бари прогресу

Для довготривалих завдань може бути корисно показати індикатор прогресу. Використовуючи вихідний об'єкт, ми можемо запускати, просувати і зупиняти індикатор прогресу. По-перше, визначте загальну кількість кроків, які процес буде повторювати. Потім просуньте індикатор прогресу після обробки кожного елемента:

$users = App\Models\User::all();

$bar = $this->output->createProgressBar(count($users));

$bar->start();

foreach ($users as $user) {
    $this->performTask($user);

    $bar->advance();
}

$bar->finish();

Щоб отримати додаткові параметри, перегляньте документацію до компонента Symfony Progress Bar .

Реєстрація команд

Через 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 .

Події

Artisan відправляє три події при запуску команди: Illuminate\Console\Events\ArtisanStartingIlluminate\Console\Events\CommandStartingі Illuminate\Console\Events\CommandFinishedArtisanStartingПодія відправляється відразу після Artisan починає працювати. Далі CommandStartingподія надсилається безпосередньо перед запуском команди. Нарешті, CommandFinishedподія відправляється, як тільки команда закінчує виконуватись.

Подпишись на рассылку