Zend_Form_Element は、Zend_Loader_PluginLoader を使用しており、バリデータやフィルタ、デコレータの場所を指定できます。 それぞれに独自のプラグインローダーが関連付けられており、 アクセサを使用して個別に取得したり変更したりできます。

プラグインローダーのメソッドで使用できるローダーの型は 'validate'、'filter' と 'decorator' です。 この型名は大文字小文字を区別しません。

プラグインローダーを使用するためのメソッドを以下にまとめます。

独自のバリデータやフィルタ、デコレータを作成すると、 複数のフォームで機能を共有したり独自の機能をカプセル化したりすることが簡単になります。

class My_Decorator_Label extends Zend_Form_Decorator_Abstract
{
    protected $_placement = 'PREPEND';

    public function render($content)
    {
        if (null === ($element = $this->getElement())) {
            return $content;
        }
        if (!method_exists($element, 'getLabel')) {
            return $content;
        }

        $label = $element->getLabel() . ':';

        if (null === ($view = $element->getView())) {
            return $this->renderLabel($content, $label);
        }

        $label = $view->formLabel($element->getName(), $label);

        return $this->renderLabel($content, $label);
    }

    public function renderLabel($content, $label)
    {
        $placement = $this->getPlacement();
        $separator = $this->getSeparator();

        switch ($placement) {
            case 'APPEND':
                return $content . $separator . $label;
            case 'PREPEND':
            default:
                return $label . $separator . $content;
        }
    }
}

$element->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');

$form->addElementPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');

バリデーションの前に、入力の正規化を行えると便利です。 あるいはそれが必要となることもあるでしょう。 たとえば、HTML タグを除去した後の内容を検証したりといった場合です。 あるいは、入力の前後に含まれるスペースを取り除いてから検証を行わないと StringLength バリデータが正しい判断をできないなどという場合もあります。 これらの操作は Zend_Filter が行います。 Zend_Form_Element はフィルタチェインをサポートしているので、 複数のフィルタを順に適用できます。 フィルタリングは、バリデーションの際や要素の値を getValue() で取得する際に行われます。

$filtered = $element->getValue();

フィルタをチェインに追加する方法は、次のふたつです。

では、例を見てみましょう。

// フィルタのインスタンス
$element->addFilter(new Zend_Filter_Alnum());

// 完全なクラス名
$element->addFilter('Zend_Filter_Alnum');

// 短い形式のフィルタ名
$element->addFilter('Alnum');
$element->addFilter('alnum');

短い形式の名前とは、通常はフィルタ名からプレフィックスを除いた部分のことです。 デフォルトでは、'Zend_Filter_' を除いた部分を表します。 また、最初の文字は大文字でも小文字でもかまいません。

$element->addPrefixPath('My_Filter', 'My/Filter/', 'filter');

フィルタリング前の値がほしい場合は getUnfilteredValue() メソッドを使用します。

$unfiltered = $element->getUnfilteredValue();

フィルタについての詳細な情報は Zend_Filter のドキュメント を参照ください。

フィルタ関係のメソッドを以下にまとめます。

セキュリティ界で有名なお言葉 "入力はフィルタリングせよ。 出力はエスケープせよ。" に賛同する人なら、フォームの入力を検証 ("入力のフィルタリング") したくなるでしょう。 Zend_Form では、各要素が個別にバリデータチェインを保持しています。 これは Zend_Validate_* のバリデータでできています。

バリデータをチェインに追加する方法は、次のふたつです。

では、例を見てみましょう。

// バリデータのインスタンス
$element->addValidator(new Zend_Validate_Alnum());

// 短い形式の名前
$element->addValidator('Alnum');
$element->addValidator('alnum');

短い形式の名前とは、通常はバリデータ名からプレフィックスを除いた部分のことです。 デフォルトでは、バリデータ名から 'Zend_Validate_' を除いた部分を表します。 また、最初の文字は大文字でも小文字でもかまいません。

$element->addPrefixPath('My_Validator', 'My/Validator/', 'validate');

どれかひとつのバリデーションに失敗したときに それ以降のバリデータを実行しないようにさせるには、2 番目のパラメータに TRUE を渡します。

$element->addValidator('alnum', true);

バリデータの名前を指定して追加する場合で そのバリデータクラスのコンストラクタが引数を受け付ける場合は、 addValidator() の 3 番目のパラメータに配列形式で指定します。

$element->addValidator('StringLength', false, array(6, 20));

この方式で引数を渡す場合は、コンストラクタで定義されているとおりの順で指定する必要があります。 上の例では、Zend_Validate_StringLenth クラスのインスタンスを作成する際にパラメータ $min と $max を指定しています。

$validator = new Zend_Validate_StringLength(6, 20);

複数のバリデータを一度に設定するには addValidators() を使用します。 このメソッドには、配列の配列を渡します。 各配列の要素は 1 から 3 となり、これが addValidator() に渡されます。

$element->addValidators(array(
    array('NotEmpty', true),
    array('alnum'),
    array('stringLength', false, array(6, 20)),
));

もうすこし詳しくはっきりと書きたい場合は、キー 'validator'、'breakChainOnFailure' そして 'options' を持つ配列を使用することもできます。

$element->addValidators(array(
    array(
        'validator'           => 'NotEmpty',
        'breakChainOnFailure' => true),
    array('validator' => 'alnum'),
    array(
        'validator' => 'stringLength',
        'options'   => array(6, 20)),
));

この使用法は、設定ファイルを用いてバリデータを設定する場合に便利です。

element.validators.notempty.validator = "NotEmpty"
element.validators.notempty.breakChainOnFailure = true
element.validators.alnum.validator = "Alnum"
element.validators.strlen.validator = "StringLength"
element.validators.strlen.options.min = 6
element.validators.strlen.options.max = 20

それが必要か否かにかかわらず、すべての項目がキーを持つことに注意しましょう。 これは、設定ファイルを使用する場合の制限事項となります。 しかし、これにより、その引数がどういう意味なのかをきちんと明示できるようになります。 バリデータのオプションは、正しい順で指定しなければならないことに注意しましょう。

要素を検証するには、その値を isValid() に渡します。

if ($element->isValid($value)) {
    // 有効
} else {
    // 無効
}

class My_Validate_PasswordConfirmation extends Zend_Validate_Abstract
{
    const NOT_MATCH = 'notMatch';

    protected $_messageTemplates = array(
        self::NOT_MATCH => 'パスワード (確認) の内容がパスワードと一致しません'
    );

    public function isValid($value, $context = null)
    {
        $value = (string) $value;
        $this->_setValue($value);

        if (is_array($context)) {
            if (isset($context['password_confirm'])
                && ($value == $context['password_confirm']))
            {
                return true;
            }
        } elseif (is_string($context) && ($value == $context)) {
            return true;
        }

        $this->_error(self::NOT_MATCH);
        return false;
    }
}

バリデータは、順番どおりに処理されます。 すべてのバリデータが実行されますが、 $breakChainOnFailure が true の場合はどれかひとつのバリデータが検証に失敗した時点で処理を終了します。 バリデータは、適切な順で指定するようにしましょう。

検証に失敗したときは、バリデータチェインから エラーコードとメッセージを取得できます。

$errors   = $element->getErrors();
$messages = $element->getMessages();

(注意: 返されるエラーメッセージは連想配列形式で、 エラーコードとエラーメッセージのペアとなります)

バリデータに加えて、ある要素が必須である場合は setRequired($flag) を使用できます。 デフォルトではこのフラグは FALSE です。 In combination with setAllowEmpty($flag) (TRUE by default) and setAutoInsertNotEmptyValidator($flag) (TRUE by default), the behavior of your validator chain can be modified in a number of ways:

バリデータについての詳細な情報は Zend_Validate のドキュメント を参照ください。

検証関係のメソッドを以下にまとめます。

多くのウェブ開発者にとって、XHTML のフォームを作成することは悩みの種です。 フォームの要素ひとつひとつに対して ラベルなどのマークアップが必要ですし、 ユーザの使いやすさを考慮して検証エラーメッセージも表示させなければなりません。 要素の数が増えれば増えるほど、この作業量は無視できなくなります。

Zend_Form_Element は、この問題を解決するために "デコレータ" を使用します。デコレータは、 要素にアクセスしてその中身をレンダリングするためのメソッドを持つクラスです。 デコレータの動作原理については、Zend_Form_Decorator のセクションを参照ください。

Zend_Form_Element がデフォルトで使用するデコレータは次のとおりです。

$element = new Zend_Form_Element('foo',
                                 array('disableLoadDefaultDecorators' =>
                                      true)
                                );

デコレータの実行順序は登録された順によって決まります。 つまり、最初に登録したデコレータから順に実行することになります。 したがって、デコレータを登録するときにはその順番に気をつけなければなりません。 あるいは、placement オプションを明示的に指定して順序を決めることもできます。 例として、デフォルトのデコレータを登録するコードを示します。

$this->addDecorators(array(
    array('ViewHelper'),
    array('Errors'),
    array('Description', array('tag' => 'p', 'class' => 'description')),
    array('HtmlTag', array('tag' => 'dd')),
    array('Label', array('tag' => 'dt')),
));

最初のコンテンツを作成するのは 'ViewHelper' デコレータで、これはフォーム要素そのものを作成します。 次に 'Errors' デコレータがその要素のエラーメッセージを取得し、 もしエラーが発生していた場合はそれをビューヘルパー 'FormErrors' に渡してレンダリングさせます。 説明が存在する場合は、'Description' デコレータがクラス 'description' の段落を追加します。ここには、そのコンテンツの内容を説明するテキストが書き込まれます。 その次のデコレータである 'HtmlTag' は、要素とエラーと説明文を HTML の <dd> タグで囲みます。最後に、'label' が要素のラベルを取得します。それをビューヘルパー 'FormLabel' に渡し、HTML の <dt> で囲みます。 ラベルの内容は、デフォルトでコンテンツの前に付加されます。 出力結果は、基本的にはこのようになります。

<dt><label for="foo" class="optional">Foo</label></dt>
<dd>
    <input type="text" name="foo" id="foo" value="123" />
    <ul class="errors">
        <li>"123" is not an alphanumeric value</li>
    </ul>
    <p class="description">
        This is some descriptive text regarding the element.
    </p>
</dd>

デコレータについての詳細な情報は Zend_Form_Decorator のセクション を参照ください。

// 'FooBar' へのエイリアス
$element->addDecorator(array('FooBar' => 'HtmlTag'),
                       array('tag' => 'div'));

// 後で、このように取得できます
$decorator = $element->getDecorator('FooBar');

// ふたつの 'HtmlTag' デコレータを使用するため、片方に 'FooBar' というエイリアスを指定します
$element->addDecorators(
    array('HtmlTag', array('tag' => 'div')),
    array(
        'decorator' => array('FooBar' => 'HtmlTag'),
        'options' => array('tag' => 'dd')
    ),
);

// 後で、このように取得できます
$htmlTag = $element->getDecorator('HtmlTag');
$fooBar  = $element->getDecorator('FooBar');

デコレータ関連のメソッドを以下にまとめます。

Zend_Form_Element は、 オーバーロードを使用して特定のデコレータをレンダリングすることもできます。 'render' で始まる名前のメソッドを __call() で捕捉し、メソッド名の残りの部分にもとづいてデコレータを探します。 見つかった場合は、そのデコレータ だけ をレンダリングします。 引数を渡すと、それがデコレータの render() メソッドにコンテンツとして渡されます。次の例を参照ください。

// ViewHelper デコレータのみをレンダリングします
echo $element->renderViewHelper();

// HtmlTag デコレータにコンテンツを渡してレンダリングします
echo $element->renderHtmlTag("This is the html tag content");

デコレータが存在しない場合は、例外が発生します。

Zend_Form_Element は、 要素の属性やメタデータを処理できます。 基本的な属性には次のようなものがあります。

フォームの要素の中にはメタデータを要するものもあります。たとえば XHTML のフォーム要素では、class や id といった属性を指定することになるでしょう。 これは、次のメソッドで行います。

しかし、たいていの場合はもっとシンプルにオブジェクトのプロパティとしてアクセスすることになるでしょう。 Zend_Form_Element はオーバーロードを使用してこの機能を実現しています。

// $element->setAttrib('class', 'text') と同じ意味です
$element->class = 'text;

デフォルトでは、すべての属性がビューヘルパーに渡され、 要素の描画時に使用します。これらの属性は、要素タグの HTML 属性として設定されます。

Zend_Form には、標準的な要素が同梱されています。詳細は 標準要素 の章を参照ください。

Zend_Form_Element には非常にたくさんのメソッドがあります。 以下に、それらのシグネチャを種類別に分けて簡単にまとめました。

Zend_Form_Element のコンストラクタには、配列あるいは Zend_Config オブジェクトでオプションを指定できます。 また、setOptions() や setConfig() で設定を変更することもできます。 一般に、キーの名前は次のようになります。

このルールには、次のような例外があります。

例として、すべての型の設定データを渡すファイルを見てみましょう。

[element]
name = "foo"
value = "foobar"
label = "Foo:"
order = 10
required = true
allowEmpty = false
autoInsertNotEmptyValidator = true
description = "Foo elements are for examples"
ignore = false
attribs.id = "foo"
attribs.class = "element"
; sets 'onclick' attribute
onclick = "autoComplete(this, '/form/autocomplete/element')"
prefixPaths.decorator.prefix = "My_Decorator"
prefixPaths.decorator.path = "My/Decorator/"
disableTranslator = 0
validators.required.validator = "NotEmpty"
validators.required.breakChainOnFailure = true
validators.alpha.validator = "alpha"
validators.regex.validator = "regex"
validators.regex.options.pattern = "/^[A-F].*/$"
filters.ucase.filter = "StringToUpper"
decorators.element.decorator = "ViewHelper"
decorators.element.options.helper = "FormText"
decorators.label.decorator = "Label"

独自の要素を作成するには Zend_Form_Element クラスを継承したクラスを作成します。 独自の要素を作成することになるのは、たとえば次のような場合です。

要素を継承する際に主に使用するメソッドは次の 2 つです。 init() で独自の初期化ロジックをあなたの要素に追加し、 loadDefaultDecorators() でデフォルトのデコレータのリストをあなたの要素に設定します。,

たとえば、あなたが作成するフォーム上のテキストボックスでは、すべて StringTrim フィルタが必要で、 かつ正規表現による入力検証を行うことになるとしましょう。 ついでに、表示用に独自のデコレータ 'My_Decorator_TextItem' も使用するものとします。さらに、標準の属性 'size' や 'maxLength'、そして 'class' なども設定します。 このような要素は、次のように定義します。

class My_Element_Text extends Zend_Form_Element
{
    public function init()
    {
        $this->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator')
             ->addFilters('StringTrim')
             ->addValidator('Regex', false, array('/^[a-z0-9]{6,}$/i'))
             ->addDecorator('TextItem')
             ->setAttrib('size', 30)
             ->setAttrib('maxLength', 45)
             ->setAttrib('class', 'text');
    }
}

それから、フォームオブジェクトに対して この要素のプレフィックスパスを登録した上で要素を作成します。

$form->addPrefixPath('My_Element', 'My/Element/', 'element')
     ->addElement('text', 'foo');

'foo' 要素はこれで My_Element_Text 型となりました。先ほど説明したような機能を持つテキストボックスです。

Zend_Form_Element を継承したクラスでオーバーライドしたくなる その他のメソッドとして、loadDefaultDecorators() があります。このメソッドは、条件付きで 要素にデフォルトのデコレータセットを読み込みます。 継承したクラスで、このデコレータ群を置き換えることができます。

class My_Element_Text extends Zend_Form_Element
{
    public function loadDefaultDecorators()
    {
        $this->addDecorator('ViewHelper')
             ->addDecorator('DisplayError')
             ->addDecorator('Label')
             ->addDecorator('HtmlTag',
                            array('tag' => 'div', 'class' => 'element'));
    }
}

要素のカスタマイズにはさまざまな方法があります。 Zend_Form_Element の API ドキュメントを熟読し、 どんな機能が使用できるのかを覚えていきましょう。