repo_zf1/documentation/manual/ja/module_specs/Zend_File_Transfer-Validators.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 17685 -->
<sect1 id="zend.file.transfer.validators">

    <title>Zend_File_Transfer 用のバリデータ</title>

    <para>
        <classname>Zend_File_Transfer</classname> にはファイル関連のバリデータがいくつか同梱されています。
        これらを使用してセキュリティを向上させ、攻撃から身を守るようにしましょう。
        バリデータは、それを使ってこそ役に立つものなのですから。
        <classname>Zend_File_Transfer</classname> が提供するバリデータは
        <classname>Zend_Validator</classname> コンポーネントに含まれ、
        <classname>Zend_Validate_File_*</classname> という名前がついています。
        現在使用できるバリデータは次のとおりです。
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <code>Count</code>: このバリデータはファイルの数をチェックします。
                最小値と最大値を指定し、そのいずれかに違反した場合にエラーをスローします。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Crc32</code>: このバリデータはファイルの内容の crc32 ハッシュ値をチェックします。
                <code>Hash</code> バリデータをもとにしたもので、
                Crc32 のみをサポートする便利でシンプルなバリデータを提供します。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>ExcludeExtension</code>: このバリデータはファイルの拡張子をチェックします。
                渡されたファイルの拡張子が定義済みのものだった場合にエラーをスローします。
                これにより、特定の拡張子だけを除外できるようになります。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>ExcludeMimeType</code>: このバリデータはファイルの <acronym>MIME</acronym> 型をチェックします。
                <acronym>MIME</acronym> 型の種類を検証し、指定したファイルの <acronym>MIME</acronym>
                型がそれと一致するときにエラーをスローします。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Exists</code>: このバリデータはファイルの存在をチェックします。
                指定したファイルが存在しない場合にエラーをスローします。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Extension</code>: このバリデータはファイルの拡張子をチェックします。
                渡されたファイルの拡張子が未定義のものだった場合にエラーをスローします。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>FilesSize</code>: このバリデータはすべてのファイルのサイズをチェックします。
                すべてのファイルのサイズを内部的に記憶し、
                その合計が制限値を超えた場合にエラーをスローします。
                サイズの最小値と最大値を指定することができます。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>ImageSize</code>: このバリデータは画像のサイズをチェックします。
                幅と高さについて、最小値と最大値を検証することができます。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>IsCompressed</code>: このバリデータはファイルが圧縮されているかどうかをチェックします。
                <code>MimeType</code> バリデータにもとづいて、
                zip や arc といった圧縮アーカイブ形式かどうかを判断します。
                特定のアーカイブ形式のみに制限することもできます。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>IsImage</code>: このバリデータはファイルが画像であるかどうかをチェックします。
                <code>MimeType</code> バリデータにもとづいて、
                jpg や gif といった画像ファイルであるかどうかを判断します。
                特定の画像形式のみに制限することもできます。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Hash</code>: このバリデータはファイルの内容のハッシュ値をチェックします。
                複数のアルゴリズムをサポートしています。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Md5</code>: このバリデータはファイルの内容の md5 ハッシュ値をチェックします。
                <code>Hash</code> バリデータをもとにしたもので、
                Md5 のみをサポートする便利でシンプルなバリデータを提供します。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>MimeType</code>: このバリデータはファイルの <acronym>MIME</acronym> 型をチェックします。
                <acronym>MIME</acronym> 型の種類を検証し、指定したファイルの <acronym>MIME</acronym>
                型がそれと一致しないときにエラーをスローします。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>NotExists</code>: このバリデータはファイルの存在をチェックします。
                指定したファイルが存在する場合にエラーをスローします。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Sha1</code>: このバリデータはファイルの内容の sha1 ハッシュ値をチェックします。
                <code>Hash</code> バリデータをもとにしたもので、
                sha1 のみをサポートする便利でシンプルなバリデータを提供します。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Size</code>: このバリデータは各ファイルのサイズをチェックします。
                最小値と最大値を指定し、そのいずれかに違反した場合にエラーをスローします。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Upload</code>: このバリデータは内部的に使用するもので、
                アップロード時に何らかの問題が発生していないかどうかをチェックします。
                自分でこれを設定してはいけません。これは、
                <classname>Zend_File_Transfer</classname> 自身が自動的に設定します。
                ですので、このバリデータのことは忘れてしまってもかまいません。
                ただ、そういうバリデータが存在することだけを覚えておきましょう。
            </para>
        </listitem>

        <listitem>
            <para>
                <code>WordCount</code>: このバリデータはファイル内の単語数をチェックします。
                最小値と最大値を指定し、そのいずれかに違反した場合にエラーをスローします。
            </para>
        </listitem>
    </itemizedlist>

    <sect2 id="zend.file.transfer.validators.usage">
        <title>Zend_File_Transfer でのバリデータの使用法</title>

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

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

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

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

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

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

            <listitem>
                <para>
                    <methodname>getValidator($name)</methodname>:
                    前回登録されたバリデータを返します。
                </para>
            </listitem>

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

            <listitem>
                <para>
                    <methodname>removeValidator($name)</methodname>:
                    前回登録されたバリデータを削除します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>clearValidators()</methodname>:
                    登録されているすべてのバリデータを消去します。
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.validators.usage.example">
            <title>ファイル転送用のバリデータの追加</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

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

        <example id="zend.file.transfer.validators.usage.exampletwo">
            <title>特定のファイルに対してのみのバリデータの適用</title>

            <para>
                <methodname>addValidator()</methodname>、<methodname>addValidators()</methodname> および
                <methodname>setValidators()</methodname> は、それぞれ最後の引数
                <code>$files</code> を指定することができます。
                この引数にはファイル名あるいはファイル名の配列を指定し、
                指定したファイルに対してのみバリデータを設定します。
            </para>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

        <example id="zend.file.transfer.validators.usage.examplemultiple">
            <title>複数のバリデータの追加</title>

            <para>
                単に <methodname>addValidator()</methodname> を複数回コールするほうがシンプルに書けます。
                個々のバリデータごとにコールするというわけです。
                これはコードの可読性も向上させ、保守性もあがります。
                すべてのメソッドは流れるようなインターフェイスを提供しているので、
                複数回のコールは以下のように書くことができます。
            </para>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

        </example>

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

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

        <example id="zend.file.transfer.validators.usage.exampleisvalid">
            <title>ファイルの検証</title>

            <para>
                <methodname>isValid()</methodname> には、
                アップロードあるいはダウンロードされるファイル名だけでなく、
                テンポラリファイル名やフォーム要素の名前を指定することもできます。
                パラメータを省略したり null を指定したりした場合は、
                すべてのファイルが検証対象となります。
            </para>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

        </example>

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

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

    </sect2>

    <sect2 id="zend.file.transfer.validators.count">
        <title>Count バリデータ</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>min</code>: 転送するファイル数の最小値。
                </para>

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

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

            <listitem>
                <para>
                    <code>max</code>: 転送するファイル数の最大値。
                </para>

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

        <para>
            文字列あるいは整数値を指定してインスタンス化すると、その値は
            <code>max</code> とみなされます。あるいは、後から <methodname>setMin()</methodname> や
            <methodname>setMax()</methodname> でオプションを設定することもできますし、
            <methodname>getMin()</methodname> や <methodname>getMax()</methodname>
            で設定内容を取得することもできます。
        </para>

        <example id="zend.file.transfer.validators.count.example">
            <title>Count バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

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

    <sect2 id="zend.file.transfer.validators.crc32">
        <title>Crc32 バリデータ</title>

        <para>
            <code>Crc32</code> バリデータは、転送されたファイルの中身のハッシュをチェックします。
            このバリデータは、<acronym>PHP</acronym> の hash 拡張モジュールの crc32 アルゴリズムを使用します。
            次のオプションをサポートしています。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: 任意のキーあるいは数値添字配列を設定します。
                    この値を、検証対象のハッシュと比較します。
                </para>

                <para>
                    異なるキーを使用して複数のハッシュを設定することができます。
                    すべてのキーの内容をチェックし、
                    どれにも一致しなかった場合にのみ検証が失敗します。
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.validators.crc32.example">
            <title>Crc32 バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

// アップロードされたファイルのハッシュが指定したものと一致するかどうかをチェックします
$upload->addValidator('Crc32', false, '3b3652f');

// ふたつの異なるハッシュを指定します
$upload->addValidator('Crc32', false, array('3b3652f', 'e612b69'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.validators.excludeextension">
        <title>ExcludeExtension バリデータ</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: 任意のキーあるいは数値添字配列を指定します。
                    指定したファイルがこの拡張子を使用していないかどうかをチェックします。
                </para>
            </listitem>

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

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

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

        <example id="zend.file.transfer.validators.excludeextension.example">
            <title>ExcludeExtension バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

 // 大文字小文字を区別するチェックを行います
$upload->addValidator('ExcludeExtension',
                      false,
                      array('php', 'exe', 'case' => true));
$upload->addValidator('ExcludeExtension',
                      false,
                      array('php', 'exe', 'case' => true));
]]></programlisting>

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

    <sect2 id="zend.file.transfer.validators.excludemimetype">
        <title>ExcludeMimeType バリデータ</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: 任意のキー、あるいは数値添字配列を指定します。
                    検証したい <acronym>MIME</acronym> 型を設定します。
                </para>

                <para>
                    このオプションで、許可したくないファイルの <acronym>MIME</acronym> 型を定義することができます。
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>headerCheck</code>: <constant>TRUE</constant> に設定すると、
                    <emphasis>fileInfo</emphasis> あるいは <emphasis>mimeMagic</emphasis>
                    拡張モジュールがない場合にも <acronym>HTTP</acronym>
                    情報からファイルタイプをチェックします。このオプションのデフォルト値は
                    <constant>FALSE</constant> です。
                </para>
            </listitem>
        </itemizedlist>

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

        <example id="zend.file.transfer.validators.excludemimetype.example">
            <title>ExcludeMimeType バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

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

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

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

    <sect2 id="zend.file.transfer.validators.exists">
        <title>Exists バリデータ</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: 任意のキーあるいは数値添字配列を指定し、
                    ファイルが指定したディレクトリに存在するかどうかをチェックします。
                </para>
            </listitem>
        </itemizedlist>

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

        <example id="zend.file.transfer.validators.exists.example">
            <title>Exists バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

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

    <sect2 id="zend.file.transfer.validators.extension">
        <title>Extension バリデータ</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: 任意のキーあるいは数値添字配列を設定し、
                    指定したファイルがこの拡張子かどうかをチェックします。
                </para>
            </listitem>

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

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

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

        <example id="zend.file.transfer.validators.extension.example">
            <title>Extension バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

// 大文字小文字を区別したチェックを行います
$upload->addValidator('Extension', false, array('mo', 'png', 'case' => true));
if (!$upload->isValid('C:\temp\myfile.MO')) {
    print 'Not valid because MO and mo do not match with case sensitivity;
}
]]></programlisting>

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

    <sect2 id="zend.file.transfer.validators.filessize">
        <title>FilesSize バリデータ</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>min</code>: ファイルサイズの総合計の最小値を設定します。
                    このオプションで、転送されるファイルの合計サイズの最小値を指定します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>max</code>: ファイルサイズの総合計の最大値を設定します。
                </para>

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

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

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

        <para>
            文字列を指定してインスタンス化すると、その値は
            <code>max</code> とみなされます。
            後から <methodname>setMin()</methodname> や
            <methodname>setMax()</methodname> でオプションを設定することもできますし、
            <methodname>getMin()</methodname> や <methodname>getMax()</methodname>
            で設定内容を取得することもできます。
        </para>

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

        <example id="zend.file.transfer.validators.filessize.example">
            <title>FilesSize バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

// アップロードされるファイルサイズの合計を 40000 バイトまでに制限します
$upload->addValidator('FilesSize', false, 40000);

// アップロードされるファイルサイズの合計を最大 4MB、最小 10kB に制限します
$upload->addValidator('FilesSize',
                      false,
                      array('min' => '10kB', 'max' => '4MB'));

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

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

    <sect2 id="zend.file.transfer.validators.imagesize">
        <title>ImageSize バリデータ</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>minheight</code>: 画像の高さの最小値を設定します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>maxheight</code>: 画像の高さの最大値を設定します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>minwidth</code>: 画像の幅の最小値を設定します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>maxwidth</code>: 画像の幅の最大値を設定します。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            <methodname>setImageMin()</methodname> や <methodname>setImageMax()</methodname>
            で最小値・最大値を設定することもできますし、
            <methodname>getMin()</methodname> や <methodname>getMax()</methodname>
            で設定内容を取得することもできます。
        </para>

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

        <para>
            サイズの検証をしたくない場合は、その部分に値 <constant>NULL</constant> を設定します。
        </para>

        <example id="zend.file.transfer.validators.imagesize.example">
            <title>ImageSize バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

// 検証用の幅をリセットします
$upload->setImageWidth(array('minwidth' => 20, 'maxwidth' => 200));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.validators.iscompressed">
        <title>IsCompressed バリデータ</title>

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

        <example id="zend.file.transfer.validators.iscompressed.example">
            <title>IsCompressed バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

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

        <note>
            <para>
                指定した <acronym>MIME</acronym>
                型がアーカイブ型であるかどうかのチェックは行われないことに注意しましょう。
                たとえば gif ファイルがこのバリデータを通過するように設定することも可能です。
                アーカイブ型かどうかのチェックには 'MimeType'
                バリデータを使用したほうが読みやすいコードとなります。
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.isimage">
        <title>IsImage バリデータ</title>

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

        <example id="zend.file.transfer.validators.isimage.example">
            <title>IsImage バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

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

        <note>
            <para>
                指定した <acronym>MIME</acronym>
                型が image 型であるかどうかのチェックは行われないことに注意しましょう。
                たとえば gif ファイルがこのバリデータを通過するように設定することも可能です。
                image 型かどうかのチェックには 'MimeType'
                バリデータを使用したほうが読みやすいコードとなります。
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.hash">
        <title>Hash バリデータ</title>

        <para>
            <code>Hash</code> バリデータは、転送されたファイルの中身のハッシュをチェックします。
            このバリデータは、<acronym>PHP</acronym> の hash 拡張モジュールを使用します。
            次のオプションをサポートしています。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: 任意のキーあるいは数値添字配列を設定します。
                    この値と、検証対象のハッシュとを比較します。
                </para>

                <para>
                    配列形式で複数のハッシュを設定することができます。
                    すべてのキーの内容をチェックし、
                    どれにも一致しなかった場合にのみ検証が失敗します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>algorithm</code>: ハッシュの取得に使用するアルゴリズムを設定します。
                </para>

                <para>
                    複数のアルゴリズムを設定するには、<methodname>addHash()</methodname>
                    メソッドを複数回コールします。
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.validators.hash.example">
            <title>Hash バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

// アップロードされたファイルのハッシュが指定したものと一致するかどうかをチェックします
$upload->addValidator('Hash', false, '3b3652f');

// ふたつの異なるハッシュを指定します
$upload->addValidator('Hash', false, array('3b3652f', 'e612b69'));

// 別のアルゴリズムでチェックを行います
$upload->addValidator('Hash',
                      false,
                      array('315b3cd8273d44912a7',
                            'algorithm' => 'md5'));
]]></programlisting>
        </example>

        <note>
            <para>
                このバリデータは、役 34 のハッシュアルゴリズムをサポートしています。
                よく使われるものとしては 'crc32' や 'md5' そして 'sha1' があります。
                サポートするアルゴリズムの一覧は、
                <ulink url="http://php.net">php.net</ulink> の
                <ulink url="http://php.net/hash_algos">hash_algos メソッド</ulink>
                を参照ください。
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.md5">
        <title>Md5 バリデータ</title>

        <para>
            <code>Md5</code> バリデータは、転送されたファイルの中身のハッシュをチェックします。
            このバリデータは、<acronym>PHP</acronym> の hash 拡張モジュールの md5 アルゴリズムを使用します。
            次のオプションをサポートしています。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: 任意のキーあるいは数値添字配列を設定します。
                </para>

                <para>
                    配列形式で複数のハッシュを設定することができます。
                    すべてのキーの内容をチェックし、
                    どれにも一致しなかった場合にのみ検証が失敗します。
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.validators.md5.example">
            <title>Md5 バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

// アップロードされたファイルのハッシュが指定したものと一致するかどうかをチェックします
$upload->addValidator('Md5', false, '3b3652f336522365223');

// ふたつの異なるハッシュを指定します
$upload->addValidator('Md5',
                      false,
                      array('3b3652f336522365223',
                            'eb3365f3365ddc65365'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.validators.mimetype">
        <title>MimeType バリデータ</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: 任意のキーあるいは数値添字配列を指定します。
                   検証したい <acronym>MIME</acronym> 型を設定します。
                </para>

                <para>
                    許可したいファイルの <acronym>MIME</acronym> 型を定義します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>headerCheck</code>: <constant>TRUE</constant> に設定すると、
                    <emphasis>fileInfo</emphasis> あるいは <emphasis>mimeMagic</emphasis>
                    拡張モジュールがない場合にも <acronym>HTTP</acronym>
                    情報からファイルタイプをチェックします。このオプションのデフォルト値は
                    <constant>FALSE</constant> です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>magicfile</code>: 使用する magicfile。
                </para>

                <para>
                    このオプションで、使用する magicfile を定義します。
                    指定しなかったり空だったりした場合は、定数 MAGIC
                    を使用します。このオプションは Zend Framework 1.7.1
                    以降で使用可能です。
                </para>
            </listitem>
        </itemizedlist>

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

        <para>
            fileinfo が使用する magicfile を設定するには、オプション 'magicfile' を使用します。
            さらに、<methodname>setMagicFile()</methodname> や <methodname>getMagicFile()</methodname>
            といったメソッドで後から magicfile の設定や取得が可能です。
            これらのメソッドは Zend Framework 1.7.1 以降で使用可能です。
        </para>

        <example id="zend.file.transfer.validators.mimetype.example">
            <title>MimeType バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

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

// 別の magicfile を使用します
$upload->addValidator('MimeType',
                      false,
                      array('image',
                            'magicfile' => '/path/to/magicfile.mgx'));
]]></programlisting>
        </example>

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

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

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

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

    <sect2 id="zend.file.transfer.validators.notexists">
        <title>NotExists バリデータ</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: 任意のキーあるいは数値添字配列を設定し、
                    ファイルが指定したディレクトリに存在しないかどうかをチェックします。
                </para>
            </listitem>
        </itemizedlist>

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

        <example id="zend.file.transfer.validators.notexists.example">
            <title>NotExists バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

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

<sect2 id="zend.file.transfer.validators.sha1">
        <title>Sha1 バリデータ</title>

        <para>
            <code>Sha1</code> バリデータは、転送されたファイルの中身のハッシュをチェックします。
            このバリデータは、<acronym>PHP</acronym> の hash 拡張モジュールの sha1 アルゴリズムを使用します。
            次のオプションをサポートしています。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: 任意のキーあるいは数値添字配列を設定します。
                </para>

                <para>
                    配列形式で複数のハッシュを設定することができます。
                    すべてのキーの内容をチェックし、
                    どれにも一致しなかった場合にのみ検証が失敗します。
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.validators.sha1.example">
            <title>sha1 バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

// アップロードされたファイルのハッシュが指定したものと一致するかどうかをチェックします
$upload->addValidator('sha1', false, '3b3652f336522365223');

// ふたつの異なるハッシュを指定します
$upload->addValidator('Sha1',
                      false, array('3b3652f336522365223',
                                   'eb3365f3365ddc65365'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.validators.size">
        <title>Size バリデータ</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>Min</code>: ファイルサイズの最小値を設定します。
                </para>

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

            <listitem>
                <para>
                    <code>Max</code>: ファイルサイズの最大値を設定します。
                </para>

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

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

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

        <para>
            文字列を指定してインスタンス化すると、その値は
            <code>max</code> とみなされます。あるいは、後から <methodname>setMin()</methodname> や
            <methodname>setMax()</methodname> でオプションを設定することもできますし、
            <methodname>getMin()</methodname> や <methodname>getMax()</methodname>
            で設定内容を取得することもできます。
        </para>

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

        <example id="zend.file.transfer.validators.size.example">
            <title>Size バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

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

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

    <sect2 id="zend.file.transfer.validators.wordcount">
        <title>WordCount バリデータ</title>

        <para>
            <code>WordCount</code> バリデータは、
            指定したファイル内の単語数をチェックします。
            次のオプションをサポートしています。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>min</code>: 見つかった単語数の最小値を設定します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>max</code>: 見つかった単語数の最大値を設定します。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            文字列あるいは整数値を指定してインスタンス化すると、その値は
            <code>max</code> とみなされます。あるいは、後から <methodname>setMin()</methodname> や
            <methodname>setMax()</methodname> でオプションを設定することもできますし、
            <methodname>getMin()</methodname> や <methodname>getMax()</methodname>
            で設定内容を取得することもできます。
        </para>

        <example id="zend.file.transfer.validators.wordcount.example">
            <title>WordCount バリデータの使用法</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

// ファイル内の単語数を 2000 語までに制限します
$upload->addValidator('WordCount', false, 2000);

// ファイル内の単語数を最大 5000 語、最小 1000 語に制限します
$upload->addValidator('WordCount', false, array('min' => 1000, 'max' => 5000));
]]></programlisting>

        </example>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 tw=80 et:
-->