miramir
9 years ago
2 changed files with 212 additions and 0 deletions
After Width: | Height: | Size: 150 KiB |
@ -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."; |
||||
``` |
Loading…
Reference in new issue