Может войдёшь?
Черновики Написать статью Профиль

Консоль Artisan

перевод документация 5.х

  1. 1. Введение
  2. 2. Создание команд
    1. 2.1. Структура команды
  3. 3. Ввод/вывод команды
    1. 3.1. Определение ожиданий ввода
    2. 3.2. Чтение ввода
    3. 3.3. Запрос ввода
    4. 3.4. Вывод
  4. 4. Регистрация команд
  5. 5. Вызов команд из кода
    1. 5.1. Вызов команд из других команд
  6. 6. Планирование команд Artisan
    1. 6.1. Ещё примеры планирования
Этот перевод актуален для англоязычной документации на (ветка 5.2) , (ветка 5.1) и (ветка 5.0). Опечатка? Выдели и нажми Ctrl+Enter.

Введение

Artisan — название интерфейса командной строки, который поставляется с Laravel. Он содержит набор полезных команд, помогающих вам при разработке приложения. Он основан на мощном компоненте Symfony Console. Для просмотра списка доступных команд используйте команду shlist:

shphp artisan list

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

shphp artisan help migrate

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

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

Для создания новой команды можно использовать Artisan-команду shmake:console, которая создаст заглушку, с которой вы можете начать работать.

shphp artisan make:console SendEmails

Эта команда создаст класс в app/Console/Commands/SendEmails.php. При создании команды может быть использован параметр sh--command для назначения имени команды в терминале:

shphp artisan make:console SendEmails --command=emails:send

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

Когда вы сгенерировали класс команды, вам нужно заполнить его свойства signature и description, которые используются при отображении вашей команды в списке команд (shlist).

При вызове вашей команды будет вызван метод PHPhandle(). В него вы можете поместить любую нужную логику. Давайте посмотрим на пример команды.

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

PHP
<?php

namespace App\Console\Commands;

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

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

  
/**
   * Описание консольной команды.
   *
   * @var string
   */
  
protected $description 'Send drip e-mails to a user';

  
/**
   * Служба "капельных" e-mail сообщений.
   *
   * @var DripEmailer
   */
  
protected $drip;

  
/**
   * Создание нового экземпляра команды.
   *
   * @param  DripEmailer  $drip
   * @return void
   */
  
public function __construct(DripEmailer $drip)
  {
    
parent::__construct();

    
$this->drip $drip;
  }

  
/**
   * Выполнение консольной команды.
   *
   * @return mixed
   */
  
public function handle()
  {
    
$this->drip->send(User::find($this->argument('user')));
  }
}

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

Определение ожиданий ввода

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

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

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

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

PHP
// Необязательный параметр...
email:send {user?}

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

Ключи, как и параметры, являются формой пользовательского ввода. Но при вводе команды они обозначаются префиксом из двух дефисов (—). Определяются ключи вот так:

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

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

shphp artisan email:send 1 --queue

Можно указать необходимость ввода пользователем значения для ключа при помощи знака равно (=):

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

В этом примере пользователь может передать значение для ключа вот так:

shphp artisan email:send 1 --queue=default

Для ключей также можно задать значение по умолчанию:

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

Чтобы задать сокращение при определении ключа, вы можете указать его перед именем ключа и отделить его символом вертикальной черты (|):

shemail:send {user} {--Q|queue}
+ 5.2

добавлено в 5.2 ()

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

shemail:send {user*}

email:send {user} {--id=*}

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

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

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

Чтение ввода

Во время выполнения команды вам, конечно, потребуется доступ к параметрам и ключам, которые были переданы ей на вход. Для этого вы можете использовать методы PHPargument() и PHPoption().

Для чтения значения параметра используйте метод PHPargument():

PHP
/**
 * Выполнение консольной команды.
 *
 * @return mixed
 */
public function handle()
{
    
$userId $this->argument('user');

    
//
}

Если вам необходимо прочитать все параметры в виде массива, вызовите метод PHPargument() без параметров:

PHP
$arguments $this->argument();

Ключи можно прочитать так же легко, как параметры, используя метод PHPoption(). Как и метод PHPargument(), вы можете вызвать метод PHPoption() без параметров, чтобы получить массив всех ключей:

PHP
// Чтение конкретного ключа...
$queueName $this->option('queue');

// Чтение всех ключей...
$options $this->option();

Если параметра или ключа не существует, будет возвращён PHPnull.

Запрос ввода

В дополнение к отображению вывода вы можете запросить у пользователя данные во время выполнения команды. Метод PHPask() выведет запрос, примет введённые данные, а затем вернёт их вашей команде:

PHP
/**
 * Выполнение консольной команды.
 *
 * @return mixed
 */
public function handle()
{
    
$name $this->ask('What is your name?');
}

Метод PHPsecret() похож на метод PHPask(), но он не отображает вводимые пользователем данные в консоли. Этот метод полезен при запросе секретной информации, такой как пароль:

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

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

Для получения от пользователя простого подтверждения можно использовать метод PHPconfirm(). По умолчанию этот метод возвращает false. Но если пользователь введёт y в ответ на запрос, то метод вернёт true:

PHP
if ($this->confirm('Do you wish to continue? [y|N]')) {
    
//
}

Предоставление выбора пользователю

Метод PHPanticipate() можно использовать для предоставления пользователю возможных вариантов для выбора. Независимо от наличия этих вариантов пользователь может указать свой вариант.

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

Для предоставления пользователю определённого набора вариантов можно использовать метод PHPchoice(). Пользователь выбирает номер варианта, но вам будет возвращено его значение. Можно задать значение по умолчанию, на случай если ничего не выбрано:

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

Вывод

Для вывода вы можете использовать методы PHPline(), PHPinfo(), PHPcomment(), PHPquestion() и PHPerror(). Каждый из них будет использовать подходящие по смыслу цвета ANSI для отображении текста.

Для вывода информационного сообщения используйте метод PHPinfo(). Он выводит в консоль текст зелёного цвета:

PHP
/**
 * Выполнение консольной команды.
 *
 * @return mixed
 */
public function handle()
{
    
$this->info('Display this on the screen');
}

Для вывода сообщения об ошибке используйте метод PHPerror(). Он выводит в консоль текст красного цвета:

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

Для простого вывода текста в консоль используйте метод PHPline(). Он выводит текст не используя специальных цветов:

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

Табличный вывод

Метод PHPtable() позволяет легко форматировать несколько строк/столбцов данных. Просто передайте в него заголовки и строки. Ширина и высота будет динамически определена на основе переданных данных:

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

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

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

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

Для продолжительных задач бывает полезно вывести индикатор процесса. Используя объект вывода мы можем запустить, передвинуть и остановить индикатор. При запуске процесса вам надо определить число шагов, а затем передвигать индикатор после каждого шага:

PHP
$users App\User::all();

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

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

  
$bar->advance();
}

$bar->finish();

Более подробная информация указана в документации по индикаторам процесса Symfony.

+ 5.0

добавлено в 5.0 ()

Указание имени среды для выполнения команды

Вы можете указать среду, которая будет использоваться при выполнении команды, с помощью ключа sh--env:

shphp artisan migrate --env=local

Вывод вашей текущей версии Laravel

Вы также можете узнать версию текущей установки Laravel с помощью ключа sh--version:

shphp artisan --version

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

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

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

Вызов команд из кода

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

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

    
//
});

С помощью метода PHPqueue() можно даже поставить команды в очередь, тогда они будут обработаны в фоне с помощью ваших обработчиков очереди:

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

    
//
});

Когда нужно указать значение ключа, который не принимает строковое значение, например, флаг sh--force команды shmigrate:refresh, вы можете передать логическое значение true или false:

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

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

Иногда необходимо вызвать другую команду из своей. Для этого используйте метод PHPcall(). Он принимает имя команды и массив её параметров:

PHP
/**
 * Выполнение консольной команды.
 *
 * @return mixed
 */
public function handle()
{
  
$this->call('email:send', [
    
'user' => 1'--queue' => 'default'
  
]);

  
//
}

Если вы хотите вызвать другую команду и запретить её вывод в консоль, используйте метод PHPcallSilent(). Этот метод принимает те же параметры, что и метод PHPcall():

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

Планирование команд Artisan

Данный раздел статьи актуален только для версии 5.0 и был
удален в версии 5.1.

Раньше разработчикам приходилось создавать Cron-задачи для каждой консольной команды, которую они хотели запланировать. Это утомительно. Для планирования консольных команд теперь не ведётся контроль версий, и для добавления Cron-задач вам необходимо подключаться к серверу по SSH. Давайте упростим нам жизнь. Планировщик команд Laravel позволяет вам гибко и выразительно задавать план команд в самом Laravel, а на сервере нужна только одна Cron-задача.

Ваш план команд хранится в файле app/Console/Kernel.php. В этом классе вы найдёте метод PHPschedule. Чтобы помочь вам разобраться, в метод включён простой пример. Вы можете добавлять в объект PHPSchedule столько запланированных задач, сколько пожелаете. А на сервере вам надо добавить единственную Cron-задачу:

sh* * * * * php /path/to/artisan schedule:run 1>> /dev/null 2>&1

Эта задача будет каждую минуту вызывать планировщик команд Laravel. А тот в свою очередь будет проверять имеющиеся в плане задачи и выполнять необходимые. Проще некуда!

Ещё примеры планирования

Давайте рассмотрим ещё несколько примеров планирования.

Планирование замыканий

PHP
$schedule->call(function()
{
    
// Выполнить какое-то задание...

})->hourly();

Планирование терминальных команд

PHP
$schedule->exec('composer self-update')->daily();

Ручное Cron-выражение

PHP
$schedule->command('foo')->cron('* * * * *');

Частые задачи

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

PHP
$schedule->command('foo')->everyFiveMinutes();

$schedule->command('foo')->everyTenMinutes();

$schedule->command('foo')->everyThirtyMinutes();

Ежедневные задачи

PHP
$schedule->command('foo')->daily();

Ежедневные задачи в указанное время (24-часовой формат)

PHP
$schedule->command('foo')->dailyAt('15:00');

Задачи, выполняемые дважды в день

PHP
$schedule->command('foo')->twiceDaily();

Задачи по будням

PHP
$schedule->command('foo')->weekdays();

Еженедельные задачи

PHP
$schedule->command('foo')->weekly();

// Планирование еженедельной задачи на конкретный день (0-6) и время...
$schedule->command('foo')->weeklyOn(1'8:00');

Ежемесячные задачи

PHP
$schedule->command('foo')->monthly();

Задачи, выполняемые в указанный день недели

PHP
$schedule->command('foo')->mondays();
$schedule->command('foo')->tuesdays();
$schedule->command('foo')->wednesdays();
$schedule->command('foo')->thursdays();
$schedule->command('foo')->fridays();
$schedule->command('foo')->saturdays();
$schedule->command('foo')->sundays();

Защита от наложения задач

По умолчанию запланированные задачи будут запущены, даже если предыдущий экземпляр всё ещё запущен. Для предотвращения такого поведения используйте метод PHPwithoutOverlapping:

PHP
$schedule->command('foo')->withoutOverlapping();

В этом примере команда foo будет запускаться каждую минуту, если она уже не запущена.

Указание конкретных сред для запуска задач

PHP
$schedule->command('foo')->monthly()->environments('production');

Указание необходимости запуска задачи даже в режиме техобслуживания

PHP
$schedule->command('foo')->monthly()->evenInMaintenanceMode();

Запуск задачи только в случае возврата PHPtrue

PHP
$schedule->command('foo')->monthly()->when(function()
{
    return 
true;
});

Отправка вывода задачи на e-mail

PHP
$schedule->command('foo')->sendOutputTo($filePath)->emailOutputTo('foo@example.com');

Необходимо отправить вывод в файл перед тем, как он сможет быть послан по e-mail.

Отправка вывода задачи в указанное место

PHP
$schedule->command('foo')->sendOutputTo($filePath);

Выполнить ping указанного URL после запуска задачи

PHP
$schedule->command('foo')->thenPing($url);

Для использования функции PHPthenPing($url) необходима HTTP-библиотека Guzzle. Вы можете добавить Guzzle 5 в свой проект, добавив следующую строку в файл PHPcomposer.json:

conf"guzzlehttp/guzzle": "~5.0"

Написать комментарий

Разметка: ? ?

Авторизуйся, чтобы прокомментировать.