Using Extensions

Using an extension usually involves the following three steps:

1. Download the extension from Yii's extension repository.
2. Unpack the extension under the extensions/xyz subdirectory of application base directory, where xyz is the name of the extension.
3. Import, configure and use the extension.

Each extension has a name that uniquely identifies it among all extensions. Given an extension named as xyz, we can always use the path alias ext.xyz to locate its base directory which contains all files of xyz.

Note: The root path alias ext has been available since version 1.0.8. Previously, we would need to use application.extensions to refer to the directory containing all extensions. In the following description, we assume ext is defined. You will need to replace it with application.extensions if you are using version 1.0.7 or lower.

Different extensions have different requirements about importing, configuration and usage. In the following, we summarize common usage scenarios about extensions, according to their categorization described in the overview.

1. Application Component ¶

To use an application component, we first need to change the application configuration by adding a new entry to its components property, like the following:

return array(
    // 'preload'=>array('xyz',...),
    'components'=>array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzClass',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
        // other component configurations
    ),
);

Then, we can access the component at any place using Yii::app()->xyz. The component will be lazily created (that is, created when it is accessed for the first time) unless we list it the preload property.

2. Behavior ¶

Behavior can be used in all sorts of components. Its usage involves two steps. In the first step, a behavior is attached to a target component. In the second step, a behavior method is called via the target component. For example:

// $name uniquely identifies the behavior in the component
$component->attachBehavior($name,$behavior);
// test() is a method of $behavior
$component->test();

More often, a behavior is attached to a component using a configurative way instead of calling the attachBehavior method. For example, to attach a behavior to an application component, we could use the following application configuration:

return array(
    'components'=>array(
        'db'=>array(
            'class'=>'CDbConnection',
            'behaviors'=>array(
                'xyz'=>array(
                    'class'=>'ext.xyz.XyzBehavior',
                    'property1'=>'value1',
                    'property2'=>'value2',
                ),
            ),
        ),
        //....
    ),
);

The above code attaches the xyz behavior to the db application component. We can do so because CApplicationComponent defines a property named behaviors. By setting this property with a list of behavior configurations, the component will attach the corresponding behaviors when it is being initialized.

For CController, CFormModel and CActiveModel classes which usually need to be extended, attaching behaviors is done by overriding their behaviors() method. For example,

public function behaviors()
{
    return array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzBehavior',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
    );
}

3. Widget ¶

Widgets are mainly used in views. Given a widget class XyzClass belonging to the xyz extension, we can use it in a view as follows,

// widget that does not need body content
<?php $this->widget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>
 
// widget that can contain body content
<?php $this->beginWidget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>
 
...body content of the widget...
 
<?php $this->endWidget(); ?>

4. Action ¶

Actions are used by a controller to respond specific user requests. Given an action class XyzClass belonging to the xyz extension, we can use it by overriding the CController::actions method in our controller class:

class TestController extends CController
{
    public function actions()
    {
        return array(
            'xyz'=>array(
                'class'=>'ext.xyz.XyzClass',
                'property1'=>'value1',
                'property2'=>'value2',
            ),
            // other actions
        );
    }
}

Then, the action can be accessed via route test/xyz.

5. Filter ¶

Filters are also used by a controller. Their mainly pre- and post-process the user request when it is handled by an action. Given a filter class XyzClass belonging to the xyz extension, we can use it by overriding the CController::filters method in our controller class:

class TestController extends CController
{
    public function filters()
    {
        return array(
            array(
                'ext.xyz.XyzClass',
                'property1'=>'value1',
                'property2'=>'value2',
            ),
            // other filters
        );
    }
}

In the above, we can use plus and minus operators in the first array element to apply the filter to limited actions only. For more details, please refer to the documentation of CController.

6. Controller ¶

A controller provides a set of actions that can be requested by users. In order to use a controller extension, we need to configure the CWebApplication::controllerMap property in the application configuration:

return array(
    'controllerMap'=>array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzClass',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
        // other controllers
    ),
);

Then, an action a in the controller can be accessed via route xyz/a.

7. Validator ¶

A validator is mainly used in a model class (one that extends from either CFormModel or CActiveRecord). Given a validator class XyzClass belonging to the xyz extension, we can use it by overriding the CModel::rules method in our model class:

class MyModel extends CActiveRecord // or CFormModel
{
    public function rules()
    {
        return array(
            array(
                'attr1, attr2',
                'ext.xyz.XyzClass',
                'property1'=>'value1',
                'property2'=>'value2',
            ),
            // other validation rules
        );
    }
}

8. Console Command ¶

A console command extension usually enhances the yiic tool with an additional command. Given a console command XyzClass belonging to the xyz extension, we can use it by configuring the configuration for the console application:

return array(
    'commandMap'=>array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzClass',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
        // other commands
    ),
);

Then, we can use the yiic tool is equipped with an additional command xyz.

Note: A console application usually uses a configuration file that is different from the one used by a Web application. If an application is created using yiic webapp command, then the configuration file for the console application protected/yiic is protected/config/console.php, while the configuration file for the Web application is protected/config/main.php.

9. Module ¶

Please refer to the section about modules on how to use a module.

10. Generic Component ¶

To use a generic component, we first need to include its class file by using

Yii::import('ext.xyz.XyzClass');

Then, we can either create an instance of the class, configure its properties, and call its methods. We may also extend it to create new child classes.