フォーム要素のFilter
フォーム要素に入力された内容をチェックする際、また表示する際にどのように加工するかを決める機能です。通常のgetValueメソッドで得られる値はこれらのFilterで加工した値になります。もしFilterで加工前の値が必要な場合にはgetUnfilteredValueメソッドを利用します。
//通常はFilter済のものを得る $filtered = $formElement->getValue(); //フィルタで処理していなものが必要な場合 $unfiltered = $formElement->getUnfilteredValue();
FilterはVadator同様にフォーム要素に追加することができます。Filterを追加するにはフォーム要素のaddFilterを使います。addFilterメソッドの構文は次のとおりです。
addFilter($nameOrFilter, $options)
| 引数 | 標準の値 | 説明 |
| $nameOrFilter | (なし) | Filterの名前、フィルタオブジェクト |
| $options | null | Filterに渡す引数を配列に格納したもの |
//あらかじめ作成したFilterを追加
$filter = new Zend_Filter_Alnum();
$formElement->addFilter($filter);
//上と同じ
$formElement->addFilter('Alnum');
$formElement->addFilter('alnum');
//上と同じだが、引数を省略していないもの
//最後のarray(false)はZend_Filter_Alnumへの引数
$formElement->addFilter('Zend_Validate_Alnum', array(false));
組込みのFilterには次のようなものがあります：
| 名前 | Filterの引数 | 説明 |
| Alnum | $allowWhiteSpace | 英数字のみを通す。$allowWhiteSpaceは省略可能で、標準ではfalse（trueなら空白も許容する）。 |
| Alpha | $allowWhiteSpace | アルファベットのみを通す。$allowWhiteSpaceは省略可能で、標準ではfalse（trueなら空白も許容する）。 |
| BaseName | (なし) | 与えられた文字列をファイルパスと見なし、そのファイル名の部分だけを通す。 |
| Digits | (なし) | 数字のみを通す。 |
| Dir | (なし) | 与えられた文字列をファイルパスと見なし、そのフォルダの部分だけを通す。 |
| HtmlEntities | $quoteStyle, $charSet | HtmlEntitiesでエスケープ処理をする。$quoteStyle, $charSetは省略可能で、これらの指定に応じて処理の内容を変更する。 |
| Int | (なし) | 整数のみを通す。 |
| RealPath | (なし) | 与えられた文字列をファイルパスと見なし、シンボリックリンクなどがあった場合には実際のファイルパスに変更する。 |
| StringToLower | (なし) | 大文字のアルファベットは小文字にする。 |
| StringToUpper | (なし) | 小文字のアルファベットは大文字にする。 |
| StringTrim | $charList | $charListに含まれている各文字列を削除する。複数含まれている場合には、先頭のもののみ削除する。$charListは省略可能で、その場合には先頭と末尾の空白文字列を削除する。 |
| StripTags | $tagsAllowed, $attributesAllowed, $commentsAllowed, $allowComments | HTMLやPHPのタグを削除する。$allowCommentsでコメントも削除するかを指定する。また、他の引数は省略可能で、どのようなタグを削除するかを指定することができる。 |
フォーム要素の属性
この他にフォームの属性を設定することができます。特にZend_Formにとって意味のある属性の一覧を以下に示します。
| 属性 | メソッド | 説明 |
| name | setName, getName | フォーム要素のname属性。 |
| label | setLabel, getLabel | いくつかのフォーム要素では、フォーム要素の前に表示される。 |
| order | setOrder, getOrder | フォーム内でのこの要素が何番目に表示されるかの設定。 |
| value | setValue, getValue | フォーム要素の値。 |
| description | setDescription, getDescription | フォーム要素の説明。この説明をツールチップとして表示するJavaScriptなどが利用する。 |
| required | setRequired, getRequired | この値がtrueの場合、チェックのときに、このフォーム要素がなければエラーになる（多くの場合、空欄であってはならないのと等しい、autoInsertNotEmptyValidatorも参照のこと）。 |
| allowEmpty | setAllowEmpty, getAllowEmpty | このフォーム要素が空欄であった場合、チェックの際には無視するかどうかの設定。標準ではtrue。 |
| autoInsertNotEmptyValidator | setAutoInsertNotEmptyValidator, autoInsertNotEmptyValidator | requiredが設定がされている場合には空欄を許さないかどうかの設定。標準ではtrue。 |
それ以外の属性についてもsetAttrib($name, $value)メソッドで設定することができます。
フォーム要素の設定の例
ここでは、$userに2つのValidatorと1つのFilter、そしていくつかの属性を設定した例を見てみます。
$user->addValidator('alnum')
->addValidator('regex', false, array('/^[a-z]/'))
->setLabel('Your name:')
->setRequired(true)
->addFilter('StringToLower');
この例で、$userのフォーム要素へのユーザからの入力は、
- 英数字で構成されていなければならない
- 先頭は英字でなければならない
- ラベルは'Your name:' である
- 空欄であってはならない
- チェックするときや値を取ってくるときには大文字のアルファベットは小文字にする
という設定がされています。
なお，ここまでのフォーム要素の作成～フォーム要素の設定と、次に紹介するフォーム要素の追加はまとめて行うこともできます。その例については次のフォーム要素の追加内のコラムを参照して下さい。
フォーム要素の追加
作成・設定したフォーム要素をフォームに追加します。これにはフォームのaddElementメソッドを利用します：
//単純に追加する
$form->addElement($user);
//作成しながら追加する
$form->addElement('submit', '送信');
例の最初の追加（$userの追加）はaddElementにフォーム要素のオブジェクトを渡しています。このような場合には単純にそのオブジェクトがフォームに追加されます。
2つ目の例ではaddElementの最初の引数が文字列になっています。このような場合にはaddElementはその文字列に対応したフォーム要素を作成し、フォームに加えます。
なお、ここまでのフォームに対応するHTMLは次のようになります：
<form enctype="application/x-www-form-urlencoded" action="/index/hello" method="post"><dl class="zend_form"> <dt><label for="user" class="required">Your name:</label></dt> <dd> <input type="text" name="user" id="user" value=""></dd> <dt> </dt><dd> <input type="submit" name="送信" id="送信" value="送信"></dd></dl></form>
フォーム要素の設定はフォーム要素の作成・追加とまとめてやってしまうことができます。その場合にはaddElementの 3つ目の引数に設定をまとめて渡して下さい。先ほどの「フォーム要素設定の例」ですと、次のようになります：
$form->addElement('text', 'user', array(
'validators' => array(
'alnum',
array('regex', false, '/^[a-z]/')
),
'label' => 'Your name:',
'required' => true,
'filters' => array('StringToLower')));
標準で添付されているフォーム要素
なお、HTMLのフォームのinputに対応する、Zend_Formのフォーム要素として、以下のものが標準で添付されています：
| フォーム要素 | 説明 |
| Zend_Form_Element_Button | フォームのボタン要素。 |
| Zend_Form_Element_Checkbox | フォームのチェックボックス要素。 |
| Zend_Form_Element_Hidden | フォームの隠し要素。 |
| Zend_Form_Element_Hash | フォームへの入力経由でない入力（例えばスクリプトによって生成された入力）をチェックするための機能。 |
| Zend_Form_Element_Image | フォーム内にイメージを表示するのに使う。 |
| Zend_Form_Element_MultiCheckbox | フォームのマルチチェックボックス要素。 |
| Zend_Form_Element_Multiselect | フォームのマルチセレクト要素。 |
| Zend_Form_Element_Password | フォームのパスワード要素。 |
| Zend_Form_Element_Radio | フォームのラジオボタン要素。 |
| Zend_Form_Element_Reset | フォームのリセットト要素。 |
| Zend_Form_Element_Select | フォームのセレクト要素。 |
| Zend_Form_Element_Submit | フォームの送信ボタン要素。 |
| Zend_Form_Element_Text | フォームのテキスト要素。 |
| Zend_Form_Element_Textarea | フォームのテキストエリア要素。 |
このうち、Zend_Form_Element_Hashの使い方はピンと来ない方もいるかもしれませんが、これについてはこの後登場する例で使っています。
