Використання розширень

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

Завантажити розширення з репозиторію Yii;
Розпакувати розширення в підпапку extensions/xyz базової директорії додатка, де xyz — імʼя розширення;
Підключити, налаштувати і використовувати розширення.

Кожне розширення унікально ідентифікується по імені. Якщо розширення називається 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 // or 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');

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

The Definitive Guide to Yii