Использование расширений

Порядок использования расширений, как правило, включает три шага:

1. Скачать расширение из репозитория Yii;
2. Распаковать расширение в подпапку extensions/xyz базовой директории приложения, где xyz - имя расширения;
3. Подключить, настроить и использовать расширение.

Каждое расширение уникально идентифицируется по имени. Если расширение называется xyz, то, используя псевдоним пути ext.xyz, мы всегда можем определить папку, в которой хранятся файлы данного расширения.

Примечание: Псевдоним ext доступен с версии 1.0.8. Ранее мы должны были использовать псевдоним application.extensions для обращения к директории, содержащей все расширения. В дальнейшем, мы предполагаем, что определен псевдоним ext. Поэтому, если Вы используете версию 1.0.7 или ниже, Вы должны заменить ext на application.extensions.

Разные расширения предъявляют разные требования к импорту, настройке и порядку использования. Ниже, мы приведем несколько общих вариантов использования расширений согласно классификации, представленной в обзоре.

1. Компонент приложения ¶

Для использования компонента приложения в первую очередь необходимо изменить конфигурацию приложения, добавив новый элемент в свойство components:

return array(
    // 'preload'=>array('xyz',...),
    'components'=>array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzClass',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
        // прочие настройки компонентов
    ),
);

Теперь можно обращаться к компоненту в любом месте приложения через Yii::app()->xyz. Компонент будет создан отложенно (т.е. в момент первого обращения), если, конечно, мы не укажем его в свойстве preload.

2. Поведение ¶

Поведение может быть использовано в любом компоненте. Делается это в два шага: присоединение к компоненту и вызов метода поведения из компонента. К примеру:

// $name соответствует уникальному поведению компонента
$component->attachBehavior($name,$behavior);
// test() является методом $behavior
$component->test();

Чаще всего поведение присоединяется к компоненту с использованием конфигурации, а не вызовом метода attachBehavior. К примеру, чтобы присоединить поведение к компоненту приложения, мы можем использовать следующую конфигурацию:

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

Приведённый выше код присоединяет поведение xyz к компоненту приложения db. Это возможно так как CApplicationComponent определяет свойство behaviors. При инициализации компонент присоединит перечисленные в нём поведения.

Для классов CController, CFormModel и CActiveModel, которые необходимо расширять, присоединение поведений присходит при помощи переопределения метода behaviors(). К примеру:

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

3. Виджет ¶

Виджеты в основном используются в представлениях. Виджетом класса XyzClass расширения xyz, можно воспользоваться в представлении следующим образом:

// виджет без внутреннего содержимого
<?php $this->widget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>
 
// виджет, который может иметь внутреннее содержимое
<?php $this->beginWidget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>
 
...содержимое виджета...
 
<?php $this->endWidget(); ?>

4. Действие ¶

Действия используются в контроллерах для обработки запросов пользователя. Действие класса XyzClass расширения xyz можно использовать путем переопределения метода CController::actions класса нашего контроллера:

class TestController extends CController
{
    public function actions()
    {
        return array(
            'xyz'=>array(
                'class'=>'ext.xyz.XyzClass',
                'property1'=>'value1',
                'property2'=>'value2',
            ),
            // прочие действия
        );
    }
}

Теперь к действию можно обратиться по маршруту test/xyz.

5. Фильтры ¶

Фильтры также используются в контроллерах. В основном они используются в действиях для осуществления пред- и пост-обработки пользовательского запроса. Фильтр класса XyzClass расширения xyz можно использовать путем переопределения метода CController::filters в нашем классе контроллера:

class TestController extends CController
{
    public function filters()
    {
        return array(
            array(
                'ext.xyz.XyzClass',
                'property1'=>'value1',
                'property2'=>'value2',
            ),
            // прочие фильтры
        );
    }
}

Выше мы можем использовать операторы '+' и '-' в первом элементе массива для применения фильтра только к определенным действия. Подробнее ознакомиться можно в документации к CController.

6. Контроллер ¶

Контроллер предоставляет набор действий, которые могут быть запрошены пользователем. Для использования расширения контроллера необходимо настроить свойство CWebApplication::controllerMap в конфигурации приложения:

return array(
    'controllerMap'=>array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzClass',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
        // прочие контроллеры
    ),
);

Теперь к действию a контроллера можно обратиться через маршрут xyz/a.

7. Валидатор ¶

Валидатор применяется в классе модели (наследующего либо CFormModel или CActiveRecord). Класс валидатора XyzClass расширения xyz используется путем переопределения метода CModel::rules в нашем классе модели:

class MyModel extends CActiveRecord // or CFormModel
{
    public function rules()
    {
        return array(
            array(
                'attr1, attr2',
                'ext.xyz.XyzClass',
                'property1'=>'value1',
                'property2'=>'value2',
            ),
            // прочие правила проверки
        );
    }
}

8. Команда консоли ¶

Расширение консольной команды, как правило, используется для добавления новой команды в утилите yiic. Консольную команду XyzClass расширения xyz можно использовать, настроив конфигурацию консольного приложения:

return array(
    'commandMap'=>array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzClass',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
        // прочие команды
    ),
);

Теперь в утилите yiic добавилась еще одна команда xyz.

Примечание: Консольное приложение, как правило, использует иной файл конфигурации нежели веб-приложение. Если приложение было создано командой консоли yiic webapp, то конфигурационный файл для консоли protected/yiic находится в protected/config/console.php, а конфигурация веб-приложения - в protected/config/main.php.

9. Модуль ¶

Информация о порядке использования и создания модулей представлена в разделе Модуль.

10. Компонент общего вида ¶

Чтобы использовать компонент общего вида, нужно для начала включить его класс:

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

Теперь мы можем создавать экземпляр этого класса, настроить его свойства, вызывать его методы. Кроме того, можно его расширить для создания дочерних классов.