Artisan Консоль

• Введение
  • Tinker (REPL)
• Создание команд
  • Генерация команд
  • Структура команды
  • Команды на основе замыканий
  • Изолируемые команды
• Определение ожидаемого ввода
  • Аргументы
  • Опции
  • Массивы ввода
  • Описание ввода
  • Запрос недостающего ввода
• Ввод/вывод команд
  • Получение ввода
  • Запрос ввода
  • Вывод данных
• Регистрация команд
• Программное выполнение команд
  • Вызов команд из других команд
• Обработка сигналов
• Настройка шаблонов
• События

#Введение

Artisan — это интерфейс командной строки, включённый в Laravel. Artisan находится в корне вашего приложения в виде скрипта artisan и предоставляет множество полезных команд, которые помогут вам при разработке приложения. Чтобы увидеть список всех доступных команд Artisan, используйте команду list:

php artisan list

Каждая команда также содержит экран "help", который отображает и описывает доступные аргументы и опции команды. Чтобы просмотреть экран помощи, перед именем команды добавьте help:

php artisan help migrate

#Laravel Sail

Если вы используете Laravel Sail в качестве локальной среды разработки, не забывайте вызывать команды Artisan через команду sail. Sail выполнит ваши команды Artisan внутри Docker-контейнеров вашего приложения:

./vendor/bin/sail artisan list

#Tinker (REPL)

Laravel Tinker — это мощный REPL для фреймворка Laravel, основанный на пакете PsySH.

#Установка

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

composer require laravel/tinker

#Использование

Tinker позволяет взаимодействовать со всем вашим Laravel-приложением через командную строку, включая ваши модели Eloquent, задания, события и многое другое. Чтобы войти в среду Tinker, выполните команду Artisan tinker:

php artisan tinker

Вы можете опубликовать файл конфигурации Tinker с помощью команды vendor:publish:

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

#Список разрешённых команд

Tinker использует список разрешённых команд, чтобы определить, какие команды Artisan можно запускать в его оболочке. По умолчанию разрешены команды clear-compiled, down, env, inspire, migrate, optimize и up. Если вы хотите разрешить больше команд, добавьте их в массив commands в вашем файле конфигурации tinker.php:

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

#Классы, которые не должны иметь алиасы

Обычно Tinker автоматически создаёт алиасы для классов при взаимодействии с ними. Однако вы можете указать классы, для которых алиасы создавать не нужно. Для этого перечислите их в массиве dont_alias в файле конфигурации tinker.php:

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

#Создание команд

Помимо команд, предоставляемых Artisan, вы можете создавать собственные пользовательские команды. Обычно команды хранятся в директории app/Console/Commands, но вы можете выбрать любое место, если ваши команды будут загружаться Composer.

#Генерация команд

Чтобы создать новую команду, используйте Artisan-команду make:command. Она создаст новый класс команды в директории app/Console/Commands. Если этой директории нет, она будет создана при первом запуске make:command:

php artisan make:command SendEmails

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

После создания команды следует задать подходящие значения для свойств signature и description класса. Эти свойства используются при отображении команды на экране list. Свойство signature также позволяет определить ожидаемые входные данные команды. Метод handle вызывается при выполнении команды. Логику команды можно разместить в этом методе.

Рассмотрим пример команды. Обратите внимание, что мы можем запросить любые нужные зависимости через handle-метод команды. Laravel контейнер служб автоматически внедрит все зависимости, помеченные подсказками типов в сигнатуре этого метода:

<?php

namespace App\Console\Commands;

use App\Models\User;
use App\Support\DripEmailer;
use Illuminate\Console\Command;

class SendEmails extends Command
{
    /**
     * Имя и сигнатура консольной команды.
     *
     * @var string
     */
    protected $signature = 'mail:send {user}';

    /**
     * Описание консольной команды.
     *
     * @var string
     */
    protected $description = 'Отправить маркетинговое письмо пользователю';

    /**
     * Выполнить консольную команду.
     */
    public function handle(DripEmailer $drip): void
    {
        $drip->send(User::find($this->argument('user')));
    }
}

#Команды на основе замыканий

Команды на основе замыканий — альтернатива определению команд в виде классов. Так же, как маршруты на основе замыканий — альтернатива контроллерам, команды на основе замыканий — альтернатива классам команд. В методе commands файла app/Console/Kernel.php Laravel загружает файл routes/console.php:

/**
 * Зарегистрировать команды на основе замыканий для приложения.
 */
protected function commands(): void
{
    require base_path('routes/console.php');
}

Хотя этот файл не определяет HTTP-маршруты, он задаёт консольные точки входа (маршруты) в приложение. В этом файле вы можете определить все команды на основе замыканий с помощью метода Artisan::command. Метод command принимает два аргумента: сигнатуру команды и замыкание, которое получает аргументы и опции команды:

Artisan::command('mail:send {user}', function (string $user) {
    $this->info("Отправка письма пользователю: {$user}!");
});

Замыкание привязано к экземпляру команды, поэтому у вас есть полный доступ ко всем вспомогательным методам, доступным в полном классе команды.

#Внедрение зависимостей через типизацию

Помимо аргументов и опций команды, замыкания могут типизировать дополнительные зависимости, которые будут разрешены из контейнера сервисов:

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

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

#Описание команд на основе замыканий

При определении команды на основе замыкания вы можете использовать метод purpose для добавления описания команды. Это описание будет отображаться при выполнении php artisan list или php artisan help:

Artisan::command('mail:send {user}', function (string $user) {
    // ...
})->purpose('Отправить маркетинговое письмо пользователю');

#Изолируемые команды

Иногда нужно гарантировать, что одновременно выполняется только один экземпляр команды. Для этого реализуйте интерфейс Illuminate\Contracts\Console\Isolatable в классе команды:

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Contracts\Console\Isolatable;

class SendEmails extends Command implements Isolatable
{
    // ...
}

Когда команда помечена как Isolatable, Laravel автоматически добавит опцию --isolated. При вызове команды с этой опцией Laravel гарантирует, что другие экземпляры команды не выполняются. Это достигается попыткой получить атомарную блокировку через драйвер кеша приложения. Если другие экземпляры команды запущены, команда не выполнится, но завершится с успешным кодом выхода:

php artisan mail:send 1 --isolated

Если вы хотите указать код возврата, который команда должна вернуть при невозможности выполнения, задайте его через опцию isolated:

php artisan mail:send 1 --isolated=12

#Идентификатор блокировки

По умолчанию Laravel использует имя команды для генерации ключа блокировки в кеше. Вы можете настроить этот ключ, определив метод isolatableId в классе команды, чтобы включить аргументы или опции команды в ключ:

/**
 * Получить идентификатор для изолируемой команды.
 */
public function isolatableId(): string
{
    return $this->argument('user');
}

#Время истечения блокировки

По умолчанию блокировки изоляции истекают после завершения команды. Если команда прерывается и не может завершиться, блокировка истекает через час. Вы можете изменить время истечения, определив метод isolationLockExpiresAt в команде:

use DateTimeInterface;
use DateInterval;

/**
 * Определить время истечения блокировки изоляции для команды.
 */
public function isolationLockExpiresAt(): DateTimeInterface|DateInterval
{
    return now()->addMinutes(5);
}

#Определение ожидаемого ввода

При написании консольных команд часто требуется получать ввод от пользователя через аргументы или опции. Laravel упрощает определение ожидаемого ввода с помощью свойства signature в командах. Свойство signature позволяет задать имя, аргументы и опции команды в одном выразительном синтаксисе, похожем на маршруты.

#Аргументы

Все аргументы и опции пользователя заключаются в фигурные скобки. В следующем примере команда определяет один обязательный аргумент: user:

/**
 * Имя и сигнатура консольной команды.
 *
 * @var string
 */
protected $signature = 'mail:send {user}';

Вы также можете сделать аргументы необязательными или задать им значения по умолчанию:

// Необязательный аргумент...
'mail:send {user?}'

// Необязательный аргумент со значением по умолчанию...
'mail:send {user=foo}'

#Опции

Опции, как и аргументы, являются формой пользовательского ввода. Опции при передаче через командную строку начинаются с двух дефисов (--). Существуют два типа опций: принимающие значение и не принимающие. Опции без значения служат булевым переключателем. Рассмотрим пример такой опции:

/**
 * Имя и сигнатура консольной команды.
 *
 * @var string
 */
protected $signature = 'mail:send {user} {--queue}';

В этом примере ключ --queue можно указать при вызове команды Artisan. Если ключ --queue передан, значение опции будет true. В противном случае значение будет false:

php artisan mail:send 1 --queue

#Опции с значениями

Далее рассмотрим опцию, которая ожидает значение. Если пользователь должен указать значение, добавьте к имени опции знак =:

/**
 * Имя и сигнатура консольной команды.
 *
 * @var string
 */
protected $signature = 'mail:send {user} {--queue=}';

В этом примере пользователь может передать значение опции так. Если опция не указана, её значение будет null:

php artisan mail:send 1 --queue=default

Вы можете задать значения по умолчанию для опций, указав их после имени опции. Если пользователь не передаст значение, будет использовано значение по умолчанию:

'mail:send {user} {--queue=default}'

#Сокращения для опций

Чтобы задать сокращение для опции, укажите его перед именем опции, разделив символом |:

'mail:send {user} {--Q|queue}'

При вызове команды в терминале сокращения опций должны начинаться с одного дефиса, и при указании значения не нужно использовать знак =:

php artisan mail:send 1 -Qdefault

#Массивы ввода

Если вы хотите, чтобы аргумент или опция принимали несколько значений, используйте символ *. Рассмотрим пример с таким аргументом:

'mail:send {user*}'

При вызове команды аргументы user могут передаваться по порядку. Например, следующая команда установит значение user как массив с элементами 1 и 2:

php artisan mail:send 1 2

Символ * можно комбинировать с необязательным аргументом, чтобы разрешить ноль или более значений:

'mail:send {user?*}'

#Массивы опций

При определении опции, которая принимает несколько значений, каждое значение должно передаваться с префиксом имени опции:

'mail:send {--id=*}'

Такую команду можно вызвать, передав несколько аргументов --id:

php artisan mail:send --id=1 --id=2

#Описание ввода

Вы можете добавить описания к аргументам и опциям, разделяя имя и описание двоеточием. Если описание длинное, его можно разбить на несколько строк:

/**
 * Имя и сигнатура консольной команды.
 *
 * @var string
 */
protected $signature = 'mail:send
                        {user : ID пользователя}
                        {--queue : Нужно ли ставить задание в очередь}';

#Запрос недостающего ввода

Если в команде есть обязательные аргументы, при их отсутствии пользователь получит ошибку. Вместо этого вы можете настроить автоматический запрос недостающих аргументов, реализовав интерфейс PromptsForMissingInput:

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Contracts\Console\PromptsForMissingInput;

class SendEmails extends Command implements PromptsForMissingInput
{
    /**
     * Имя и сигнатура консольной команды.
     *
     * @var string
     */
    protected $signature = 'mail:send {user}';

    // ...
}

Если Laravel нужно получить обязательный аргумент, он автоматически задаст пользователю вопрос, формулируя его на основе имени или описания аргумента. Чтобы настроить вопрос, реализуйте метод promptForMissingArgumentsUsing, возвращающий массив вопросов с ключами — именами аргументов:

/**
 * Запросить недостающие аргументы с помощью возвращаемых вопросов.
 *
 * @return array
 */
protected function promptForMissingArgumentsUsing()
{
    return [
        'user' => 'Какой ID пользователя должен получить письмо?',
    ];
}

Вы также можете задать плейсхолдер, используя кортеж с вопросом и плейсхолдером:

return [
    'user' => ['Какой ID пользователя должен получить письмо?', 'Например, 123'],
];

Если хотите полный контроль над запросом, можете вернуть замыкание, которое задаст вопрос и вернёт ответ пользователя:

use App\Models\User;
use function Laravel\Prompts\search;

// ...

return [
    'user' => fn () => search(
        label: 'Поиск пользователя:',
        placeholder: 'Например, Taylor Otwell',
        options: fn ($value) => strlen($value) > 0
            ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
            : []
    ),
];

Подробная документация по Laravel Prompts содержит дополнительную информацию о доступных запросах и их использовании.

Если вы хотите запрашивать у пользователя выбор или ввод опций, вы можете включить запросы в метод handle команды. Если же хотите запрашивать опции только после автоматического запроса недостающих аргументов, реализуйте метод afterPromptingForMissingArguments:

use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use function Laravel\Prompts\confirm;

// ...

/**
 * Выполнить действия после запроса недостающих аргументов.
 *
 * @param  \Symfony\Component\Console\Input\InputInterface  $input
 * @param  \Symfony\Component\Console\Output\OutputInterface  $output
 * @return void
 */
protected function afterPromptingForMissingArguments(InputInterface $input, OutputInterface $output)
{
    $input->setOption('queue', confirm(
        label: 'Хотите поставить письмо в очередь?',
        default: $this->option('queue')
    ));
}

#Ввод/вывод команд

#Получение ввода

Во время выполнения команды вам, вероятно, понадобится получить значения аргументов и опций. Для этого используйте методы argument и option. Если аргумент или опция отсутствуют, будет возвращено null:

/**
 * Выполнить консольную команду.
 */
public function handle(): void
{
    $userId = $this->argument('user');
}

Если нужно получить все аргументы в виде array, вызовите метод arguments:

$arguments = $this->arguments();

Опции можно получить так же просто, как аргументы, с помощью метода option. Чтобы получить все опции в виде массива, вызовите метод options:

// Получить конкретную опцию...
$queueName = $this->option('queue');

// Получить все опции в виде массива...
$options = $this->options();

#Запрос ввода

Помимо вывода, вы можете запрашивать ввод у пользователя во время выполнения команды. Метод ask задаст вопрос, примет ввод и вернёт его обратно в команду:

/**
 * Выполнить консольную команду.
 */
public function handle(): void
{
    $name = $this->ask('Как вас зовут?');

    // ...
}

Метод ask принимает необязательный второй аргумент — значение по умолчанию, которое возвращается, если пользователь не ввёл ничего:

$name = $this->ask('Как вас зовут?', 'Taylor');

Метод secret похож на ask, но ввод пользователя не отображается в консоли. Это удобно для ввода конфиденциальных данных, например паролей:

$password = $this->secret('Введите пароль:');

#Запрос подтверждения

Если нужно получить простой ответ "да" или "нет", используйте метод confirm. По умолчанию он возвращает false, но если пользователь введёт y или yes, вернёт true:

if ($this->confirm('Хотите продолжить?')) {
    // ...
}

При необходимости вы можете указать, что запрос подтверждения должен по умолчанию возвращать true, передав true в качестве второго аргумента методу confirm:

if ($this->confirm('Хотите продолжить?', true)) {
    // ...
}

#Автодополнение

Метод anticipate позволяет задать варианты автодополнения. Пользователь может ввести любой ответ, независимо от подсказок:

$name = $this->anticipate('Как вас зовут?', ['Taylor', 'Dayle']);

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

$name = $this->anticipate('Какой у вас адрес?', function (string $input) {
    // Вернуть варианты автодополнения...
});

#Вопросы с выбором

Если нужно предложить пользователю набор вариантов, используйте метод choice. Третий аргумент задаёт индекс значения по умолчанию, если пользователь не выберет вариант:

$name = $this->choice(
    'Как вас зовут?',
    ['Taylor', 'Dayle'],
    $defaultIndex
);

Метод choice также принимает необязательные четвёртый и пятый аргументы — максимальное число попыток и разрешение множественного выбора:

$name = $this->choice(
    'Как вас зовут?',
    ['Taylor', 'Dayle'],
    $defaultIndex,
    $maxAttempts = null,
    $allowMultipleSelections = false
);

#Вывод данных

Для вывода в консоль используйте методы line, info, comment, question, warn и error. Каждый из них выводит текст с соответствующим цветом ANSI. Например, info обычно выводит зелёный текст:

/**
 * Выполнить консольную команду.
 */
public function handle(): void
{
    // ...

    $this->info('Команда выполнена успешно!');
}

Для вывода ошибки используйте метод error. Текст ошибки обычно красный:

$this->error('Что-то пошло не так!');

Метод line выводит простой текст без цвета:

$this->line('Отобразить это на экране');

Метод newLine выводит пустую строку:

// Вывести одну пустую строку...
$this->newLine();

// Вывести три пустые строки...
$this->newLine(3);

#Таблицы

Метод table упрощает форматирование нескольких строк и столбцов данных. Нужно лишь указать имена столбцов и данные, а Laravel автоматически рассчитает ширину и высоту таблицы:

use App\Models\User;

$this->table(
    ['Имя', 'Email'],
    User::all(['name', 'email'])->toArray()
);

#Индикаторы прогресса

Для долгих задач полезно показывать индикатор прогресса, информирующий пользователя о ходе выполнения. Метод withProgressBar отображает индикатор и продвигает его при каждой итерации по переданному итерабельному значению:

use App\Models\User;

$users = $this->withProgressBar(User::all(), function (User $user) {
    $this->performTask($user);
});

Иногда нужен более ручной контроль над продвижением индикатора. Сначала задайте общее число шагов, затем продвигайте индикатор после обработки каждого элемента:

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

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

$bar->start();

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

    $bar->advance();
}

$bar->finish();

#Регистрация команд

Все консольные команды регистрируются в классе App\Console\Kernel вашего приложения, который является «консольным ядром» приложения. В методе commands этого класса вы увидите вызов метода ядра load. Метод load просканирует каталог app/Console/Commands и автоматически зарегистрирует в Artisan каждую содержащуюся в нём команду. Вы также можете дополнительно вызывать load, чтобы просканировать другие каталоги на предмет команд Artisan:

/**
 * Зарегистрировать команды приложения.
 */
protected function commands(): void
{
    $this->load(__DIR__.'/Commands');
    $this->load(__DIR__.'/../Domain/Orders/Commands');

    // ...
}

При необходимости вы можете вручную зарегистрировать команды, добавив имена классов в свойство $commands класса App\Console\Kernel. Если этого свойства нет, создайте его. При загрузке Artisan все команды из этого массива будут разрешены через контейнер сервисов и зарегистрированы:

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

#Программное выполнение команд

Иногда может потребоваться выполнить команду Artisan вне CLI. Например, вы можете захотеть выполнить команду Artisan из маршрута или контроллера. Для этого можно использовать метод call у фасада Artisan. Метод call принимает в качестве первого аргумента либо сигнатуру команды, либо имя класса команды, а вторым аргументом — массив параметров команды. Будет возвращён код завершения:

use Illuminate\Support\Facades\Artisan;

Route::post('/user/{user}/mail', function (string $user) {
    $exitCode = Artisan::call('mail:send', [
        'user' => $user, '--queue' => 'default'
    ]);

    // ...
});

Или можно передать всю команду Artisan в метод call в виде строки:

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

#Передача массивов значений

Если команда определяет опцию, принимающую массив, передайте массив значений:

use Illuminate\Support\Facades\Artisan;

Route::post('/mail', function () {
    $exitCode = Artisan::call('mail:send', [
        '--id' => [5, 13]
    ]);
});

#Передача булевых значений

Если нужно указать значение опции, не принимающей строковые значения, например флаг --force команды migrate:refresh, передайте true или false:

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

#Помещение команд Artisan в очередь

С помощью метода queue фасада Artisan вы можете поставить команды в очередь для фоновой обработки работниками очереди. Перед использованием убедитесь, что очередь настроена и запущен слушатель:

use Illuminate\Support\Facades\Artisan;

Route::post('/user/{user}/mail', function (string $user) {
    Artisan::queue('mail:send', [
        'user' => $user, '--queue' => 'default'
    ]);

    // ...
});

С помощью методов onConnection и onQueue можно указать соединение и очередь, в которую должна быть отправлена команда:

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

#Вызов команд из других команд

Иногда вы можете захотеть вызвать другие команды из существующей команды Artisan. Для этого используйте метод call. Метод call принимает имя команды и array аргументов/опций команды:

/**
 * Выполнить консольную команду.
 */
public function handle(): void
{
    $this->call('mail:send', [
        'user' => 1, '--queue' => 'default'
    ]);

    // ...
}

Если вы хотите вызвать другую консольную команду и подавить весь её вывод, можно использовать метод callSilently. Метод callSilently имеет ту же сигнатуру, что и метод call:

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

#Обработка сигналов

Как известно, операционные системы могут отправлять сигналы запущенным процессам. Например, сигнал SIGTERM — это запрос на завершение программы. Чтобы слушать сигналы в командах Artisan и выполнять код при их получении, используйте метод trap:

/**
 * Выполнить консольную команду.
 */
public function handle(): void
{
    $this->trap(SIGTERM, fn () => $this->shouldKeepRunning = false);

    while ($this->shouldKeepRunning) {
        // ...
    }
}

Чтобы слушать несколько сигналов одновременно, передайте массив сигналов в метод trap:

$this->trap([SIGTERM, SIGQUIT], function (int $signal) {
    $this->shouldKeepRunning = false;

    dump($signal); // SIGTERM / SIGQUIT
});

#Настройка шаблонов

Команды Artisan make создают различные классы, например контроллеры, задания, миграции и тесты. Эти классы генерируются на основе "шаблонов" (stub), которые заполняются значениями из вашего ввода. Если вы хотите внести небольшие изменения в файлы, создаваемые Artisan, используйте команду stub:publish для публикации наиболее распространённых шаблонов в ваше приложение для дальнейшей настройки:

php artisan stub:publish

Опубликованные шаблоны будут находиться в директории stubs в корне приложения. Все изменения в этих шаблонах будут применяться при генерации соответствующих классов через команды Artisan make.

#События

Artisan генерирует три события при выполнении команд: Illuminate\Console\Events\ArtisanStarting, Illuminate\Console\Events\CommandStarting и Illuminate\Console\Events\CommandFinished. Событие ArtisanStarting вызывается сразу при запуске Artisan. Затем CommandStarting вызывается непосредственно перед выполнением команды. И, наконец, CommandFinished вызывается после завершения команды.