diff --git a/docs/guide-ru/images/tutorial-console-help.png b/docs/guide-ru/images/tutorial-console-help.png new file mode 100644 index 0000000000..34812a6d90 Binary files /dev/null and b/docs/guide-ru/images/tutorial-console-help.png differ diff --git a/docs/guide-ru/tutorial-console.md b/docs/guide-ru/tutorial-console.md new file mode 100644 index 0000000000..75a1d01e61 --- /dev/null +++ b/docs/guide-ru/tutorial-console.md @@ -0,0 +1,212 @@ +Консольное приложение +===================== + +Кроме богатых возможностей для построеня веб приложений, 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). + + +Использование +------------- + +Вы можете запустить действие консольного контроллера, используя следующий синтаксис: + +``` +yii [--option1=value1 --option2=value2 ... argument1 argument2 ...] +``` + +В приведённом выше примере, `` относится к действию контроллера. Параметры будут подставляться в свойства +класса и в аргументы метода действия. + +Для примера, [[yii\console\controllers\MigrateController::actionUp()|MigrateController::actionUp()]] +с [[yii\console\controllers\MigrateController::$migrationTable|MigrateController::$migrationTable]] установкой `migrations` +и лимитом в 5 миграций может быть вызвано следующим образом: + +``` +yii migrate/up 5 --migrationTable=migrations +``` + +> **Примечание**: При использовании в консоли `*`, не забудте поместить её в кавычки `"*"` чтобы избежать её интерпретации +> и замены на все имена файлов в данной директории. + + +Входной скрипт +-------------- + +Входной скрипт консольного приложения - это подобие файла `index.php`, используемого в веб приложении. +Входной скрипт консоли, как правило, называется `yii` и располагается в основной директории приложения. +Он содержит код похожий на следующее: + +```php +#!/usr/bin/env php +run(); +exit($exitCode); +``` + +Этот скрипт будет создан как часть вашего приложения; вы можете его редактировать, если вам это необходимо. +`YII_DEBUG` можете установить в `false` если вам не нужно видеть отладочный вывод при ошибке, и/или если вы хотите +улучшить общую производительность. В обоих шаблонах приложения, во входном скрипте приложения отладка включена по +умолчанию для обеспечения более дружественного к разработчику окружения. + + +Настройка +--------- + +Как видно из приведённого выше кода, консольное приложение использует свой собственный файл конфигурации, названый `console.php`. +В этом файле вы должны произвести настройку различных [компонентов приложения](structure-application-components.md) и +свойств консольного приложения. + +Если ваше веб и консольное приложение имеет много общих параметров конфигурации, вы можете выделить общую часть в +отдельный файл, и включить его в оба файла конфигурации (веб и консоль). +Вы можете посмотреть пример в "продвинутом" шаблоне проекта. + +> Подсказка: Иногда, вам может потребоваться запустить консольную команду используя конфигурацию, отличную от той, что +> указано во входном скрипте. Для примера, вы можете использовать команду `yii migrate` для обновления тестовой +> базы данных, которая настраивается для каждого отдельного набора тестов. Для изменения файла конфигурации, +> просто укажите свой конфигурационный файл через опцию `appconfig` при запуске команды: +> +> ``` +> yii --appconfig=path/to/config.php ... +> ``` + + +Создание ваших собственных комманд +---------------------------------- + +### Консолный контроллер и действие + +Консольная команда определяется как класс контроллера расширяющий [[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."; +```