エクステンションを使う

エクステンションを使うには、通常、次の3つのステップが必要です:

Yii の extension repository より、エクステンションをダウンロードします。
エクステンションをアプリケーションベースディレクトリのサブディレクトリである extensions/xyz 以下に解凍します。ここで、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' エクステンションに属している場合、ビュー中で下記のようにして使用できます。

// 本文 (body content) を必要としないウィジェット
<?php $this->widget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>
 
// 本文 (body content) を含められるウィジェット
<?php $this->beginWidget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>
 
...ウィジェットの本文 (body content) ...
 
<?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',
        ),
        // 他のコマンド
    ),
);

こうすると、追加コマンド xyz を備えている yiic ツールを使用できるようになります。

注意: コンソールアプリケーションは、通常、ウェブアプリケーションで使用されるものとは異なる初期構成ファイルを使用します。アプリケーションを yiic webapp コマンドを使用して作成した場合、コンソールアプリケーション protected/yiic 用の初期構成ファイルは protected/config/console.php、また、ウェブアプリケーション用の初期構成ファイルは protected/config/main.php です。

モジュール

モジュールの使用方法については、モジュールに関する章を参照してください。

一般的なコンポーネント

一般的なコンポーネントを使用するには、はじめに、下記のようにそのクラスファイルをインクルードする必要があります。

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

こうすると、クラスのインスタンスの生成やプロパティの設定、メソッドのコールを行えます。それを継承して新しい子クラスを作成することも可能です。

$Id$

The Definitive Guide to Yii