Приложения консоли

Помимо богатых возможностей для создания веб-приложений, Yii также предоставляет полную поддержку приложений консоли, которые в основном используются для создания фоновых и обслуживающих задач, которые необходимо выполнять для веб-сайта.

Структура приложений консоли очень похожа на веб-приложение Yii. Она состоит из одного или нескольких классов yii\console\Controller, которые часто называют командами в среде консоли. Каждый контроллер также может иметь одну или несколько действий, как и веб-контроллеры.

Оба шаблона проекта уже содержат приложение консоли. Вы можете запустить его, вызвав скрипт yii, который находится в базовом каталоге репозитория. Это покажет вам список доступных команд, если вы запустите его без дополнительных параметров:

Как видно из скриншота, Yii уже определил набор команд, которые доступны по умолчанию:

• AssetController - Позволяет объединять и сжимать файлы JavaScript и CSS. Более подробную информацию об этой команде вы можете найти в разделе Аксессуары.
• CacheController - Позволяет очистить кэши приложения.
• FixtureController - Управляет загрузкой и выгрузкой данных фикстур для целей тестирования. Более подробная информация об этой команде представлена в разделе Раздел тестирования по фикстурам.
• HelpController - Предоставляет справочную информацию о командах консоли, это команда по умолчанию, и выводит то, что вы увидели в выводе выше.
• MessageController - Извлекает сообщения для перевода из исходных файлов. Более подробную информацию об этой команде см. в разделе Раздел I18N.
• MigrateController - Управляет миграциями приложения. Более подробная информация о миграциях базы данных представлена в разделе Раздел миграций базы данных.
• ServeController - Позволяет запускать встроенный веб-сервер PHP.

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

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

yii <route> [--option1=value1 --option2=value2 ... argument1 argument2 ...]

В приведенном выше примере <route> относится к маршруту действия контроллера. Параметры заполнят свойства класса, а аргументы — параметрами метода действия.

Например, MigrateController::actionUp() с MigrateController::$migrationTable, установленной на migrations, и ограничением в 5 миграций можно вызвать следующим образом:

yii migrate/up 5 --migrationTable=migrations

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

Скрипт входа

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

#!/usr/bin/env php
<?php
/**
 * Yii console bootstrap file.
 */

defined('YII_DEBUG') or define('YII_DEBUG', true);
defined('YII_ENV') or define('YII_ENV', 'dev');

require(__DIR__ . '/vendor/autoload.php');
require(__DIR__ . '/vendor/yiisoft/yii2/Yii.php');

$config = require(__DIR__ . '/config/console.php');

$application = new yii\console\Application($config);
$exitCode = $application->run();
exit($exitCode);

Этот скрипт будет создан в составе вашего приложения; вы можете изменить его в соответствии со своими потребностями. Константу YII_DEBUG можно установить на false, если вы не хотите видеть трассировку стека при ошибках и/или хотите улучшить общую производительность. В шаблонах как базовых, так и расширенных, скрипт входа приложения консоли имеет отладку по умолчанию, чтобы предоставить более удобную для разработчика среду.

Настройка

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

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

Подсказка: Иногда вам может понадобиться запустить команду консоли с конфигурацией приложения, отличной от указанной в скрипте входа. Например, вы можете захотеть использовать команду yii migrate для обновления баз данных тестов, которые настраиваются в каждом отдельном наборе тестов. Чтобы динамически изменить конфигурацию, просто укажите файл пользовательской конфигурации приложения с помощью параметра appconfig при выполнении команды:

yii <route> --appconfig=path/to/config.php ...

Завершение команд консоли

Автозаполнение аргументов команд — полезная функция при работе с оболочкой. Начиная с версии 2.0.11, команда ./yii предоставляет автозаполнение для оболочек Bash и ZSH «из коробки».

Завершение Bash

Убедитесь, что установлено завершение Bash. Для большинства установок оно доступно по умолчанию.

Поместите скрипт завершения в /etc/bash_completion.d/:

 curl -L https://raw.githubusercontent.com/yiisoft/yii2/master/contrib/completion/bash/yii -o /etc/bash_completion.d/yii

Для временного использования вы можете поместить файл в текущую директорию и включить его в текущую сессию через source yii. При глобальной установке может потребоваться перезапустить терминал или source ~/.bashrc для его активации.

Обратитесь к Руководству по Bash для получения других способов включения скрипта завершения в вашу среду.

Завершение ZSH

Поместите скрипт завершения в каталог для завершений, используя, например, ~/.zsh/completion/

mkdir -p ~/.zsh/completion
curl -L https://raw.githubusercontent.com/yiisoft/yii2/master/contrib/completion/zsh/_yii -o ~/.zsh/completion/_yii

Включите каталог в $fpath, например, добавив его в ~/.zshrc

fpath=(~/.zsh/completion $fpath)

Убедитесь, что compinit загружен или сделайте это, добавив в ~/.zshrc

autoload -Uz compinit && compinit -i

Затем перезапустите вашу оболочку

exec $SHELL -l

Создание собственных команд консоли

Контроллер и действие консоли

Команда консоли определяется как класс контроллера, расширяющий yii\console\Controller. В классе контроллера вы определяете одно или несколько действий, которые соответствуют подкомандам контроллера. В каждом действии вы пишете код, реализующий соответствующие задачи для этой конкретной подкоманды.

При выполнении команды вам необходимо указать маршрут к действию контроллера. Например, маршрут migrate/create вызывает подкоманду, которая соответствует методу действия MigrateController::actionCreate(). Если маршрут, предлагаемый во время выполнения, не содержит идентификатора действия, будет выполнено действие по умолчанию (как и в случае с веб-контроллером).

Параметры

Переопределяя метод yii\console\Controller::options(), вы можете указать параметры, доступные для команды консоли (контроллер/идентификатор действия). Метод должен возвращать список общедоступных свойств класса контроллера. При выполнении команды вы можете указать значение параметра с помощью синтаксиса --optionName=optionValue. Это присвоит optionValue свойству optionName класса контроллера.

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

Псевдонимы параметров

Начиная с версии 2.0.8, команда консоли предоставляет метод yii\console\Controller::optionAliases() для добавления псевдонимов к параметрам.

Чтобы определить псевдоним, переопределите yii\console\Controller::optionAliases() в вашем контроллере, например:

namespace app\commands;

use yii\console\Controller;

class HelloController extends Controller
{
    public $message;
    
    public function options($actionID)
    {
        return ['message'];
    }
    
    public function optionAliases()
    {
        return ['m' => 'message'];
    }
    
    public function actionIndex()
    {
        echo $this->message . "\n";
    }
}

Теперь вы можете использовать следующий синтаксис для выполнения команды:

yii hello -m=hello

Аргументы

Помимо параметров, команда также может принимать аргументы. Аргументы будут переданы в качестве параметров методу действия, соответствующему запрошенной подкоманде. Первый аргумент соответствует первому параметру, второй — второму и так далее. Если при вызове команды не предоставлено достаточно аргументов, соответствующие параметры примут объявленные значения по умолчанию, если они определены. Если значение по умолчанию не задано и значение не предоставлено во время выполнения, команда завершится с ошибкой.

Вы можете использовать подсказку типа array для указания того, что аргумент должен обрабатываться как массив. Массив будет создан путем разделения входной строки на запятые.

Следующий пример демонстрирует, как объявить аргументы:

class ExampleController extends \yii\console\Controller
{
    // The command "yii example/create test" will call "actionCreate('test')"
    public function actionCreate($name) { ... }

    // The command "yii example/index city" will call "actionIndex('city', 'name')"
    // The command "yii example/index city id" will call "actionIndex('city', 'id')"
    public function actionIndex($category, $order = 'name') { ... }

    // The command "yii example/add test" will call "actionAdd(['test'])"
    // The command "yii example/add test1,test2" will call "actionAdd(['test1', 'test2'])"
    public function actionAdd(array $name) { ... }
}

Код выхода

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

Чтобы ваша команда консоли возвращала код выхода, просто верните целое число в методе действия контроллера:

public function actionIndex()
{
    if (/* some problem */) {
        echo "A problem occurred!\n";
        return 1;
    }
    // do something
    return 0;
}

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

• Controller::EXIT_CODE_NORMAL со значением 0;
• Controller::EXIT_CODE_ERROR со значением 1.

Хорошо определять значимые константы для вашего контроллера, если у вас есть больше типов кодов ошибок.

Форматирование и цвета

Консоль Yii поддерживает форматированный вывод, который автоматически деградирует до неформатированного, если он не поддерживается терминалом, выполняющим команду.

Вывод форматированных строк прост. Вот как вывести некоторые жирные символы:

$this->stdout("Hello?\n", Console::BOLD);

Если вам нужно динамически создавать строку, объединяя несколько стилей, лучше использовать ansiFormat():

$name = $this->ansiFormat('Alex', Console::FG_YELLOW);
echo "Hello, my name is $name.";