バリデータの使い方はきわめて簡単です。 バリデータを追加したり操作したりするには、次のメソッドを使用します。

• addValidator($validator, $options = null, $files = null): 指定したバリデータをバリデータスタックに追加します (オプションで、指定したファイルにだけ追加することもできます)。 $validator に指定するのは、 バリデータのインスタンスかあるいはバリデータの型の短い名前 (たとえば 'Count') です。

• addValidators(array $validators, $files = null): 指定した複数のバリデータをバリデータスタックに追加します。 各エントリは、バリデータの型とオプションのペアか あるいはキー 'validator' を持つ配列となります (配列の場合、バリデータのオプションはインスタンスの作成時に設定するものとします)。

• setValidators(array $validators, $files = null): 既存のバリデータを、指定したバリデータで上書きします。 バリデータの指定方法は addValidators() と同じです。

• hasValidator($name): バリデータが登録されているかどうかを調べます。

• getValidator($name): 前回登録されたバリデータを返します。

• getValidators($files = null): 登録されているバリデータを返します。$files を渡すと、そのファイルに関連するバリデータを返します。

• removeValidator($name): 前回登録されたバリデータを削除します。

• clearValidators(): 登録されているすべてのバリデータを消去します。

$upload = new Zend_File_Transfer();

// ファイルサイズを 20000 バイトに設定します
$upload->addValidator('Size', 20000);

// ファイルサイズの最小値を 20 バイト、最大値を 20000 バイトに設定します
$upload->addValidator('Size', array(20, 20000));

// ファイルサイズの最小値を 20 バイト、最大値を 20000 バイトに設定し、同時にファイルの数も設定します
$upload->setValidators(array(
    'Size'  => array(20, 20000), 
    'Count' => array(1, 3),
));

            

$upload = new Zend_File_Transfer();

// ファイルサイズを 20000 バイトとし、それを 'file2' にのみ適用します
$upload->addValidator('Size', 20000, 'file2');

            

一般的には、単純に addValidators() メソッドをコールすることになるでしょう。 これは何度でもコールすることができます。

$upload = new Zend_File_Transfer();

// ファイルサイズを 20000 バイトに設定します
$upload->addValidator('Size', 20000)
       ->addValidator('Count', 2)
       ->addValidator('Filessize', 25000);

            

注意: 同じバリデータを複数回設定することもできます。 しかしそんなことをすると、 同じバリデータに異なるオプションを設定したときにおかしなことになるので注意しましょう。

Count バリデータは、 渡されたファイルの数をチェックします。 次のオプションをサポートしています。

• min: 転送するファイル数の最小値。

  注意: このオプションを使用する場合は、 このバリデータを最初にコールした際にファイル数の最小値を指定する必要があります。 そうしないとエラーが返されます。
  

  このオプションで、受け取りたいファイル数の最小値を指定することができます。

• max: 転送するファイル数の最大値。

  このオプションで、受け取りたいファイル数を制限することができます。 それだけでなく、フォームで定義されている以上の数のファイルを送られるなどの攻撃を防ぐこともできます。

このバリデータは、両方のオプションを指定してインスタンス化することができます。 最初のオプションが min、 2 番目のオプションが max となります。 オプションをひとつだけ指定した場合は、max とみなされます。しかし、後から setMin() や setMax() でオプションを設定することもできますし、 getMin() や getMax() で設定内容を取得することもできます。

$upload = new Zend_File_Transfer();

// ファイルの数を最大 2 に制限します
$upload->addValidator('Count', 2);

// 最大でも 5 個、少なくとも 1 つのファイルが返されるよう制限します
$upload->addValidator('Count', array(1, 5);

            

注意: このバリデータは、チェックしたファイルの数を内部に保存することに注意しましょう。 最大値を超えたファイルはエラーを返します。

Exists バリデータは、 指定したファイルの存在をチェックします。 次のオプションをサポートしています。

• directory: ファイルが指定したディレクトリに存在するかどうかをチェックします。

このバリデータで複数のディレクトリを指定するには、 カンマ区切りの文字列あるいは配列を使用します。 setDirectory()、addDirectory() および getDirectory() といったメソッドでディレクトリの設定や取得が可能です。

$upload = new Zend_File_Transfer();

// temp ディレクトリをチェック対象に追加します
$upload->addValidator('Exists', '\temp');

// ふたつのディレクトリを配列記法で追加します
$upload->addValidator('Exists', array('\home\images', '\home\uploads'));

            

注意: このバリデータは、ファイルが存在するかどうかをすべてのディレクトリでチェックすることに注意しましょう。 指定したディレクトリのうちのどこかひとつでもファイルが存在しなかった場合に検証が失敗します。

Extension バリデータは、 渡されたファイルの拡張子をチェックします。 次のオプションをサポートしています。

• extension: 指定したファイルがこの拡張子かどうかをチェックします。

• case: チェックの際に大文字小文字を区別するかどうかを設定します。 デフォルトでは大文字小文字を区別しません。 このオプションは、すべての拡張子に対して適用されることに注意しましょう。

このバリデータで複数の拡張子を指定するには、 カンマ区切りの文字列あるいは配列を使用します。 setExtension()、addExtension() および getExtension() といったメソッドで拡張子の設定や取得が可能です。

場合によっては大文字小文字を区別してチェックしたくなることもあるでしょう。 そんなときのために、コンストラクタで 2 番目のパラメータ $case を指定することができます。これを true にすると、大文字小文字を区別して拡張子のチェックを行います。

$upload = new Zend_File_Transfer();

// 拡張子を jpg と png のみに制限します
$upload->addValidator('Extension', 'jpg,png');

// 配列形式で、拡張子を jpg と png のみに制限します
$upload->addValidator('Extension', array('jpg', 'png'));

// 大文字小文字を区別したチェックを行います
$upload = new Zend_File_Transfer('mo,png', true);
if (!$upload->isValid('C:\temp\myfile.MO')) {
    print 'Not valid due to MO instead of mo';
}

            

注意: このバリデータがチェックするのはファイルの拡張子のみであることに注意しましょう。 実際の MIME タイプなどはチェックしません。

FilesSize バリデータは、 すべてのファイルの合計サイズをチェックします。 次のオプションをサポートしています。

• min: ファイルサイズの総合計の最小値を設定します。

  このオプションで、転送されるファイルの合計サイズの最小値を指定することができます。

• max: ファイルサイズの総合計の最大値を設定します。

  このオプションで、転送されるファイルの合計サイズの最大値を指定することができます。 個別のファイルのサイズはチェックしません。

このバリデータは、両方のオプションを指定してインスタンス化することができます。 最初のオプションが min、 2 番目のオプションが max となります。 オプションをひとつだけ指定した場合は、max とみなされます。しかし、後から setMin() や setMax() でオプションを設定することもできますし、 getMin() や getMax() で設定内容を取得することもできます。

サイズの指定には SI 記法も使えます。 これは多くのオペレーティングシステムでもサポートされているものです。 20000 バイトと書くかわりに、20kB とすることができるのです。すべての単位は、1024 単位に変換されます。 使用できる単位は kB、MB、 GB、TB、PB および EB です。先ほど説明したとおり、1kB は 1024 バイトであることに注意する必要があります。

$upload = new Zend_File_Transfer();

// ファイルサイズの合計を 40000 バイトまでに制限します
$upload->addValidator('FilesSize', 40000);

// ファイルサイズの合計を最大 4MB、最小 10kB に制限します
$upload->setValidator('FilesSize', array('10kB', '4MB');

            

注意: このバリデータは、チェックしたファイルのサイズを内部に保存することに注意しましょう。 最大値を超えたファイルはエラーを返します。

ImageSize バリデータは、 画像ファイルのサイズをチェックします。 次のオプションをサポートしています。

• minheight: 画像の高さの最小値を設定します。

  このオプションで、検証したい画像の高さの最小値を指定することができます。

• maxheight: 画像の高さの最大値を設定します。

  このオプションで、検証したい画像の高さの最大値を指定することができます。

• minwidth: 画像の幅の最小値を設定します。

  このオプションで、検証したい画像の幅の最小値を指定することができます。

• maxwidth: 画像の幅の最大値を設定します。

  このオプションで、検証したい画像の幅の最大値を指定することができます。

このバリデータは、これら 4 つのオプションを指定してインスタンス化することができます。 minheight あるいは minwidth を省略した場合は、 0 に設定されます。maxwidth あるいは maxheight を省略した場合は、null に設定されます。しかし、後から setImageMin() や setImageMax() で最小値・最大値を設定することもできますし、 getMin() や getMax() で設定内容を取得することもできます。

利便性を考慮して、setImageWidth や setImageHeight といったメソッドも用意されています。これは、幅や高さの最小値と最大値を設定します。 もちろん、それに対応する getImageWidth や getImageHeight も使用可能です。

サイズの検証をしたくない場合は、その部分に値 null を設定します。

$upload = new Zend_File_Transfer();

// 画像の高さを 100-200 ピクセル、幅を 40-80 ピクセルに制限します
$upload->addValidator('ImageSize', 40, 100, 80, 200);

// 配列表記を使用します
$upload->setValidator('ImageSize', array(40, 100, 80, 200);

// 連想配列表記を使用します
$upload->setValidator('ImageSize', array('minwidth' => 40, 'maxwidth' => 80, 'minheight' => 100, 'maxheight' => 200);

// 別の画像サイズを設定します
$upload->setImageWidth(20, 200);

            

MimeType バリデータは、 転送されるファイルの mimetype をチェックします。 次のオプションをサポートしています。

• MimeType: 検証したい mimetype 形式を設定します。

  このオプションで、許可したいファイルの mimetype を定義することができます。

このバリデータで複数の mimetype を指定するには、 カンマ区切りの文字列あるいは配列を使用します。 setMimeType()、addMimeType() および getMimeType() といったメソッドで mimetype の設定や取得が可能です。

$upload = new Zend_File_Transfer();

// mimetype を制限し、gif 画像のみを許可するようにします
$upload->addValidator('MimeType', 'image/gif');

// すべてのファイルが gif および jpeg 画像でなければならないように mimetype を制限します
$upload->setValidator('MimeType', array('image/gif', 'image/jpeg');

// すべてのファイルが画像であるように mimetype を制限します
$upload->setValidator('MimeType', 'image');

            

上の例で示したように、複数の mimetype をひとつのグループとして扱うこともできます。 画像ファイルならすべて許可したいという場合は、mimetype に 'image' と指定します。 'image' 以外にも 'audio'、'video'、'text などが使用可能です。

注意: mimetype のグループを許可してしまうと、アプリケーション側で対応しているか否かにかかわらず そのグループのすべての形式のファイルを許可してしまうことに注意しましょう。 たとえば 'image' を許可したら 'image/xpixmap' や 'image/vasa' も受け付けることになりますが、おそらくこれは問題となるでしょう。 アプリケーション側ですべての形式を処理できるかどうか不安なら、 グループ指定ではなく個別の mimetype を指定するようにしましょう。

NotExists バリデータは、 指定したファイルの存在をチェックします。 次のオプションをサポートしています。

• directory: ファイルが指定したディレクトリに存在しないかどうかをチェックします。

このバリデータで複数のディレクトリを指定するには、 カンマ区切りの文字列あるいは配列を使用します。 setDirectory()、addDirectory() および getDirectory() といったメソッドでディレクトリの設定や取得が可能です。

$upload = new Zend_File_Transfer();

// temp ディレクトリをチェック対象に追加します
$upload->addValidator('NotExists', '\temp');

// ふたつのディレクトリを配列記法で追加します
$upload->addValidator('NotExists', array('\home\images', '\home\uploads'));

            

注意: このバリデータは、ファイルが存在しないかどうかをすべてのディレクトリでチェックすることに注意しましょう。 指定したディレクトリのうちのどこかひとつでもファイルが存在した場合に検証が失敗します。

Size バリデータは、 個々のファイルのサイズをチェックします。 次のオプションをサポートしています。

• Min: ファイルサイズの最小値を設定します。

  このオプションで、転送されるファイルの個々のサイズの最小値を指定することができます。

• Max: ファイルサイズの最大値を設定します。

  このオプションで、転送されるファイルの個々のサイズを制限することができます。

このバリデータは、両方のオプションを指定してインスタンス化することができます。 最初のオプションが min、 2 番目のオプションが max となります。 オプションをひとつだけ指定した場合は、max とみなされます。しかし、後から setMin() や setMax() でオプションを設定することもできますし、 getMin() や getMax() で設定内容を取得することもできます。

サイズの指定には SI 記法も使えます。 これは多くのオペレーティングシステムでもサポートされているものです。 20000 バイトと書くかわりに、20kB とすることができるのです。すべての単位は、1024 単位に変換されます。 使用できる単位は kB、MB、 GB、TB、PB および EB です。先ほど説明したとおり、1kB は 1024 バイトであることに注意する必要があります。

$upload = new Zend_File_Transfer();

// ファイルサイズを 40000 バイトまでに制限します
$upload->addValidator('Size', 40000);

// 指定したファイルのサイズを最大 4MB、最小 10kB に制限し、
// このバリデータをファイル "uploadfile" に適用します
$upload->addValidator('Size', array('10kB', '4MB', 'uploadfile');