Zend Framework 1.7.9 Manual

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

• isValid($files = null): 指定したファイルがすべてのバリデータを使用したかどうかを調べます。 $files には、実際のファイル名あるいは要素名、 またはテンポラリファイル名を指定します。

• addValidator($validator, $breakChainOnFailure, $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', false, 20000);

// ファイルサイズの最小値を 20 バイト、最大値を 20000 バイトに設定します
$upload->addValidator('Size', false, 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', false, 20000, 'file2');

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

$upload = new Zend_File_Transfer();

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

Note:

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

最後に、単純にファイルをチェックするには isValid() を使用します。

$upload = new Zend_File_Transfer();

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

if ($upload->isValid()) {
    print "検証に失敗";
}

Note:

isValid() は、 ファイルを受け取った際にそれまでコールされていなければ自動的にコールされることに注意しましょう。

検証に失敗した場合は、何が問題だったのかについての情報を取得したくなることでしょう。 getMessages() を使うとすべての検証メッセージを配列で取得できます。 また getErrors() はすべてのエラーコードを返し、 hasErrors() は検証エラーが見つかった時点で true を返します。

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

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

  Note:

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

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

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

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

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

$upload = new Zend_File_Transfer();

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

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

Note:

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

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

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

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

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

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

$upload = new Zend_File_Transfer();

// 拡張子 php あるいは exe のファイルは許可しません
$upload->addValidator('ExcludeExtension', false, 'php,exe');

// 拡張子 php あるいは exe のファイルを許可しない設定を配列記法で行います
$upload->addValidator('ExcludeExtension', false, array('php', 'exe'));

Note:

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

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

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

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

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

$upload = new Zend_File_Transfer();

// すべてのファイルで gif 画像の mimetype を許可しません
$upload->addValidator('ExcludeMimeType', false, 'image/gif');

// すべてのファイルで gif 画像および jpg 画像の mimetype を許可しません
$upload->addValidator('ExcludeMimeType', false, array('image/gif', 'image/jpeg');

// すべてのファイルで画像を許可しません
$upload->addValidator('ExcludeMimeType', false, 'image');

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

Note:

mimetype のグループを拒否してしまうと、意図していないものも含めて そのグループのすべての形式のファイルを拒否してしまうことに注意しましょう。 たとえば 'image' を拒否したら 'image/jpeg' や 'image/vasa' などすべての画像形式を拒否することになります。 すべての形式を拒否していいのかどうか不安な場合は、 グループ指定ではなく個別の mimetype を指定するようにしましょう。

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

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

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

$upload = new Zend_File_Transfer();

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

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

Note:

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

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

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

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

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

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

$upload = new Zend_File_Transfer();

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

// 配列形式で、拡張子を jpg と png のみに制限します
$upload->addValidator('Extension', false, 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';
}

Note:

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

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

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

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

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

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

• bytestring: 失敗したときに返す情報を、 人間が読みやすい形式にするかファイルサイズそのものにするかを設定します。

  このオプションで、ユーザが受け取る結果が '10864' あるいは '10MB' のどちらの形式になるのかを指定することができます。デフォルト値は true で、'10MB' 形式となります。

このバリデータは、両方のオプションを指定してインスタンス化することができます。 最初のオプションが 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', false, 40000);

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

// さきほどと同じですが、結果をプレーンなファイルサイズで返します
$upload->addValidator('FilesSize', false, array('10kB', '4MB', false);

Note:

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

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', false, 40, 100, 80, 200);

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

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

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

IsCompressed バリデータは、 転送されたファイルが zip や arc のような圧縮アーカイブ形式であるかどうかをチェックします。 このバリデータは MimeType バリデータを使用しており、 同じメソッドとオプションをサポートしています。 このバリデータを特定の圧縮形式のみに制限するには、 そのメソッドを使用します。

$upload = new Zend_File_Transfer();

// アップロードされたファイルが圧縮アーカイブであるかどうかチェックします
$upload->addValidator('IsCompressed', false);

// zip ファイルのみを対象とするようこのバリデータを制限します
$upload->addValidator('IsCompressed', false, array('application/zip'));

// よりシンプルな記法で、zip ファイルのみを対象とするようこのバリデータを制限します
$upload->addValidator('IsCompressed', false, 'zip');

Note:

指定したファイルタイプが compression 型であるかどうかのチェックは行われないことに注意しましょう。 論理的にはおかしな話ですが、gif ファイルがこのバリデータを通過するように設定することも可能です。

IsImage バリデータは、 転送されたファイルが gif や jpeg のような画像ファイルであるかどうかをチェックします。 このバリデータは MimeType バリデータを使用しており、 同じメソッドとオプションをサポートしています。 このバリデータを特定の画像形式のみに制限するには、 そのメソッドを使用します。

$upload = new Zend_File_Transfer();

// アップロードされたファイルが画像ファイルであるかどうかチェックします
$upload->addValidator('IsImage', false);

// gif ファイルのみを対象とするようこのバリデータを制限します
$upload->addValidator('IsImage', false, array('application/gif'));

// よりシンプルな記法で、gif ファイルのみを対象とするようこのバリデータを制限します
$upload->addValidator('IsImage', false, 'jpeg');

Note:

指定したファイルタイプが image 型であるかどうかのチェックは行われないことに注意しましょう。 論理的にはおかしな話ですが、zip ファイルがこのバリデータを通過するように設定することも可能です。

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

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

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

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

$upload = new Zend_File_Transfer();

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

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

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

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

Note:

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

Note:

このコンポーネントは、もし fileinfo 拡張モジュールが使用可能ならそれを使用します。使用できない場合は mime_content_type 関数を使用します。 この関数コールが失敗した場合は、HTTP で渡された mimetype を使用します。

fileinfo も mime_content_type も使えない場合は、セキュリティの問題に注意する必要があります。 HTTP から取得する mimetype はセキュアではなく、 容易に改ざんすることができます。

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

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

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

$upload = new Zend_File_Transfer();

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

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

Note:

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

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

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

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

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

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

• bytestring: 失敗したときに返す情報を、 人間が読みやすい形式にするかファイルサイズそのものにするかを設定します。

  このオプションで、ユーザが受け取る結果が '10864' あるいは '10MB' のどちらの形式になるのかを指定することができます。デフォルト値は true で、'10MB' 形式となります。

このバリデータは、両方のオプションを指定してインスタンス化することができます。 最初のオプションが 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', false, 40000);

// 指定したファイルのサイズを最大 4MB、最小 10kB に制限し、
// さらにエラー時に返す結果をユーザに優しい形式ではなくプレーンな数値とします
$upload->addValidator('Size', false, array('10kB', '4MB', false));