tutorial-console.md 7.17 KB
Newer Older
1 2
Console applications
====================
3

4
> Note: This section is under development.
Qiang Xue committed
5

Larry Ullman committed
6 7
Yii has full featured support for console applications, whose structure is very similar to a Yii web application. A console application
consists of one or more [[yii\console\Controller]] classes, which are often referred to as "commands" in the console environment. Each controller can also have one or more actions, just like web controllers.
8 9 10 11

Usage
-----

Larry Ullman committed
12
You execute a console controller action using the following syntax:
13 14

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

Larry Ullman committed
18
For example, the [[yii\console\controllers\MigrateController::actionCreate()|MigrateController::actionCreate()]]
19
with [[yii\console\controllers\MigrateController::$migrationTable|MigrateController::$migrationTable]] set can
Larry Ullman committed
20
be called from command line like so:
21 22

```
kate-kate committed
23
yii migrate/create --migrationTable=my_migration
24 25
```

Larry Ullman committed
26
In the above `yii` is the console application entry script described below.
27

28 29 30
Entry script
------------

Carsten Brandt committed
31
The console application entry script is equivalent to the `index.php` bootstrap file used for the web application. The console entry script is typically called `yii`, and located in your application's root directory. The contents of the console application entry script contains
32 33 34 35 36 37 38 39 40
code like the following:

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

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

43
// fcgi doesn't have STDIN and STDOUT defined by default
44 45
defined('STDIN') or define('STDIN', fopen('php://stdin', 'r'));
defined('STDOUT') or define('STDOUT', fopen('php://stdout', 'w'));
46 47

require(__DIR__ . '/vendor/autoload.php');
Qiang Xue committed
48
require(__DIR__ . '/vendor/yiisoft/yii2/Yii.php');
49 50 51 52 53 54 55 56 57

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

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

```

Larry Ullman committed
58 59 60
This script will be created as part of your application; you're free to edit it to suit your needs. The `YII_DEBUG` constant can be set `false` if you do
not want to see a stack trace on error, and/or if you want to improve the overall performance. In both basic and advanced application
templates, the console application entry script has debugging enabled to provide a more developer-friendly environment.
61 62 63 64

Configuration
-------------

Larry Ullman committed
65 66
As can be seen in the code above, the console application uses its own configuration file, named `console.php`. In this file
you should configure various application components and properties for the console application in particular.
67

Larry Ullman committed
68 69
If your web application and the console application share a lot of configuration parameters and values, you may consider moving the common
parts into a separate file, and including this file in both of the application configurations (web and console). You can see an example of this in the "advanced" application template.
70 71 72

Sometimes, you may want to run a console command using an application configuration that is different from the one
specified in the entry script. For example, you may want to use the `yii migrate` command to upgrade your
Larry Ullman committed
73 74
test databases, which are configured in each individual test suite. To do change the configuration dynamically, simply specify a custom application configuration
file via the `appconfig` option when executing the command:
75 76 77 78

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

80 81
> **Note**: When using `*` in console don't forget to quote it as `"*"` in order to avoid executing it as a shell
> command.
82

83

84 85 86
Creating your own console commands
----------------------------------

87
### Console Controller and Action
88

89
A console command is defined as a controller class extending from [[yii\console\Controller]]. In the controller class,
Larry Ullman committed
90
you define one or more actions that correspond to sub-commands of the controller. Within each action, you write code that implements the appropriate tasks for that particular sub-command.
91

Larry Ullman committed
92 93
When running a command, you need to specify the route to the  controller action. For example,
the route `migrate/create` invokes the sub-command that corresponds to the
94
[[yii\console\controllers\MigrateController::actionCreate()|MigrateController::actionCreate()]] action method.
Larry Ullman committed
95
If a route offered during execution does not contain an action ID, the default action will be executed (as with a web controller).
96

97 98
### Options

99
By overriding the [[yii\console\Controller::options()]] method, you can specify options that are available
Larry Ullman committed
100
to a console command (controller/actionID). The method should return a list of the controller class's public properties.
101 102 103
When running a command, you may specify the value of an option using the syntax `--OptionName=OptionValue`.
This will assign `OptionValue` to the `OptionName` property of the controller class.

Larry Ullman committed
104 105
If the default value of an option is of an array type and you set this option while running the command,
the option value will be converted into an array by splitting the input string on any commas.
106

107 108 109 110
### Arguments

Besides options, a command can also receive arguments. The arguments will be passed as the parameters to the action
method corresponding to the requested sub-command. The first argument corresponds to the first parameter, the second
Larry Ullman committed
111 112
corresponds to the second, and so on. If not enough arguments are provided when the command is called, the corresponding parameters
will take the declared default values, if defined. If no default value is set, and no value is provided at runtime, the command will exit with an error.
113

Larry Ullman committed
114 115
You may use the `array` type hint to indicate that an argument should be treated as an array. The array will be generated
by splitting the input string on commas.
116 117 118 119 120 121

The follow examples show how to declare arguments:

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

125 126 127
    // 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') { ... }
128

129 130 131
    // 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) { ... }
132 133 134 135 136
}
```


### Exit Code
137

Larry Ullman committed
138 139 140 141
Using exit codes is a best practice for console application development. Conventionally, a command returns `0` to indicate that
everything is OK. If the command returns a number greater than zero, that's considered to be indicative of an error. The number returned will be the error
code, potentially usable to find out details about the error.
For example `1` could stand generally for an unknown error and all codes above would be reserved for specific cases: input errors, missing files, and so forth.
Carsten Brandt committed
142

Larry Ullman committed
143
To have your console command return an exit code, simply return an integer in the controller action
Carsten Brandt committed
144 145 146 147 148
method:

```php
public function actionIndex()
{
149 150 151 152 153 154
    if (/* some problem */) {
        echo "A problem occured!\n";
        return 1;
    }
    // do something
    return 0;
Carsten Brandt committed
155 156
}
```
157

158
There are some predefined constants you can use:
159

160 161
- `Controller::EXIT_CODE_NORMAL` with value of `0`;
- `Controller::EXIT_CODE_ERROR` with value of `1`.