Ru translation code style docs [ci skip]

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).
+
+
+Использование <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);
+
+// fcgi doesn't have STDIN and STDOUT defined by default
+defined('STDIN') or define('STDIN', fopen('php://stdin', 'r'));
+defined('STDOUT') or define('STDOUT', fopen('php://stdout', 'w'));
+
+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.";
+```