@@ -26,7 +26,7 @@ In the above `yii` is the console application entry script described below.
Entry script
------------
Console application entry script is typically called `yii`, located in your application root directory and contains
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 is located in your application's root directory (e.g., `protected`). The contents of the console application entry script contains
code like the following:
```php
...
...
@@ -57,24 +57,23 @@ exit($exitCode);
```
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
not want to see stack trace on error and want to improve overall performance. In both basic and advanced application
templates it is enabled to provide more developer-friendly environment.
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.
Configuration
-------------
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.
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.
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.
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.
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,
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:
```
yii <route> --appconfig=path/to/config.php ...
...
...
@@ -87,33 +86,32 @@ Creating your own console commands
### Console Controller and Action
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.
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.
When running a command, you need to specify the route to the corresponding controller action. For example,
the route `migrate/create`specifies the sub-command corresponding to the
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
If a route does not contain an action ID, the default action will be executed.
If a route offered during execution does not contain an action ID, the default action will be executed (as with a web controller).
### Options
By overriding the [[yii\console\Controller::options()]] method, you can specify options that are available
to a console command (controller/actionID). The method should return a list of public property names of the controller class.
to a console command (controller/actionID). The method should return a list of the controller class's public properties.
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.
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.
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.
### 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.
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.
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.
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.
The follow examples show how to declare arguments:
...
...
@@ -136,13 +134,12 @@ class ExampleController extends \yii\console\Controller
### Exit Code
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.
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.
To have your console command return with an exit code you simply return an integer in the controller action
To have your console command return an exit code, simply return an integer in the controller action
