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.

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. Zii Extensions ¶

Before we start describing the usage of third-party extensions, we would like to introduce the Zii extension library, which is a set of extensions developed by the Yii developer team and included in every release.

When using a Zii extension, one must refer to the corresponding class using a path alias in the form of zii.path.to.ClassName. Here the root alias zii is predefined by Yii. It refers to the root directory of the Zii library. For example, to use CGridView, we would use the following code in a view script when referring to the extension:

$this->widget('zii.widgets.grid.CGridView', array(
    'dataProvider'=>$dataProvider,
));

2. 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.

3. 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 CActiveRecord classes which usually need to be extended, attaching behaviors can be done by overriding their behaviors() method. The classes will automatically attach any behaviors declared in this method during initialization. For example,

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

4. 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(); ?>

5. 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.

6. Filter ¶

Filters are also used by a controller. They 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.

7. 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.

8. 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
        );
    }
}

9. 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.

10. Module ¶

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

11. 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.