目次

Ethna_Pluginのつかいかた(簡易)

| 書いた人 | いちい | 新規 | | 編集した人 | sotarok | 2.5.0p4以降に関して |

Ethna_Pluginのつかいかた(簡易)

プラグインは$type(種類)と$name(名前)で区別されます。プラグインのマネージャ(Ethna_Pluginクラス)は，命名規則にしたがってファイルを探索し，インクルードとインスタンス作成を代行します。

現時点では，

の5種類の$typeのプラグインが使えるようになっています。

プラグインオブジェクトの取得，実行

Ethna_Pluginがプラグインを管理しています。$type(=Hoge)と$name(=Fuga)を指定して，

$plugin =& $controller->getPlugin();
$hoge_plugin =& $plugin->getPlugin('Hoge', 'Fuga');
$hoge_plugin->doSomething();

のようにしてプラグインを使うことができます。

アプリケーションごとのプラグインの一覧は InfoManagerで見ることができます。

プラグインを用いた例

プラグインを用いた例として，アクションフォームでプラグインを使ってフォーム値の検証を行う方法を簡単に説明します。

Regexpバリデータプラグインは，パラメータとしてフォームの値と，バリデートするための正規表現を受け取り，フォームの値が正規表現にマッチするかを検証します。

バリデータプラグインの親クラスで，どのようなパラメータを受け取るのかなどが規定されています。

アプリケーションのフォーム定義において，

var $use_validator_plugin = true;

/**
 * @access private
 * @var array フォーム値定義
 */
var $form = array(
        'sample' => array(
            'form_type' => FORM_TYPE_TEXT,
            'type' => VAR_TYPE_STRING,
            'name' => 'サンプル',
            'regexp' => '/[0-9]+/',
            'regexp_error' => '正規表現にマッチしません',
        ),
    );

のように指定すると， $this->af->validate() の中でアクションフォームがRegexpバリデータプラグインのインスタンスを取得し，

'regexp' => '/[0-9]+/',
            'regexp_error' => '正規表現にマッチしません',

の部分をパラメータとしてフォーム値の検証を行います。

バリデータプラグインの詳細については、 フォーム値の自動検証を行う(プラグイン編)を参照してください。

また、新規にプラグインを導入するときの具体例については、 プラグイン導入の例を参照してください。

Ethna_Pluginのつかいかた(詳細)

Ethna-2.3.0からEthna_Pluginクラスが追加されました。Smartyのプラグインのように，Ethnaでもプラグイン方式の機能追加ができるようになります。

概要

現状，プラグイン自体は「ある命名規則に従ったファイル名とクラス名をもったオブジェクト」でしかありません。Ethna_Plugin_Validatorのように，そのプラグインの種類に応じた親クラスを用意して，その継承クラスとして定義されることを期待しています。そして，Ethna_ActionFormのように，そのプラグインを呼び出す側もプラグインを使うことを意識しておかなければなりません。

プラグインのマネージャとして，Ethna_Pluginクラス(class/Ethna_Plugin.php)があります。Ethna_Pluginは，種類($type)と名前($name)から，ある命名規則にしたがってプラグインのソースファイルを探索し，includeし，インスタンスを作ってアプリケーションに受け渡しをします。なお，Ethna_Pluginのインスタンス自体はEthna_ClassFactoryによって管理されます。

プラグインは，Ethna本体に付属する形のものと，アプリケーション固有のものとがあります。たとえばすべてのアプリケーションに共通するプラグインをEthna本体のディレクトリに配置したり，特定のアプリケーションでのみ必要なプラグインを作ったりすることができます。また，Ethna本体のプラグインを，命名規則に従うことでアプリケーションのプラグインによって上書きすることができます。

Ethna_Plugin

Ethna_PluginクラスはEthnaにおけるプラグインの管理機構を提供します。

Ethna_Plugin自体のインスタンスはEthna_Controller::getPlugin()から取得することができます。

$plugin =& $controller->getPlugin();
$hoge_plugin =& $plugin->getPlugin('Hoge', 'Fuga');
$hoge_plugin->doSomething();

命名規則

$type, $nameは大文字／小文字を区別しています。新たにプラグインを作る場合は、 Ucfirst のように，先頭を英大文字，以降を英小文字にすることを強くお勧めします。

Ethna本体に付属するプラグイン

アプリケーション固有のプラグイン

アプリケーション名をSampleとします。

$type ごとの親クラス

その $type の各 $name で共通したプロパティやインタフェースを定義します。

自動でincludeされるファイルについて

上で述べたように，同じ$type(種類)と$name(名前)をもつプラグインは，Ethna本体に付属するものとアプリケーション固有のものがあり，アプリケーション固有のものが優先されます。

一方，クラス名においては， Ethna_Plugin_Validator_Regexp と Sample_Plugin_Validator_Regexp のように異なる名前を持つため，両方を共存させることができます。このことは特に，Ethna本体に付属するプラグインのクラスを継承してアプリケーション固有のプラグインを作りたい場合に重要です。

Ethna_Plugin::getPlugin()は，指定された$typeと$nameから自動でソースファイルを探索しincludeしますが，インスタンスを作るべきクラスのソースファイルしかincludeしないことに注意してください。すなわち，アプリケーション固有のプラグインが存在する場合に，おなじ$typeと$nameを持つEthna本体付属のプラグインファイルは無視されます。

Ethna_Plugin::includePlugin()

Ethna_Pluginには，内部で管理しているレジストリとは別に，命名規則にしたがってincludeのみを行うstaticメソッド

が用意されました。Ethna_Pluginのインスタンスが手元にない，class定義の前に include しておきたいときなどに便利です。

Ethna_Plugin_Validator_Regexp を継承して Sample_Plugin_Validator_Regexp を作る例:

<?php
Ethna_Plugin::includeEthnaPlugin('Validator', 'Regexp');
class Hoge_Plugin_Validator_Fuga extends Ethna_Plugin_Validator_Regexp
{
    var $accept_array = true;
    function &validate($name, $var, $params)
    {
        $result = true;
        foreach (to_array($var) as $v) {
            $result = $result
                      && Ethna::isError(parent::validate($name, $v, $params));
        }
        return $result;
    }
}
?>

この例では，配列の個別要素に対して実行される正規表現バリデータを，配列をそのまま受け取るように変更した意味不明なバリデータになっているかもしれません(適当に書いただけなのでいつか直します)。

アプリケーション固有のプラグインについて

特定のprefixをもつプラグインを使う

sample という名前のアプリケーションに固有なプラグインは、基本的には Sample_Plugin_Hoge_Fuga という命名規則をに従うことになります。

Sample_Controller.phpの以下の設定を変更すれば、sampleに加えて特定のprefixを使うよう指示することもできます。

var $plugin_search_appids = array(
       /*
        * プラグイン検索時に検索対象となるアプリケーションIDのリストを記述します。
        *
        * 記述例：
        * Common_Plugin_Foo_Bar のような命名のプラグインがアプリケーションの
        * プラグインディレクトリに存在する場合、以下のように指定すると
        * Common_Plugin_Foo_Bar, {$project_id}_Plugin_Foo_Bar, Ethna_Plugin_Foo_Bar
        * の順にプラグインが検索されます。 
        *
        * 'Common', 'Sample', 'Ethna',
        */
       'Sample', 'Ethna',
   );

ちなみに 'Ethna' は Ethna 本体に付属するプラグインのprefixとして予約されています。これを削ると、Ethna本体のプラグインはこのアプリケーションでは使わない、ということになります(どうなるか分からないので残しておいてください)。

より細かい注意事項

$typeと$nameについて

Ethna_Plugin::getPlugin($type, $name) は与えられた $type と $name を上の命名規則にそのまま代入します。ディレクトリ名やファイル名にそのまま使われるので、 信用できない文字列を$type, $nameにそのまま代入しない よう気を付けてください。

また、大文字／小文字の違いでプラグインファイルが見付からないこともありますので、プラグインが認識されないときなどはこの点にも注意してください。なお、アプリケーションのログレベルをdebugに設定すると、プラグインを探す過程が詳細に記録されます。

$type, $name ともに、自作するときは Ucfirst (先頭が大文字、以降は小文字のアルファベット文字列) のような名前にすることを強くお薦めします。

親クラスについて

親クラスは必ずしも必要ではありません。

親クラスのファイルは(命名規則に従えば) Ethna 本体のディレクトリ内に置かれ、自動で include されます。そのため、たとえば root 権限がない環境で新しい $type のプラグインを定義できないかもしれません。

このような場合は、単純に親クラスのことを忘れて、命名規則にしたがったクラスとファイルをアプリケーション側に用意してプラグインを使うことができます。

3.0.0 以降で取り込まれる予定の変更について

取り込まれてから実際に詳細な使い方・プラグインの作り方は記述する予定ですが，ひとまず主な変更予定について記述します．

なお，この変更により プラグイン機能は 3.0.0 preview1 以降では後方互換性がなくなります ．

プラグインprefixの廃止

これまでは，'Ethna', 'APPID' などのprefixを，APPID_Controllerに

/**
     * @var array list of application id where Ethna searches plugin.
     */
    var $plugin_search_appids = array(
        'APPID', 'Ethna',
    );

などと定義し，これらのprefixをもったプラグインのクラス名を前から順に検索していくという形でした．

しかし，これのせいで，複数プロジェクトにまたがって利用したいプラグインや，ほかの人が作成したプラグインなどを自分のアプリケーションに取り込みたい場合の導入が面倒だった問題などがありました．

3.0.0 preview1 以降では， この prefix は Ethna のみに固定されます ．

したがって，2.5.0 以前のような，「Ethna prefix のプラグインクラスを継承してAPPID prefixのプラグインを実装」のような使い方ができなくなります．（ref . 自動でincludeされるファイルについて）．

プラグイン検索ディレクトリの変更

プラグイン検索ディレクトリは，以下の順序で行われます．

つまり，提供されるプラグインは大きく分けて，3種類ある，という扱いとなります．

  1. アプリケーション固有のプラグイン (app/plugin)
    • これは，app以下に定義されるプラグインです．これまでも，これが最優先で読み込まれていました．（ただし，これまでと違うところは，APPIDがprefixにつくのではなく，すべてEthnaとなります）．
  2. コミュニティ提供のプラグイン (Ethna/extlib/Plugin)
    • 今回の変更の主な目的はこれで，さまざまな人がつくったプラグインを，Ethna本体のディレクトリ直下にあるextlibに設置することにより，これを読み込めるようになります．
    • このような場所のディレクトリに設置した理由は，pear-local コマンドによるプラグイン提供をしやすくするためです．extlib以下にインストールされるようにビルド設定したPEAR形式でEthnaのプラグインを作成し，これをpear-localコマンドや（app/lib 以下にインストール），pearコマンド（サーバにインストールされます）で管理できます．
  3. Ethna本体にバンドルされたプラグイン (Ethna/class/Plugin)
    • これまでどおり，Ethna本体に同梱されて配布されるプラグインです．

アプリケーション固有のプラグイン以外は， include_pathを考慮した相対パスで読み込まれます ．たとえば 「Ethna_Plugin_Hoge_Fuga」を読み込みたいとします．

/home/user/hogeproject

にプロジェクトが作成されているとして，

  1. /home/user/hogeproject/app/plugin/Hoge/Fuga.php
  2. /home/user/hogeproject/lib/Ethna/class/Plugin/Hoge/Fuga.php
  3. /home/user/hogeproject/lib/Ethna/extlib/Plugin/Hoge/Fuga.php
  4. /usr/share/pear/Ethna/class/Plugin/Hoge/Fuga.php
  5. /usr/share/pear/Ethna/extlib/Plugin/Hoge/Fuga.php

ファイル名の命名規則

上記の変更で，特定のprefixというルールが存在しないので，ファイル名の命名規則が変更になりました．これまで冗長だったファイル名が簡潔になります（PEAR形式になります）

変更前：

Plugin/Hoge/Ethna_Plugin_Hoge_Fuga.php
(クラス名は「Ethna_Plugin_Hoge_Fuga」)

変更後

Plugin/Hoge/Fuga.php
(クラス名は「Ethna_Plugin_Hoge_Fuga」（変更なし）)

*1Ethna 2.3.6 以降

@2015 DQNEO