Laravel - Artisan Console

Вступление

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

php artisan list

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

php artisan help migrate

 

Тинкер (REPL)

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

php artisan tinker

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

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

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

Тинкер использует белый список, чтобы определить, какие команды Artisan разрешено запускать в своей оболочке. По умолчанию, вы можете запустить , , , , , , и команды. Если вы хотите добавить в белый список больше команд, вы можете добавить их в массив в вашем файле конфигурации:clear-compileddownenvinspiremigrateoptimizeupcommandstinker.php

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

Alias ​​Blacklist

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

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

 

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

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

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

Чтобы создать новую команду, используйте команду Artisan. Эта команда создаст новый класс команд в каталоге. Не беспокойтесь, если этот каталог не существует в вашем приложении, так как он будет создан при первом запуске команды Artisan. Сгенерированная команда будет включать набор свойств и методов по умолчанию, которые присутствуют во всех командах:make:commandapp/Console/Commandsmake:command

php artisan make:command SendEmails

 

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

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

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

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

<?php

namespace App\Console\Commands;

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

 

Закрытие команды

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

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

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

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

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

Зависимости подсказок типа

В дополнение к получению аргументов и параметров вашей команды, команда Closures также может напечатать дополнительные зависимости, которые вы хотели бы разрешить из контейнера службы :

use App\User;
use App\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}';

 

Командный ввод / вывод

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

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

Вопросы с множественным выбором

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

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

 

Запись вывода

Для того, чтобы отправить вывод в консоли, используйте 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 Progress Bar .

 

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

Из-за loadвызова метода в методе ядра вашей консоли commandsвсе команды в каталоге будут автоматически зарегистрированы в Artisan. Фактически вы можете сделать дополнительные вызовы метода для сканирования других каталогов на наличие команд Artisan:app/Console/Commandsload

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

    // ...
}

Вы также можете вручную зарегистрировать команды, добавив его имя класса в $commandsсвойство вашего файла. Когда Artisan загружается, все команды, перечисленные в этом свойстве, будут разрешены сервисным контейнером и зарегистрированы в Artisan:app/Console/Kernel.php

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:refreshtruefalse

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