console.md 6.3 KB
Newer Older
1 2
Console applications
====================
3

4
Yii has full featured support of console. Console application structure in Yii is very similar to web application. It
5
consists of one or more [[yii\console\Controller]] (often referred to as commands). Each has one or more actions.
6 7 8 9

Usage
-----

10
You can execute controller action using the following syntax:
11 12

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

16 17 18
For example, [[yii\console\controllers\MigrateController::actionCreate()|MigrateController::actionCreate()]]
with [[yii\console\controllers\MigrateController::$migrationTable|MigrateController::$migrationTable]] set can
be called from command line like the following:
19 20

```
kate-kate committed
21
yii migrate/create --migrationTable=my_migration
22 23
```

24 25
In the above `yii` is console application entry script described below.

26 27 28
Entry script
------------

29 30 31 32 33 34 35 36 37 38 39 40 41 42
Console application entry script is typically called `yii`, located in your application root directory and contains
code like the following:

```php
#!/usr/bin/env php
<?php
/**
 * Yii console bootstrap file.
 *
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

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

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

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

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

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

```

60
This script is a part of your application so you're free to adjust it. The `YII_DEBUG` constant can be set `false` if you do
61
not want to see stack trace on error and want to improve overall performance. In both basic and advanced application
62
templates it is enabled to provide more developer-friendly environment.
63 64 65 66

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

67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
As can be seen in the code above, console application uses its own config files named `console.php`. In this file,
you should specify how to configure various application components and properties.

If your Web application and the console application share a lot of configurations, you may consider moving the common
part into a separate file, and include this file in both of the application configurations, just as what is done
in the "advanced" application template.

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
test databases which are configured in each individual test suite. To do so, simply specify the custom application configuration
file via the `appconfig` option, like the following,

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


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

87
### Console Controller and Action
88

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

93
When running a command, you need to specify the route to the corresponding controller action. For example,
94 95
the route `migrate/create` specifies the sub-command corresponding to the
[[yii\console\controllers\MigrateController::actionCreate()|MigrateController::actionCreate()]] action method.
96
If a route does not contain an action ID, the default action will be executed.
97

98 99
### Options

100
By overriding the [[yii\console\Controller::options()]] method, you can specify options that are available
101
to a console command (controller/actionID). The method should return a list of public property names of the controller class.
102 103 104
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.

105 106 107
If the default value of an option is of array type, then if you set this option while running the command,
the option value will be converted into an array by splitting the input string by commas.

108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
### 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
corresponds to the second, and so on. If there are not enough arguments are provided, the corresponding parameters
may take the declared default values, or if they do not have default value the command will exit with an error.

You may use `array` type hint to indicate that an argument should be treated as an array. The array will be generated
by splitting the input string by commas.

The follow examples show how to declare arguments:

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

	// 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') { ... }

	// 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) { ... }
}
```


### Exit Code
138

Carsten Brandt committed
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
Using exit codes is the best practice of console application development. If a command returns `0` it means
everything is OK. If it is a number greater than zero, we have an error and the number returned is the error
code that may be interpreted to find out details about the error.
For example `1` could stand generally for an unknown error and all codes above are declared for specific cases
such as input errors, missing files, and so forth.

To have your console command return with an exit code you simply return an integer in the controller action
method:

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