Console Applications

Console applications are mainly used by a Web application to perform offline work, such as code generation, search index compiling, email sending, etc. Yii provides a framework for writing console applications in an object-oriented and systematic way.

Yii represents each console task in terms of a command, and a console application instance is used to dispatch a command line request to an appropriate command. The application instance is created in an entry script. To execute a console task, we simply run the corresponding command on the command line as follows,

php entryScript.php CommandName Param0 Param1 ...

where CommandName refers to the command name which is case-insensitive, and Param0, Param1 and so on are parameters to be passed to the command instance.

The entry script for a console application is usually written like the following, similar to that in a Web application,

defined('YII_DEBUG') or define('YII_DEBUG',true);
// include Yii bootstrap file
require_once('path/to/yii/framework/yii.php');
// create application instance and run
$configFile='path/to/config/file.php';
Yii::createConsoleApplication($configFile)->run();

We then create command classes which should extend from CConsoleCommand. Each command class should be named as its command name appended with Command. For example, to define an email command, we should write an EmailCommand class. All command class files should be placed under the commands subdirectory of the application base directory.

Tip: By configuring CConsoleApplication::commandMap, one can also have command classes in different naming conventions and located in different directories.

Writing a command class mainly involves implementing the CConsoleCommand::run method. Command line parameters are passed as an array to this method. Below is an example:

class EmailCommand extends CConsoleCommand
{
    public function run($args)
    {
        $receiver=$args[0];
        // send email to $receiver
    }
}

At any time in a command, we can access the console application instance via Yii::app(). Like a Web application instance, console application can also be configured. For example, we can configure a db application component to access the database. The configuration is usually specified as a PHP file and passed to the constructor of the console application class (or createConsoleApplication in the entry script).

1. Using the yiic Tool ¶

We have used the yiic tool to create our first application. The yiic tool is in fact implemented as a console application whose entry script file is framework/yiic.php. Using yiic, we can accomplish tasks such as creating a Web application skeleton, generating a controller class or model class, generating code needed by CRUD operations, extracting messages to be translated, etc.

We can enhance yiic by adding our own customized commands. To do so, we should start with a skeleton application created using yiic webapp command, as described in Creating First Yii Application. The yiic webapp command will generate two files under the protected directory: yiic and yiic.bat. They are the local version of the yiic tool created specifically for the Web application.

We can then create our own commands under the protected/commands directory. Running the local yiic tool, we will see that our own commands appearing together with the standard ones. We can also create our own commands to be used when yiic shell is used. To do so, just drop our command class files under the protected/commands/shell directory.