Zend_Form では、 Zend_Loader_PluginLoader を使用することで 別の要素やデコレータの位置を指定できます。 それぞれにプラグインローダーを関連づけることができ、 汎用的なアクセサを使用してそれを取得したり変更したりします。

使用できるローダーの型は 'element' と 'decorator' です。さまざまなプラグインローダーメソッドが用意されています。 型の名前は大文字小文字を区別しません。

プラグインローダーで使用できるメソッドは、次のとおりです。

さらに、Zend_Form のインスタンスで作成したすべての要素や表示グループ用のプレフィックスパスを設定するには 次のメソッドを使用します。

独自の要素やデコレータを使用すると、 複数フォーム間で機能を共有したり 独自の機能をカプセル化したりできるようになります。 独自の要素を既存の標準クラスに置き換えて使用する例については、 要素のドキュメントの中の 独自のラベルを作る例 を参照ください。

Zend_Form では、フォームに要素を追加したり フォームから要素を削除したりするためのアクセサを提供しています。 これらは要素オブジェクトのインスタンスを受け取ることもできますし、 ファクトリとして要素オブジェクトのインスタンスを作成させることもできます。

要素を追加するもっとも基本的なメソッドが addElement() です。 このメソッドは、 Zend_Form_Element 型 (あるいは Zend_Form_Element を継承したクラス) のオブジェクト あるいは新しい要素を作成するための引数 (要素の型や名前、設定オプション) を受け取ります。

例を示します。

// 要素のインスタンスを使用します
$element = new Zend_Form_Element_Text('foo');
$form->addElement($element);

// ファクトリを使用します
//
// Zend_Form_Element_Text 型で
// 'foo' という名前の要素を作成します
$form->addElement('text', 'foo');

// 要素の label オプションを渡します
$form->addElement('text', 'foo', array('label' => 'Foo:'));

要素をフォームに追加したら、名前を指定してそれを取得できます。 取得するには、getElement() メソッドを使用するか オブジェクトのプロパティとして要素にアクセスします。 property:

// getElement():
$foo = $form->getElement('foo');

// オブジェクトのプロパティとして
$foo = $form->foo;

時には、フォームにアタッチせずに要素を作成したいこともあるでしょう (フォームに登録されているさまざまなプラグインパスを使いたいけれど、 そのオブジェクトは後でサブフォームにアタッチしたい場合など)。 そんな場合は createElement() メソッドを使用します。

// $username は Zend_Form_Element_Text オブジェクトとなります
$username = $form->createElement('text', 'username');

// すべての値を取得します
$values = $form->getValues();

// 'foo' 要素の値のみを取得します
$value = $form->getValue('foo');

$form->setDefaults($data);
$form->populate($data);

$form->reset();

// グローバルプレフィックスパスの設定:
// プレフィックス My_Foo_Filter、My_Foo_Validate、
// My_Foo_Decorator のパスを作成します。
$form->addElementPrefixPath('My_Foo', 'My/Foo/');

// フィルタのパスのみ:
$form->addElementPrefixPath('My_Foo_Filter',
                            'My/Foo/Filter',
                            'filter');

// バリデータのパスのみ:
$form->addElementPrefixPath('My_Foo_Validate',
                            'My/Foo/Validate',
                            'validate');

// デコレータのパスのみ:
$form->addElementPrefixPath('My_Foo_Decorator',
                            'My/Foo/Decorator',
                            'decorator');

$form->setElementDecorators(array(
    'ViewHelper',
    'Label'
));

$form->setElementDecorators(
    array(
        'ViewHelper',
        'Label'
    ),
    array(
        'foo',
        'bar'
    )
);

$form->setElementDecorators(
    array(
        'ViewHelper',
        'Label'
    ),
    array(
        'foo',
        'bar'
    ),
    false
);

$form->setElementFilters(array('StringTrim'));

表示グループを使用すると、複数の要素を仮想的にグループ化して 表示させることができます。 フォーム内の各要素に対しては名前を指定してアクセスできますが、 フォームの要素を順次処理したりレンダリングしたりするときは 表示グループは一括して扱われます。 表示グループのもっとも一般的な使用例は、 フィールドセット内の要素をグループ化することです。

表示グループの基底クラスは Zend_Form_DisplayGroup です。 このクラスのインスタンスを直接作成することもできますが、 一般的には Zend_Form の addDisplayGroup() メソッドでインスタンスを作成することになります。 このメソッドの最初の引数には要素名の配列を渡し、 表示グループの名前を 2 番目の引数で指定します。 オプションの 3 番目の引数で、設定の配列や Zend_Config オブジェクトを渡すこともできます。

'username' と 'password' という要素がすでにフォームに登録済みである場合に、 次のコードを使用するとそれらを表示グループ 'login' にまとめることができます。

$form->addDisplayGroup(array('username', 'password'), 'login');

表示グループにアクセスするには、 getDisplayGroup() メソッドを使用するか あるいは表示グループ名を指定します。

// getDisplayGroup() の使用
$login = $form->getDisplayGroup('login');

// オーバーロードの使用
$login = $form->login;

$form->addDisplayGroup(
    array('foo', 'bar'),
    'foobar',
    array('disableLoadDefaultDecorators' => true)
);

$form->addDisplayGroupPrefixPath('My_Foo_Decorator', 'My/Foo/Decorator');

$form->setDisplayGroupDecorators(array(
    'FormElements',
    'Fieldset'
));

// 'My_DisplayGroup' クラスを使用します
$form->addDisplayGroup(
    array('username', 'password'),
    'user',
    array('displayGroupClass' => 'My_DisplayGroup')
);

// すべての表示グループで 'My_DisplayGroup' クラスを使用します
$form->setDefaultDisplayGroupClass('My_DisplayGroup');

サブフォームの役割は、次のようなものです。

サブフォームは Zend_Form のオブジェクトです。一般的には Zend_Form_SubForm のオブジェクトとなります。 後者のクラスには、大きなフォームに含めるのに適したデコレータが含まれています (HTML の form タグをレンダリングせず、要素をグループ化するものです)。 サブフォームをアタッチするには、単にそれを要素に追加して名前を指定するだけです。

$form->addSubForm($subForm, 'subform');

サブフォームを取得するには、 getSubForm($name) を使用するかあるいはサブフォームの名前を使用します。

// getSubForm() の使用
$subForm = $form->getSubForm('subform');

// オーバーロードの使用
$subForm = $form->subform;

サブフォームは、親フォームの要素のひとつとして順次処理できます。 サブフォーム内の要素は処理できません。

$form->setSubFormDecorators(array(
    'FormElements',
    'Fieldset'
));

フォームで一番大切なのはフォームが含む要素ですが、 フォームにはそれ以外のメタデータも含まれます。たとえばフォームの名前 (この名前は、HTML のマークアップ時に ID として用いられます) やアクション、そしてメソッドなどです。 要素や表示グループ、サブフォームの数も含まれます。 それ以外にも任意のメタデータを含めることができます (通常は、form タグで指定する HTML 属性などをここに含めます)。

フォームの名前を設定したり取得したりするには name アクセサを使用します。

// 名前を設定します
$form->setName('registration');

// 名前を取得します
$name = $form->getName();

アクション (フォームを送信したときに進む URL) やメソッド (送信する方法。たとえば 'POST' あるいは 'GET') を設定するには、それぞれ action アクセサおよび method アクセサを使用します。

// アクションとメソッドを設定します
$form->setAction('/user/login')
     ->setMethod('post');

フォームのエンコード形式を設定するには enctype アクセサを使用します。 Zend_Form では 2 つの定数 Zend_Form::ENCTYPE_URLENCODED と Zend_Form::ENCTYPE_MULTIPART を定義しており、 これらはそれぞれ 'application/x-www-form-urlencoded' と 'multipart/form-data' に対応します。 しかし、これ以外にも任意のエンコード形式を指定できます。

// アクションとメソッド、そして enctype を設定します
$form->setAction('/user/login')
     ->setMethod('post')
     ->setEnctype(Zend_Form::ENCTYPE_MULTIPART);

Zend_Form は Countable インターフェイスを実装しており、count 関数の引数として使用できます。

$numItems = count($form);

任意のメタデータを設定するには attribs アクセサを使用します。 Zend_Form ではオーバーロードを使用して 要素や表示グループそしてサブフォームにアクセスしているので、 これがメタデータにアクセスするための唯一の方法となります。

// 属性を設定します
$form->setAttrib('class', 'zend-form')
     ->addAttribs(array(
         'id'       => 'registration',
         'onSubmit' => 'validate(this)',
     ));

// 属性を取得します
$class = $form->getAttrib('class');
$attribs = $form->getAttribs();

// 属性を削除します
$form->removeAttrib('onSubmit');

// すべての属性を削除します
$form->clearAttribs();

フォームのマークアップを作成するのは手間のかかる作業です。 特に、検証エラーの表示や値の送信などの決まりきった処理を何度も行うのは大変なことです。 この問題に対する Zend_Form からの回答が デコレータ です。

Zend_Form オブジェクトのデコレータを使用して、 フォームをレンダリングします。 FormElements デコレータは、フォームのすべての項目 (要素、表示グループ、サブフォーム) を順次処理し、それらをレンダリングした結果を返します。 それ以外のデコレータを使用して、コンテンツをラップしたり 前後に何かを追加したりできます。

Zend_Form のデフォルトのデコレータは、FormElements と HtmlTag (定義リストによるラッピングをします)、そして Form です。 以下のコードと同様です。

$form->setDecorators(array(
    'FormElements',
    array('HtmlTag', array('tag' => 'dl')),
    'Form'
));

これは、次のような出力をします。

<form action="/form/action" method="post">
<dl>
...
</dl>
</form>

フォームオブジェクトに設定した任意の属性は、 HTML の <form> タグの属性となります。

$form = new Zend_Form(array('disableLoadDefaultDecorators' => true));

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

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

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

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

独自のデコレータを使用してフォームを作成することもできます。 一般的な使用例としては、作成したい HTML が厳密に決まっている場合などがあります。 デコレータでそれとまったく同じ HTML を作成し、単純にそれを返せばいいのです。 個々の要素や表示グループに対してもそれぞれデコレータを使用できます。

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

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

// FormElements デコレータのみをレンダリングします
echo $form->renderFormElements();

// fieldset デコレータのみ、コンテンツを渡してレンダリングします
echo $form->renderFieldset("<p>This is fieldset content</p>");

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

フォームの主な使用法は、送信されたデータを検証することです。 Zend_Form は、フォーム全体あるいはその一部を一度に検証したり、 XmlHttpRequests (AJAX) のレスポンスを自動的に検証したりできます。 送信されたデータが無効な場合は、 要素やサブフォームについて 検証エラーのコードやメッセージを取得するメソッドが用意されています。

フォーム全体のバリデーションを行うには isValid() メソッドを使用します。

if (!$form->isValid($_POST)) {
    // 検証に失敗しました
}

isValid() はすべての必須要素の検証を行います。 また非必須要素の中で値が送信された要素についても検証します。

時には一部のデータだけを検証したいこともあるでしょう。そんな場合には isValidPartial($data) を使用します。

if (!$form->isValidPartial($data)) {
    // 検証に失敗しました
}

isValidPartial() は、 data の項目にマッチする要素についてのみ検証を行います。 マッチする要素がなかった場合は処理をスキップします。

AJAX リクエストの要素や要素グループを検証する際は、 通常はフォームの一部を検証してその結果を JSON で返すことになります。 processAjax() が、まさにその作業を行うメソッドです。

$json = $form->processAjax($data);

こうすれば、単純に JSON レスポンスをクライアントに返すことができます。 フォームの検証に成功した場合は、この結果は TRUE となります。 失敗した場合は、キーとメッセージのペアを含む javascript オブジェクトを返します。個々の 'message' が検証エラーメッセージの配列となります。

フォームの検証に失敗した場合は、エラーコードとエラーメッセージをそれぞれ getErrors() と getMessages() で取得できます。

$codes = $form->getErrors();
$messages = $form->getMessages();

個々の要素のコードとエラーメッセージを取得するには、 それぞれのメソッドに要素名を渡します。

$codes = $form->getErrors('username');
$messages = $form->getMessages('username');

$validValues = $form->getValidValues($_POST);

以下の一覧は、Zend_Form のメソッドをタイプ別にまとめたものです。

Zend_Form は、 setOptions() や setConfig() を用いて (あるいはコンストラクタでオプションや Zend_Config オブジェクトを渡して) さまざまに設定できます。 これらのメソッドを使用して、フォームの要素や表示グループ、デコレータ、 そしてメタデータを設定できます。

全般的なルールとして、もし 'set' + オプションのキー という名前のメソッドが Zend_Form にあった場合は、そのメソッドを使用するとオプションを設定できます。 アクセサが存在しない場合は キーが属性への参照とみなされ、 setAttrib() に渡されます。

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

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

[element]
name = "registration"
action = "/user/register"
method = "post"
attribs.class = "zend_form"
attribs.onclick = "validate(this)"

disableTranslator = 0

prefixPath.element.prefix = "My_Element"
prefixPath.element.path = "My/Element/"
elementPrefixPath.validate.prefix = "My_Validate"
elementPrefixPath.validate.path = "My/Validate/"
displayGroupPrefixPath.prefix = "My_Group"
displayGroupPrefixPath.path = "My/Group/"

elements.username.type = "text"
elements.username.options.label = "Username"
elements.username.options.validators.alpha.validator = "Alpha"
elements.username.options.filters.lcase = "StringToLower"
; more elements, of course...

elementFilters.trim = "StringTrim"
;elementDecorators.trim = "StringTrim"

displayGroups.login.elements.username = "username"
displayGroups.login.elements.password = "password"
displayGroupDecorators.elements.decorator = "FormElements"
displayGroupDecorators.fieldset.decorator = "Fieldset"

decorators.elements.decorator = "FormElements"
decorators.fieldset.decorator = "FieldSet"
decorators.fieldset.decorator.options.class = "zend_form"
decorators.form.decorator = "Form"

これは、XML や PHP の配列形式の設定ファイルにも簡単に置き換えることができます。

独自の設定のフォームを使用するもうひとつの方法は、 Zend_Form のサブクラスを作成することです。 これには次のような利点があります。

一般的な使用法としては、init() メソッドでフォーム要素などの設定を行います。

class My_Form_Login extends Zend_Form
{
    public function init()
    {
        $username = new Zend_Form_Element_Text('username');
        $username->class = 'formtext';
        $username->setLabel('Username:')
                 ->setDecorators(array(
                     array('ViewHelper',
                           array('helper' => 'formText')),
                     array('Label',
                           array('class' => 'label'))
                 ));

        $password = new Zend_Form_Element_Password('password');
        $password->class = 'formtext';
        $password->setLabel('Password:')
                 ->setDecorators(array(
                     array('ViewHelper',
                           array('helper' => 'formPassword')),
                     array('Label',
                           array('class' => 'label'))
                 ));

        $submit = new Zend_Form_Element_Submit('login');
        $submit->class = 'formsubmit';
        $submit->setValue('Login')
               ->setDecorators(array(
                   array('ViewHelper',
                   array('helper' => 'formSubmit'))
               ));

        $this->addElements(array(
            $username,
            $password,
            $submit
        ));

        $this->setDecorators(array(
            'FormElements',
            'Fieldset',
            'Form'
        ));
    }
}

このフォームのインスタンスを作成するのは、次のように簡単です。

$form = new My_Form_Login();

そして、すべての機能はすでに準備済みの状態で、 設定ファイルは不要です (この例はかなり単純化していることに注意しましょう。 バリデーションや要素のフィルタなどは省略しています)。

独自のフォームを作成する理由としてもうひとつよくあるのが、 デフォルトのデコレータを定義したいというものです。 この場合は loadDefaultDecorators() メソッドを上書きします。

class My_Form_Login extends Zend_Form
{
    public function loadDefaultDecorators()
    {
        $this->setDecorators(array(
            'FormElements',
            'Fieldset',
            'Form'
        ));
    }
}