エクステンションの作成

エクステンションは第三者の開発者によって使われるはずのものなので、作るためにはさらにいくらかの努力を必要とします。次に示すのは一般的なガイドラインです。

エクステンションは自己充足的でなければなりません。つまり外部の依存は最小限でなければなりません。エクステンションがさらなるパッケージ、クラスまたはリソースファイルのインストールを必要とするならば、それはユーザの頭痛となるでしょう。
エクステンションに属しているファイルは、エクステンション名を名前とする同じディレクトリの下で組織される必要があります。
エクステンションのクラスは、他のエクステンションのクラスとの競合を避けるために、何文字かの識別子を名前の前に置かれなければなりません。
エクステンションには、コードと合せて詳細なインストールと API のドキュメンテーションを付けるべきです。これにより、他の開発者がエクステンションを使う際に必要な時間と努力を減らします。
エクステンションは、適当なライセンスを持っていなければなりません。オープンソースとクローズドソースプロジェクトの両方にエクステンションを使って貰いたければ BSD, MIT, その他のようなライセンスを考慮したほうが良いでしょう。 GPL ではありません。なぜなら GPL はその派生コードに同様にオープンソースであることを要求するためです。

以下に、概要で解説される分類により、新しいエクステンションを作成する方法を解説します。主として自分自身のプロジェクトで使うコンポーネントを作成するときも、これらの説明があてはまります。

アプリケーションコンポーネント

アプリケーションコンポーネントは IApplicationComponent インタフェースを実装するかまたは CApplicationComponent を継承しなければなりません。実装する必要があるメインのメソッドは IApplicationComponent::init であり、そこでコンポーネントの何らかの初期化処理を行います。このメソッドは、コンポーネントが生成され、アプリケーション初期構成で規定されるプロパティの初期値が適用された後に呼び出されます。

デフォルトでは、アプリケーションコンポーネントは、リクエスト処理中に最初にアクセスされるときに生成され、初期化されます。もしアプリケーションインスタンスが生成された直後にアプリケーションコンポーネントが生成される必要があるならば、ユーザはその ID を CApplication::preload プロパティに記述しておかなければなりません。

ビヘイビア

ビヘイビアを作成するためには、IBehavior インタフェースを実装しなければなりません。便利なように、Yii は CBehavior という基本クラスを提供して、その中で既にこのインタフェースといくつかの便利なメソッドを実装しています。これを継承する子クラスでは、主として、アタッチされるコンポーネントに対して提供しようとする追加のメソッドを実装することが必要になります。

CModel および CActiveRecord のためのビヘイビアを開発する場合も、それぞれ CModelBehavior および CActiveRecordBehavior を継承元にすることが可能です。これらの基本クラスは、CModel や CActiveRecord のために特に作られた追加の機能を提供してくれます。例えば、CActiveRecordBehavior クラスは、アクティブレコードオブジェクトのライフサイクルにおいて生成されるイベントに応答する一連のメソッドを実装しています。従って、子クラスでは、これらのメソッドをオーバーライドして、AR のライフサイクルに関与するカスタマイズされたコードを格納することが出来ます。

下記のコードはアクティブレコードのビヘイビアの例を示しています。このビヘイビアが AR オブジェクトにアタッチされると、save() が呼ばれて AR オブジェクトが保存されるときに、自動的に create_time と update_time の属性に現在のタイムスタンプが設定されます。

class TimestampBehavior extends CActiveRecordBehavior
{
    public function beforeSave($event)
    {
        if($this->owner->isNewRecord)
            $this->owner->create_time=time();
        else
            $this->owner->update_time=time();
    }
}

ウィジェット

ウィジェットは CWidget またはその子クラスを継承すべきものです。

新しいウィジェットを作成する最も簡単な方法は、既存のウィジェットを継承し、そのメソッドをオーバライドするか、またはそのデフォルトプロパティ値を変更することです。たとえば、より素晴らしい CSS スタイルを CTabView に適用したい場合、ウィジェットを使用する際にその CTabView::cssFile プロパティを構成することもできます。しかし、以下のように CTabView を継承すれば、ウィジェットを使う時にプロパティを構成しなくても済むようになります。

class MyTabView extends CTabView
{
    public function init()
    {
        if($this->cssFile===null)
        {
            $file=dirname(__FILE__).DIRECTORY_SEPARATOR.'tabview.css';
            $this->cssFile=Yii::app()->getAssetManager()->publish($file);
        }
        parent::init();
    }
}

上記においては、CWidget::init メソッドをオーバライドして、プロパティがセットされてなければ新しいデフォルト CSS スタイルの URL を CTabView::cssFile に割り当てています。この新しい CSS スタイルファイルは、エクステンションとしてまとめられるように、MyTabView クラスファイルを含む同じディレクトリの下に置いています。この CSS スタイルファイルはウェブアクセスできないので、アセットとして公開する必要があります。

ゼロから新しいウィジェットを作製するためには、主に CWidget::init と CWidget::run の二つのメソッドを実装する必要があります。ウィジェットをビューに挿入するために $this->beginWidget を使うときに、第一のメソッドが呼ばれ、$this->endWidget を呼ぶときに、第二のメソッドが呼ばれます。これらの二つのメソッドの間で表示される内容を捕えて処理したい場合には、CWidget::init の中で出力バッファリングを開始し、CWidget::run の中でバッファされた出力を取り出して追加の処理を行います。

ウィジェットは、しばしば、CSS, JavaScript または他のリソースファイルをウィジェットを使うページに含むことが必要です。これらのファイルはウィジェットクラスファイルと共にいて、通常はウェブユーザからアクセスできないので、アセット (資産) と呼ばれます。これらのファイルにウェブアクセスできるようにするため、上記のコード断片で示すように、CWebApplication::assetManager を用いて公開する必要があります。この他、CSS または JavaScript ファイルを現在のページに含めたいならば、CClientScript を用いてそれを登録する必要があります。

class MyWidget extends CWidget
{
    protected function registerClientScript()
    {
        // ...CSS または JavaScript ファイルをここで公開...
        $cs=Yii::app()->clientScript;
        $cs->registerCssFile($cssFile);
        $cs->registerScriptFile($jsFile);
    }
}

ウィジェットは、それ自身のビューファイルも持つことが出来ます。もしそうならば、ウィジェットクラスファイルを含んでいるディレクトリの下に views という名のディレクトリをつくり、すべてのビューファイルをそこに置いてください。ウィジェットクラスでは、ウィジェットの表示を行うために $this->render('ViewName') を用いてください。これはコントローラでビューを表示するのと同じ方法です。

アクション

アクションは CAction またはその子クラスから継承されるべきです。アクションとして主に実装されるべきメソッドは IAction::run です。

フィルタ

フィルタは CFilter またはその子クラスから継承されるべきです。フィルタとして主に実装されるべきメソッドは CFilter::preFilter と CFilter::postFilter です。前者はアクションが実行される前に呼び出され、後者はアクションの実行後に呼び出されます。

class MyFilter extends CFilter
{
    protected function preFilter($filterChain)
    {
        // アクションが実行される前に行われるロジック
        return true; // アクションが実行されるべきでない場合は偽
    }
 
    protected function postFilter($filterChain)
    {
        // アクションが実行された後に行われるロジック
    }
}

$filterChain パラメータは CFilterChain タイプで、現在フィルタされているアクションの情報を含みます。

コントローラ

エクステンションとして配布されるコントローラは CController の継承ではなく CExtController を継承するべきです。主な理由は、CController はビューファイルが application.views.ControllerID の下に存在するのに対し、CExtController はビューファイルが、コントローラクラスファイルを含むディレクトリのサブディレクトリである views ディレクトリに存在すると仮定するからです。その結果、ビューファイルがコントローラクラスファイルと共に存在するため、コントローラを再配布するが一層容易になます。

バリデータ

バリデータは CValidator を継承し、CValidator::validateAttribute メソッドを実装するべきです。

class MyValidator extends CValidator
{
    protected function validateAttribute($model,$attribute)
    {
        $value=$model->$attribute;
        if($value has error)
            $model->addError($attribute,$errorMessage);
    }
}

コンソールコマンド

コンソールコマンドは CConsoleCommand を継承し、CConsoleCommand::run メソッドを実装するべきです。オプションとして、CConsoleCommand::getHelp をオーバライドして、コマンドの素敵なヘルプ情報を表示することも可能です。

class MyCommand extends CConsoleCommand
{
    public function run($args)
    {
        // $argsは、このコマンドに対するコマンドラインの引数の配列です
    }
 
    public function getHelp()
    {
        return '使用法: このコマンドの使いかた';
    }
}

モジュール

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

モジュール開発の一般的なガイドラインは、モジュールは自己充足的であるべきだ、ということです。モジュールによって使用されるリソースファイル (例えばCSS, JavaScript, 画像) はモジュールと共に配布されるべきです。そしてモジュールはそれらのファイルをウェブアクセス可能なように公開しなければなりません。

汎用コンポーネント

汎用コンポーネントのエクステンションの開発はクラスを書くことに似ています。ここでも、コンポーネントは、他の開発者によって容易に使用されるように、自己充足的なものでなければなりません。

$Id$

The Definitive Guide to Yii