すべての入力データがバリデーションルールを通過すると、 isValid() メソッドは TRUE を返します。 無効な形式の入力や必須フィールドの未入力がひとつでもあると、 isValid() は FALSE を返します。

if ($input->isValid()) {
  echo "OK\n";
}

このメソッドには、オプションで文字列の引数を指定できます。 ここには、フィールドの名前を指定します。 指定したフィールドがバリデーションを通過して取得可能になると、 isValid('fieldName') は TRUE を返します。

if ($input->isValid('month')) {
  echo "'month' フィールドの内容は正しい形式です\n";
}

if ($input->hasInvalid() || $input->hasMissing()) {
  $messages = $input->getMessages();
}

// getMessages() は単に、getInvalid() と getMissing() を
// マージしたものを返します

if ($input->hasInvalid()) {
  $invalidFields = $input->getInvalid();
}

if ($input->hasMissing()) {
  $missingFields = $input->getMissing();
}

if ($input->hasUnknown()) {
  $unknownFields = $input->getUnknown();
}

getMessages() メソッドの返り値は連想配列となります。 ルール名と、そのルールに関連するエラーメッセージの配列を関連付けたものです。 この配列のインデックスは、ルールを宣言したときに使用したルール名であることに注意しましょう。 これは、そのルールによるチェックを行ったフィールド名とは異なります。

getMessages() メソッドが返す配列は、 getInvalid() と getMissing() の結果をマージしたものとなります。 これらのメソッドは、それぞれバリデーションに失敗したときのメッセージと 必須入力項目が未入力の場合のメッセージを返すものです。

getErrors() メソッドは、 ルールの名前とエラー ID の配列を対応させた連想配列を返します。 エラー ID は固定文字列で、検証に失敗した原因を表します。 エラーメッセージは変更可能です。詳細は この節 を参照ください。

getMissing() が返すメッセージは、オプション 'missingMessage' で指定できます。 これは、Zend_Filter_Input のコンストラクタへの引数か、あるいは setOptions() メソッドで指定します。

$options = array(
    'missingMessage' => "Field '%field%' is required"
);

$input = new Zend_Filter_Input($filters, $validators, $data, $options);

// もうひとつの方法

$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setOptions($options);

Zend_Filter_Input によって返されるメッセージで、 複数の言語を提供できるようにするトランスレータも追加できます。

$translate = new Zend_Translate_Adapter_Array(array(
    'content' => array(
        Zend_Filter_Input::MISSING_MESSAGE => "Where is the field?"
    )
);

$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setTranslator($translate);

アプリケーション全体のトランスレータを使っているときは、 それは Zend_Filter_Input でも使われます。 この場合、手動でトランスレータを設定する必要はありません。

getUnknown() メソッドの結果は、 フィールド名とフィールドの値を対応させた連想配列となります。 ここで配列のキーとして使われるのはフィールド名であり、 ルールの名前ではありません。 どれが未知のフィールドなのかを表すのに、ルール名では具合が悪いからです。

無効でもなければ存在しないわけでもなく、 かつ未知でもないフィールドが、有効なフィールドとみなされます。 有効なフィールドの値を取得するためのマジックメソッドが用意されています。 また、それ以外にも getEscaped() および getUnescaped() というメソッドがあります。

$m = $input->month;                 // エスケープ済み (マジックメソッド)
$m = $input->getEscaped('month');   // エスケープ済み
$m = $input->getUnescaped('month'); // エスケープ前

デフォルトでは、値を取得する際には Zend_Filter_HtmlEntities によるフィルタリングが行われます。 これがデフォルトとなっている理由は、ほとんどの場合は フィールドの値を HTML に出力するであろうと考えられるからです。 HtmlEntities フィルタを使用すると、 HTML に予期せぬ出力が現れないようにして セキュリティ上の問題を防ぎます。

$validators = array('*' => array());

$input = new Zend_Filter_Input($filters, $validators, $data, $options);

別のフィルタによるエスケープを行うことも可能です。 その場合は、それをコンストラクタのオプション配列で指定します。

$options = array('escapeFilter' => 'StringTrim');
$input = new Zend_Filter_Input($filters, $validators, $data, $options);

あるいは、 setDefaultEscapeFilter() メソッドを使用することもできます。

$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setDefaultEscapeFilter(new Zend_Filter_StringTrim());

どちらの場合についても、エスケープフィルタの指定方法は フィルタクラスのベース名を表す文字列かフィルタクラスのインスタンスの いずれかとなります。エスケープフィルタとして使用できるのは、 フィルタチェインのインスタンスか Zend_Filter クラスのオブジェクトです。

出力をエスケープするフィルタは、このように バリデーションの終了後に適用しなければなりません。 フィルタルールで指定したその他のフィルタは、 バリデーションの前に適用されます。 エスケープフィルタをバリデーションの前に適用してしまうと、 バリデーション作業がより複雑になってしまい、 エスケープ前の値とエスケープ後の値を両方管理するのが難しくなります。 出力をエスケープするフィルタは、$filters 配列ではなく setDefaultEscapeFilter() で宣言することをお勧めします。

getEscaped() というメソッドがひとつあるだけなので、 エスケープ用のフィルタはひとつだけしか指定できません (とはいえ、そのフィルタとしてフィルタチェインを指定することもできます)。 ひとつの Zend_Filter_Input のインスタンスから 複数のフィルタリングメソッドの結果を返したい場合は、 Zend_Filter_Input を継承したサブクラスで新しいメソッドを実装して対応しましょう。

フィルタやバリデータの名前がそれを適用するフィールドの名前と異なる場合は、 'fields' メタコマンドでフィールド名を指定できます。

このメタコマンドを指定する際に、文字列ではなくクラス定数 Zend_Filter_Input::FIELDS を使用できます。

$filters = array(
    'month' => array(
        'Digits',        // 数値インデックスのフィルタ名 [0]
        'fields' => 'mo' // 文字列インデックスのフィールド名 ['fields']
    )
);

上の例では、'digits' フィルタを 'mo' という名前の入力フィールドに適用しています。 文字列 'month' は、単なるこのフィルタリングルールのニモニックキーとなります。 'fields' メタコマンドでフィールドを指定した場合は、 これはフィールド名としては使われず、単なるルール名となります。

'fields' メタコマンドのデフォルト値は、現在のルールのインデックスとなります。 上の例の場合は、'fields' メタコマンドを指定しなかった場合は、 'month' という名前のフィールドにこのルールが適用されます。

'fields' メタコマンドのもうひとつの使用法は、 複数のフィールドの入力を要求するフィルタやバリデータで フィールドを指定することです。 'fields' メタコマンドに配列を指定すると、 指定したフィールドの配列がフィルタやバリデータへの引数となります。 たとえば、パスワードを登録する場合に、ふたつのフィールドに入力させて その値が一致することを確認するなどといった処理は、よくあるものです。 配列の引数を受け取り、それらの入力フィールドの値が等しいときにだけ TRUE を返すバリデータを考えてみましょう。

$validators = array(
    'password' => array(
        'StringEquals',
        'fields' => array('password1', 'password2')
    )
);
// 仮想クラス Zend_Validate_StringEquals に、
// ふたつのフィールド 'password1' および 'password2'
// の値を含む配列を渡します

このルールのバリデーションに失敗した場合は、 getInvalid() の返り値はルールのキー ('password') となります。'fields' メタコマンドのフィールド名は用いられません。

バリデータ配列の各エントリでは、メタコマンド 'presence' を指定できます。 このメタコマンドの値が 'required' の場合は、 そのフィールドの値が必須となります。 未入力の場合は「存在しないフィールド」として報告されます。

このメタコマンドを指定する際に、文字列ではなくクラス定数 Zend_Filter_Input::PRESENCE を使用できます。

$validators = array(
    'month' => array(
        'digits',
        'presence' => 'required'
    )
);

このメタコマンドのデフォルト値は 'optional' です。

入力データにそのフィールドが存在しない場合に、もしメタコマンド 'default' がルールで指定されていれば そのメタコマンドの値がフィールドの値となります。

このメタコマンドを指定する際に、文字列ではなくクラス定数 Zend_Filter_Input::DEFAULT_VALUE を使用できます。

このデフォルト値は、バリデータを適用する前にフィールドの代入されます。 また、そのフィールドのデフォルト値は現在のルールでのみ適用されます。 もしそのフィールドが別のルールから参照されていた場合には、 別のルールを評価する際にはそのフィールドには値が入っていないことになります。 つまり、個々のルールで別々のデフォルト値を宣言できるということです。

$validators = array(
    'month' => array(
        'digits',
        'default' => '1'
    )
);

// 'month' フィールドの値がありません
$data = array();

$input = new Zend_Filter_Input(null, $validators, $data);
echo $input->month; // 1 を出力します

FIELDS メタコマンドで複数のフィールドをルールに定義している場合、 DEFAULT_VALUE メタコマンドに配列を指定できます。 対応するキーのフィールドの値が存在しない場合に、デフォルト値が用いられます。 FIELDS で複数のフィールドを定義しているのに DEFAULT_VALUE がスカラーだった場合は、 配列内のすべてのフィールドに対してその値がデフォルト値として用いられます。

このメタコマンドにはデフォルト値はありません。

デフォルトでは、入力データ中にフィールドが存在すれば、 たとえそれが空文字列 ('') であったとしてもバリデータを適用します。 その結果、検証に失敗することもありえます。 たとえば、数値かどうかを調べるバリデータは、 空文字列を通すとエラーを報告します。 空の文字列 (長さゼロの文字列) の中には文字が含まれないので、 数値を表す文字も含まれないからです。

空の文字列も有効であるとみなしたい場合は、メタコマンド 'allowEmpty' を TRUE に設定します。 すると、入力データとして空の文字列が渡された場合も検証を通過します。

このメタコマンドを指定する際に、文字列ではなくクラス定数 Zend_Filter_Input::ALLOW_EMPTY を使用できます。

$validators = array(
    'address2' => array(
        'Alnum',
        'allowEmpty' => true
    )
);

このメタコマンドのデフォルト値は FALSE です。

非常に珍しいケースですが、バリデータは一切登録せずにメタコマンド 'allowEmpty' を FALSE (つまり、空の値は無効とみなす) と設定した検証ルールを定義すると、 Zend_Filter_Input はデフォルトのエラーメッセージを返します。 このメッセージは getMessages() で取得できます。 このメッセージは、'notEmptyMessage' オプションで設定します。 このオプションは、Zend_Filter_Input のコンストラクタへの引数か、 あるいは setOptions() メソッドで指定します。

$options = array(
    'notEmptyMessage' => "'%field%' に何か値を入力してください"
);

$input = new Zend_Filter_Input($filters, $validators, $data, $options);

// 別の方法

$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setOptions($options);

デフォルトでは、ひとつのルールに複数のバリデータが登録されている場合は それをすべて適用し、すべてのエラーメッセージが結果のメッセージに含まれるようになります。

一方、メタコマンド 'breakChainOnFailure' を TRUE とすると、 どれかひとつのバリデータが失敗すると、 その時点でバリデータチェインが終了するようになります。 チェイン内のそれ以降のバリデータによる入力チェックは行いません。 つまり、指摘されたエラーを修正したとしても、 さらに別のエラーが発生する可能性があるということです。

このメタコマンドを指定する際に、文字列ではなくクラス定数 Zend_Filter_Input::BREAK_CHAIN を使用できます。

$validators = array(
    'month' => array(
        'Digits',
        new Zend_Validate_Between(1,12),
        new Zend_Validate_GreaterThan(0),
        'breakChainOnFailure' => true
    )
);
$input = new Zend_Filter_Input(null, $validators);

このメタコマンドのデフォルト値は FALSE です。

バリデータチェインクラスである Zend_Validate は、チェインの実行を中断できるという点で Zend_Filter_Input よりも柔軟です。 バリデータチェインクラスでは、チェイン内のバリデータのひとつが失敗したときに 即時に処理を終了させるオプションが設定できます。 Zend_Filter_Input の場合は、メタコマンド 'breakChainOnFailure' の設定がルール内のすべてのバリデータに適用されます。 より柔軟にしたい場合は、バリデータチェインを自前で作成して それをバリデータルールの定義時に指定します。

// breakChainOnFailure 属性を個別に設定した
// バリデータチェインを作成します
$chain = new Zend_Validate();
$chain->addValidator(new Zend_Validate_Digits(), true);
$chain->addValidator(new Zend_Validate_Between(1,12), false);
$chain->addValidator(new Zend_Validate_GreaterThan(0), true);

// さきほど作成したチェインを用いるバリデータルールを宣言します
$validators = array(
    'month' => $chain
);
$input = new Zend_Filter_Input(null, $validators);

ルール内の個々のバリデータのエラーメッセージを指定するには、メタコマンド 'messages' を使用します。このメタコマンドの値には、さまざまなものが指定できます。 たとえばひとつのルールの中に複数のバリデータがある場合に それぞれ別のメッセージを指定したり、 指定したバリデータで特定のエラー条件のときにのみ指定したメッセージを返したりといったことが考えられます。

このメタコマンドを指定する際に、文字列ではなくクラス定数 Zend_Filter_Input::MESSAGES を使用できます。

以下に示すのは、あるバリデータにデフォルトのエラーメッセージを設定する例です。

$validators = array(
    'month' => array(
        'digits',
        'messages' => '月として指定できるのは数字のみです'
    )
);

エラーメッセージを設定したいバリデータが複数ある場合は、 'messages' メタコマンドの値として配列を指定します。

この配列の各要素は、それぞれ同じインデックスのバリデータに適用されます。 つまり、n 番目のバリデータのメッセージを指定するには 配列のインデックスに n を指定します。 これを使用して、チェイン内の特定のバリデータにだけメッセージを設定して それ以外はデフォルトのメッセージを使用するということができます。

$validators = array(
    'month' => array(
        'digits',
        new Zend_Validate_Between(1, 12),
        'messages' => array(
            // バリデータ [0] はデフォルトのメッセージを使用し、
            // バリデータ [1] のみ独自のメッセージを指定します
            1 => '月として指定できるのは 1 から 12 までの値です'
        )
    )
);

ひとつのバリデータに複数のエラーメッセージが存在する場合は、 メッセージのキーで識別します。 各バリデータクラスにはそれぞれ異なるキーが存在し、そのキーを用いて それぞれのバリデータクラスが生成するエラーメッセージを識別します。 バリデータクラスでは、メッセージのキーに対応する定数が定義されています。 これらのキーを 'messages' メタコマンドで使用できます。 この場合、文字列ではなく連想配列形式で渡します。

$validators = array(
    'month' => array(
        'digits', new Zend_Validate_Between(1, 12),
        'messages' => array(
            '月として指定できるのは数字のみです',
            array(
                Zend_Validate_Between::NOT_BETWEEN =>
                    '月の値 %value% は、' .
                    '%min% 以上 %max% 以下の値でなければなりません',
                Zend_Validate_Between::NOT_BETWEEN_STRICT =>
                    '月の値 %value% は、%min% より大きく、' .
                    'かつ %max% より小さい値でなければなりません'
            )
        )
    )
);

各バリデータクラスがエラーメッセージを複数持っているかどうかや それらのメッセージのキー、そしてメッセージのテンプレートで使用できるトークン 等についての情報については、各バリデータクラスのドキュメントを参照ください。

検証ルールのなかにバリデータがひとつだけしかない場合、 あるいはすべてのバリデータで同じメッセージセットを使用する場合は、 配列構造で追加しなくても参照できます。

$validators = array(
    'month' => array(
        new Zend_Validate_Between(1, 12),
        'messages' => array(
                        Zend_Validate_Between::NOT_BETWEEN =>
                            '月の値 %value% は、' .
                            '%min% 以上 %max% 以下の値でなければなりません',
                        Zend_Validate_Between::NOT_BETWEEN_STRICT =>
                            '月の値 %value% は、%min% より大きく、' .
                            'かつ %max% より小さい値でなければなりません'
        )
    )
);

メタコマンド 'allowEmpty' や 'breakChainOnFailure'、 'presence' の全ルール共通のデフォルト値は、 Zend_Filter_Input のコンストラクタの引数 $options で設定できます。これを使用すると、 個別のルールにメタコマンドを設定しなくても 全ルール共通のデフォルト値を設定できます。

// デフォルトで、全フィールドに空文字列を許可するようにします
$options = array('allowEmpty' => true);

// 空文字列を禁止したいフィールドがある場合は、
// 個別のルール定義で、この設定を上書きできます
$validators = array(
    'month' => array(
        'Digits',
        'allowEmpty' => false
    )
);

$input = new Zend_Filter_Input($filters, $validators, $data, $options);

メタコマンド 'fields'、'messages' と 'default' については、 このテクニックを使うことができません。