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

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

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

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

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

1. Расширения Zii ¶

Перед тем, как рассказать о использовании сторонних расширений, стоит упомянуть библиотеку расширений Zii — набор расширений, разрабатываемый командой Yii и включаемой в каждую новую версию.

При использовании расширения Zii, необходимо обращаться к соответствующим классам используя псевдоним пути вида zii.path.to.ClassName. Здесь zii — предопределённый в Yii маршрут, соответствующий корневой директории библиотеки Zii. К примеру, чтобы использовать CGridView, необходимо использовать в шаблоне представления следующий код:

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

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

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

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

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

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

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

// $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 и CActiveRecord, которые необходимо расширять, присоединение поведений присходит при помощи переопределения метода behaviors(). При инициализации, классы автоматически присоединят поведения, объявленные в данном методе. К примеру:

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

4. Виджет ¶

Виджеты в основном используются в представлениях. Виджетом класса 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(); ?>

5. Действие ¶

Действия используются в контроллерах для обработки запросов пользователя. Действие класса 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.

6. Фильтры ¶

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

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

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

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

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

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

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

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

Валидатор применяется в классе модели (наследующего либо 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',
            ),
            // прочие правила проверки
        );
    }
}

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

Расширение консольной команды, как правило, используется для добавления новой команды в утилите 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.

10. Модуль ¶

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

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

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

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

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