エクステンションを使う

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

1. Yii の extension repository より、エクステンションをダウンロードします。
2. エクステンションを アプリケーションベースディレクトリ のサブディレクトリである extensions/xyz 以下に解凍します。 ここで、xyz にはエクステンション名が入ります。
3. インポート、初期構成を行い、エクステンションを使用します。

各エクステンションは全てのエクステンション中でそれを特定するためのユニークな名前を持ちます。 エクステンション名が xyz であると仮定した場合、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' エクステンションに属している場合、ビュー中で下記のようにして使用できます。

// 本文 (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(); ?>

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 // または 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',
        ),
        // 他のコマンド
    ),
);

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

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

10. モジュール ¶

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

11. 一般的なコンポーネント ¶

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

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

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