Свои команды Artisan

Импорт товаров из файла, рассылка, очистка устаревших данных — такие задачи запускают не из браузера, а из терминала или по расписанию. Для них пишут собственные команды Artisan: они получают доступ ко всему приложению — моделям, почте, очередям.

Создание

php artisan make:command SendWeeklyReport

Класс появится в app/Console/Commands:

namespace App\Console\Commands;
 
use Illuminate\Console\Command;
 
class SendWeeklyReport extends Command
{
    protected $signature = 'reports:send';
 
    protected $description = 'Отправляет недельный отчёт администраторам';
 
    public function handle(): int
    {
        $this->info('Отчёт отправлен.');
 
        return self::SUCCESS;
    }
}

$signature — имя команды, handle() — её работа. Запуск:

php artisan reports:send

Аргументы и опции

Аргументы и опции описывают прямо в $signature:

protected $signature = 'users:export {format} {--limit=100} {--active}';
 
public function handle(): int
{
    $format = $this->argument('format');
    $limit = (int) $this->option('limit');
    $onlyActive = $this->option('active');
 
    return self::SUCCESS;
}

php artisan users:export csv --limit=500 --active

Запись	Значение
`{format}`	Обязательный аргумент
`{format?}`	Необязательный аргумент
`{format=csv}`	Аргумент со значением по умолчанию
`{--active}`	Флаг: есть или нет
`{--limit=100}`	Опция со значением

Вывод

$this->info('Готово');        // зелёный текст
$this->warn('Внимание');      // жёлтый
$this->error('Ошибка');       // красный
$this->line('Обычная строка');
 
$this->table(['Имя', 'Почта'], [['Анна', 'anna@example.com']]);

Вопросы

$name = $this->ask('Как назвать файл?');
 
if ($this->confirm('Удалить старые записи?')) {
    // …
}
 
$format = $this->choice('Формат', ['csv', 'json'], 0);

Индикатор выполнения

Для долгих операций показывают полосу прогресса:

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

Зависимости

В метод handle() можно запросить любой сервис — контейнер подставит его:

public function handle(ReportBuilder $builder): int
{
    $builder->build();
 
    return self::SUCCESS;
}

Запуск по расписанию и из кода

use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Schedule;
 
Schedule::command('reports:send')->weeklyOn(1, '9:00');
 
Artisan::call('users:export', ['format' => 'csv', '--limit' => 50]);

Частая ошибка

Команда должна возвращать код завершения: self::SUCCESS при успехе и self::FAILURE при ошибке. По нему планировщик и системы автоматического размещения понимают, удалась ли операция. Команда, которая при сбое молча вернула успех, скроет проблему.

if (!$file) {
    $this->error('Файл не найден.');
 
    return self::FAILURE;
}

Спасибо, что читаете!