Консольное приложение
=====================

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

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

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

![Запуск команды ./yii для вывода помощи](images/tutorial-console-help.png)

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

- [[yii\console\controllers\AssetController|AssetController]] - Позволяет вам объединять и сжимать ваши JavaScript и CSS файлы.
  Больше об этой команде вы можете узнать в [Assets Section](structure-assets.md#using-the-asset-command).
- [[yii\console\controllers\CacheController|CacheController]] - Позволяет вам сбрасывать кеш приложения.
- [[yii\console\controllers\FixtureController|FixtureController]] - Управляет загрузкой и выгрузкой данных фикстур для тестирования.
  Данная команда более подробно описана в [Testing Section about Fixtures](test-fixtures.md#managing-fixtures).
- [[yii\console\controllers\HelpController|HelpController]] - Обеспечивает справочную информацию о консольных командах,
  это команда по умолчанию и она печатает текст, который вы видели выше.
- [[yii\console\controllers\MessageController|MessageController]] - Извлекает сообщения для перевода из файлов с исходными тестами.
  Больше об этой команде вы можете узнать в [I18N Section](tutorial-i18n.md#message-command).
- [[yii\console\controllers\MigrateController|MigrateController]] - Управление миграциями приложения.
  Миграции базы данных более детально описаны в [Database Migration Section](db-migrations.md).


Использование <span id="usage"></span>
-------------

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

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

В приведённом выше примере, `<route>` относится к действию контроллера. Параметры будут подставляться в свойства
класса и в аргументы метода действия.

Для примера, [[yii\console\controllers\MigrateController::actionUp()|MigrateController::actionUp()]]
с [[yii\console\controllers\MigrateController::$migrationTable|MigrateController::$migrationTable]] установкой `migrations`
и лимитом в 5 миграций может быть вызвано следующим образом:

```
yii migrate/up 5 --migrationTable=migrations
```

> **Примечание**: При использовании в консоли `*`, не забудьте поместить её в кавычки `"*"` чтобы избежать её интерпретации 
> и замены на все имена файлов в данной директории.


Входной скрипт <span id="entry-script"></span>
--------------

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

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

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

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` если вам не нужно видеть отладочный вывод при ошибке, и/или если вы хотите
улучшить общую производительность. В обоих шаблонах приложения, во входном скрипте приложения отладка включена по
умолчанию для обеспечения более дружественного к разработчику окружения.


Настройка <span id="configuration"></span>
---------

Как видно из приведённого выше кода, консольное приложение использует свой собственный файл конфигурации, названый `console.php`.
В этом файле вы должны произвести настройку различных [компонентов приложения](structure-application-components.md) и
свойств консольного приложения.

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

> Подсказка: Иногда, вам может потребоваться запустить консольную команду используя конфигурацию, отличную от той, что
> указано во входном скрипте. Для примера, вы можете использовать команду `yii migrate` для обновления тестовой
> базы данных, которая настраивается для каждого отдельного набора тестов. Для изменения файла конфигурации,
> просто укажите свой конфигурационный файл через опцию `appconfig` при запуске команды:
> 
> ```
> yii <route> --appconfig=path/to/config.php ...
> ```


Создание ваших собственных команд <span id="create-command"></span>
----------------------------------

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

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

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

### Опции

Для переопределения [[yii\console\Controller::options()]] метода, вы можете указать опции, которые доступны в консольной
команде (controller/actionID). Метод должен возвращать список публичных атрибутов класса. При запуске команды вы
можете указать значение опций, используя синтаксис `--OptionName=OptionValue`. Это свяжет `OptionValue` с атрибутом
`OptionName` класса контроллера.

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

### Аргументы

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

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

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

```php
class ExampleController extends \yii\console\Controller
{
    // Команда "yii example/create test" вызовет "actionCreate('test')"
    public function actionCreate($name) { ... }

    // Команда "yii example/index city" вызовет "actionIndex('city', 'name')"
    // Команда "yii example/index city id" вызовет "actionIndex('city', 'id')"
    public function actionIndex($category, $order = 'name') { ... }

    // Команда "yii example/add test" вызовет "actionAdd(['test'])"
    // Команда "yii example/add test1,test2" вызовет "actionAdd(['test1', 'test2'])"
    public function actionAdd(array $name) { ... }
}
```


### Код возврата

При разработке консольного приложения принято использовать код возврата. Принято, код `0` означает, что команда выполнилась
удачно. Если команда вернула код больше нуля, то это говорит об ошибке. Номер, который был возвращён при ошибке,
потенциально может быть использован для поиска более детальной информации о ошибке.
Для примера `1` может указывать на неизвестную ошибку, а все коды выше могут быть зарезервированы под специфичные
ошибки: ошибки ввода, повреждённые файлы, и что-то другое.

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

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

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

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

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

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

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

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

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

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

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