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

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

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

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

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

Расширения Zii

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

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

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

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

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

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

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

Поведение

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

// $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',
        ),
    );
}

Виджет

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

Действие

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

Фильтры

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

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

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

Контроллер

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

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

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

Валидатор

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

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

Команда консоли

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

Модуль

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

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

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

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

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