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

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

    <title>Validators for Zend_File_Transfer</title>

    <para>
        <classname>Zend_File_Transfer</classname> is delivered with several file-related validators which can be
        used to increase security and prevent possible attacks. Note that these validators are only as effective
        as how effectively you apply them. All validators provided with <classname>Zend_File_Transfer</classname> can
        be found in the <classname>Zend_Validator</classname> component and are named <classname>Zend_Validate_File_*</classname>.
        The following validators are available:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <code>Count</code>: This validator checks for the number of files. A minimum and maximum range can be specified.
                An error will be thrown if either limit is crossed.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Crc32</code>: This validator checks for the crc32 hash value of the content from a file.
                It is based on the <code>Hash</code> validator and provides a convenient and simple validator that only supports Crc32.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>ExcludeExtension</code>: This validator checks the extension of files. It will throw an
                error when an given file has a defined extension. With this validator, you can exclude defined extensions
                from being validated.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>ExcludeMimeType</code>: This validator validates the MIME type of files. It can also
                validate MIME types and will throw an error if the MIME type of specified
                file matches.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Exists</code>: This validator checks for the existence of files. It will throw an
                error when a specified file does not exist.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Extension</code>: This validator checks the extension of files. It will throw an
                error when a specified file has an undefined extension.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>FilesSize</code>: This validator checks the size of validated files.
                It remembers internally the size of all checked files and throws an error when the sum of
                all specified files exceed the defined size. It also provides minimum and maximum values.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>ImageSize</code>: This validator checks the size of image. It validates the width
                and height and enforces minimum and maximum dimensions.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>IsCompressed</code>: This validator checks whether the file is compressed. It is based on
                the <code>MimeType</code> validator and validates for compression archives like zip or arc.
                You can also limit it to other archives.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>IsImage</code>: This validator checks whether the file is an image. It is based on
                the <code>MimeType</code> validator and validates for image files like jpg or gif.
                You can also limit it to other image types.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Hash</code>: This validator checks the hash value of the content from a file.
                It supports multiple algorithms.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Md5</code>: This validator checks for the md5 hash value of the content from a file.
                It is based on the <code>Hash</code> validator and provides a convenient and simple validator that only supports Md5.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>MimeType</code>: This validator validates the MIME type of files. It can also
                validate MIME types and will throw an error if the MIME type of a specified
                file does not match.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>NotExists</code>: This validator checks for the existence of files. It will throw an
                error when an given file does exist.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Sha1</code>: This validator checks for the sha1 hash value of the content from a file.
                It is based on the <code>Hash</code> validator and provides a convenient and simple validator that only supports sha1.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Size</code>: This validator is able to check files for its file size. It
                provides a minimum and maximum size range and will throw an error when either of these thesholds are crossed.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Upload</code>: This validator is internal. It checks if an upload has
                resulted in an error. You must not set it, as it's automatically set by
                <classname>Zend_File_Transfer</classname> itself. So you do not use this validator directly. You should only
                know that it exists.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>WordCount</code>: This validator is able to check the number of words within files. It
                provides a minimum and maximum count and will throw an error when either of these thresholds
                are crossed.
            </para>
        </listitem>
    </itemizedlist>

    <sect2 id="zend.file.transfer.validators.usage">
        <title>Using Validators with Zend_File_Transfer</title>

        <para>
            Putting validators to work is quite simple. There are several methods for adding and manipulating validators:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>isValid($files = null)</code>: Checks the specified files using all validators.
                    <code>$files</code> may be either a real filename, the element's name or the name
                    of the temporary file.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>addValidator($validator, $breakChainOnFailure, $options = null, $files =
                    null)</code>: Adds the specified validator to the validator
                    stack (optionally only to the file(s) specified).
                    <code>$validator</code> may be either an actual validator
                    instance or a short name specifying the validator type (e.g., 'Count').
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>addValidators(array $validators, $files =
                        null)</code>: Adds the specified validators to the stack of
                    validators. Each entry may be either a validator
                    type/options pair or an array with the key 'validator'
                    specifying the validator. All other options will be
                    considered validator options for instantiation.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>setValidators(array $validators, $files =
                        null)</code>: Overwrites any existing validators with
                    the validators specified. The validators should follow the
                    syntax for <code>addValidators()</code>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>hasValidator($name)</code>: Indicates whether a
                    validator has been registered.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getValidator($name)</code>: Returns a previously
                    registered validator.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getValidators($files = null)</code>: Returns
                    registered validators. If <code>$files</code> is specified,
                    returns validators for that particular file or set of
                    files.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>removeValidator($name)</code>: Removes a previously
                    registered validator.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>clearValidators()</code>: Clears all
                    registered validators.
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.validators.usage.example">
            <title>Add Validators to a File Transfer Object</title>

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

// Set a file size with 20000 bytes
$upload->addValidator('Size', false, 20000);

// Set a file size with 20 bytes minimum and 20000 bytes maximum
$upload->addValidator('Size', false, array('min' => 20, 'max' => 20000));

// Set a file size with 20 bytes minimum and 20000 bytes maximum and
// a file count in one step
$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>Limit Validators to Single Files</title>

            <para>
                <code>addValidator()</code>, <code>addValidators()</code>, and
                <code>setValidators()</code> each accept a final
                <code>$files</code> argument. This argument can be used to
                specify a particular file or array of files on which to set the
                given validator.
            </para>

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

// Set a file size with 20000 bytes and limits it only to 'file2'
$upload->addValidator('Size', false, 20000, 'file2');
]]></programlisting>
        </example>

        <para>
            Normally, you should use the <code>addValidators()</code> method, which can be called
            multiple times.
        </para>

        <example id="zend.file.transfer.validators.usage.examplemultiple">
            <title>Add Multiple Validators</title>

            <para>
                Often it's simpler just to call <code>addValidator()</code> multiple times with one call for each
                validator. This also increases readability and makes your code more maintainable. All
                methods provide a fluent interface, so you can couple the calls as shown below:
            </para>

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

// Set a file size with 20000 bytes
$upload->addValidator('Size', false, 20000)
       ->addValidator('Count', false, 2)
       ->addValidator('Filessize', false, 25000);
]]></programlisting>

        </example>

        <note>
            <para>
                Note that setting the same validator
                multiple times is allowed, but doing so can lead to issues when using
                different options for the same validator.
            </para>
        </note>

        <para>
            Last but not least, you can simply check the files using <code>isValid()</code>.
        </para>

        <example id="zend.file.transfer.validators.usage.exampleisvalid">
            <title>Validate the Files</title>

            <para>
                <code>isValid()</code> accepts the file name of the uploaded or downloaded file, the temporary file name and
                or the name of the form element. If no parameter or null is given all files
                will be validated
            </para>

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

// Set a file size with 20000 bytes
$upload->addValidator('Size', false, 20000)
       ->addValidator('Count', false, 2)
       ->addValidator('Filessize', false, 25000);

if ($upload->isValid()) {
    print "Validation failure";
}
]]></programlisting>

        </example>

        <note>
            <para>
                Note that <code>isValid()</code> will be called automatically when you receive the files
                and have not called it previously.
            </para>
        </note>

        <para>
            When validation has failed it is a good idea to get information about the
            problems found. To get this information, you can use the methods <code>getMessages()</code> which returns all
            validation messages as array, <code>getErrors()</code> which returns all error codes, and
            <code>hasErrors()</code> which returns true as soon as a validation error has been found.
        </para>

    </sect2>

    <sect2 id="zend.file.transfer.validators.count">
        <title>Count Validator</title>

        <para>
            The <code>Count</code> validator checks for the number of files which are provided. It
            supports the following option keys:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>min</code>: Sets the minimum number of files to transfer.
                </para>

                <note>
                    <para>
                        When using this option you must give the minimum number of files when
                        calling this validator the first time; otherwise you will get an error in return.
                    </para>
                </note>

                <para>
                    With this option you can define the minimum number of files you expect to receive.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>max</code>: Sets the maximum number of files to transfer.
                </para>

                <para>
                    With this option you can limit the number of files which are accepted but also detect a possible
                    attack when more files are given than defined in your form.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            If you initiate this validator with a string or integer, the value will be used as <code>max</code>.
            Or you can also use the methods <code>setMin()</code> and <code>setMax()</code> to set both
            options afterwards and <code>getMin()</code> and <code>getMax()</code> to retrieve the actual
            set values.
        </para>

        <example id="zend.file.transfer.validators.count.example">
            <title>Using the Count Validator</title>

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

// Limit the amount of files to maximum 2
$upload->addValidator('Count', false, 2);

// Limit the amount of files to maximum 5 and minimum 1 file
$upload->addValidator('Count', false, array('min' =>1, 'max' => 5));
]]></programlisting>

        </example>
        <note>
            <para>
                Note that this validator stores the number of checked files internally. The file which
                exceeds the maximum will be returned as error.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.crc32">
        <title>Crc32 Validator</title>

        <para>
            The <code>Crc32</code> validator checks the content of a transferred file by hashing it.
            This validator uses the hash extension from PHP with the crc32 algorithm.
            It supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: Sets any key or use a numeric array. The values will be used
                    as hash to validate against.
                </para>

                <para>
                    You can set multiple hashes by using different keys. Each will be checked and the validation will fail only
                    if all values fail.
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.validators.crc32.example">
            <title>Using the Crc32 Validator</title>

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

// Checks whether the content of the uploaded file has the given hash
$upload->addValidator('Crc32', false, '3b3652f');

// Limits this validator to two different hashes
$upload->addValidator('Crc32', false, array('3b3652f', 'e612b69'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.validators.excludeextension">
        <title>ExcludeExtension Validator</title>

        <para>
            The <code>ExcludeExtension</code> validator checks the file extension of the specified files. It
            supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: Sets any key or use a numeric array. The values will be used
                    to check whether the given file does not use this file extension.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>case</code>: Sets a boolean indicating whether validation should be case-sensitive. The default is not
                    case sensitive. Note that this key can be applied to for all available extensions.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            This validator accepts multiple extensions, either as a comma-delimited string, or as an
            array. You may also use the methods <code>setExtension()</code>, <code>addExtension()</code>,
            and <code>getExtension()</code> to set and retrieve extensions.
        </para>

        <para>
            In some cases it is useful to match in a case-sensitive fashion. So the constructor allows a
            second parameter called <code>$case</code> which, if set to true, validates the extension by comparing it with the specified values in a case-sensitive fashion.
        </para>

        <example id="zend.file.transfer.validators.excludeextension.example">
            <title>Using the ExcludeExtension Validator</title>

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

// Do not allow files with extension php or exe
$upload->addValidator('ExcludeExtension', false, 'php,exe');

// Do not allow files with extension php or exe, but use array notation
$upload->addValidator('ExcludeExtension', false, array('php', 'exe'));

// Check in a case-sensitive fashion
$upload->addValidator('ExcludeExtension',
                      false,
                      array('php', 'exe', 'case' => true));
$upload->addValidator('ExcludeExtension',
                      false,
                      array('php', 'exe', 'case' => true));
]]></programlisting>

        </example>
        <note>
            <para>
                Note that this validator only checks the file extension. It does not check the file's MIME type.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.excludemimetype">
        <title>ExcludeMimeType Validator</title>

        <para>
            The <code>ExcludeMimeType</code> validator checks the MIME type of transferred files.
            It supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: Sets any key individually or use a numeric array. Sets the MIME type to
                    validate against.
                </para>

                <para>
                    With this option you can define the MIME type of files that are not to be accepted.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            This validator accepts multiple MIME types, either as a comma-delimited string, or as an
            array. You may also use the methods <code>setMimeType()</code>, <code>addMimeType()</code>,
            and <code>getMimeType()</code> to set and retrieve the MIME types.
        </para>

        <example id="zend.file.transfer.validators.excludemimetype.example">
            <title>Using the ExcludeMimeType Validator</title>

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

// Does not allow MIME type of gif images for all files
$upload->addValidator('ExcludeMimeType', false, 'image/gif');

// Does not allow MIME type of gif and jpg images for all given files
$upload->addValidator('ExcludeMimeType', false, array('image/gif',
                                                      'image/jpeg');

// Does not allow MIME type of the group images for all given files
$upload->addValidator('ExcludeMimeType', false, 'image');
]]></programlisting>
        </example>

        <para>
            The above example shows that it is also possible to disallow groups of MIME types.
            For example, to disallow all images, just use 'image' as the MIME type. This can be used for all groups
            of MIME types like 'image', 'audio', 'video', 'text', etc.
        </para>

        <note>
            <para>
                Note that disallowing groups of MIME types will disallow all members of this group even if this
                is not intentional. When you disallow 'image' you will disallow all types of images like
                'image/jpeg' or 'image/vasa'. When you are not sure if you want to disallow all types,
                you should disallow only specific MIME types instead of complete groups.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.exists">
        <title>Exists Validator</title>

        <para>
            The <code>Exists</code> validator checks for the existence of specified files. It
            supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: Sets any key or use a numeric array to check if the specific file exists
                    in the given directory.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            This validator accepts multiple directories, either as a comma-delimited string, or as an
            array. You may also use the methods <code>setDirectory()</code>, <code>addDirectory()</code>,
            and <code>getDirectory()</code> to set and retrieve directories.
        </para>

        <example id="zend.file.transfer.validators.exists.example">
            <title>Using the Exists Validator</title>

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

// Add the temp directory to check for
$upload->addValidator('Exists', false, '\temp');

// Add two directories using the array notation
$upload->addValidator('Exists',
                      false,
                      array('\home\images', '\home\uploads'));
]]></programlisting>

        </example>
        <note>
            <para>
                Note that this validator checks whether the specified file exists in all of the given directories. The validation will fail
                if the file does not exist in any of the given directories.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.extension">
        <title>Extension Validator</title>

        <para>
            The <code>Extension</code> validator checks the file extension of the specified files. It
            supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: Sets any key or use a numeric array to check whether the specified file
                    has this file extension.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>case</code>: Sets whether validation should be done in a case-sensitive fashion. The default is no
                    case sensitivity. Note the this key is used for all given extensions.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            This validator accepts multiple extensions, either as a comma-delimited string, or as an
            array. You may also use the methods <code>setExtension()</code>, <code>addExtension()</code>,
            and <code>getExtension()</code> to set and retrieve extension values.
        </para>

        <para>
            In some cases it is useful to test in a case-sensitive fashion. Therefore the constructor takes a
            second parameter <code>$case</code>, which, if set to true, will validate the extension in a case-sensitive fashion.
        </para>

        <example id="zend.file.transfer.validators.extension.example">
            <title>Using the Extension Validator</title>

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

// Limit the extensions to jpg and png files
$upload->addValidator('Extension', false, 'jpg,png');

// Limit the extensions to jpg and png files but use array notation
$upload->addValidator('Extension', false, array('jpg', 'png'));

// Check case sensitive
$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>
                Note that this validator only checks the file extension. It does not check the file's MIME type.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.filessize">
        <title>FilesSize Validator</title>

        <para>
            The <code>FilesSize</code> validator checks for the aggregate size of all transferred files.
            It supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>min</code>: Sets the minimum aggregate file size.
                    This option defines the minimum aggregate file size to be transferred.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>max</code>: Sets the maximum aggregate file size.
                </para>

                <para>
                    This option limits the aggregate file size of all transferred files, but not the
                    file size of individual files.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>bytestring</code>: Defines whether a failure is to return a user-friendly number or
                    the plain file size.
                </para>

                <para>
                    This option defines whether the user sees '10864' or '10MB'. The default value is true, so
                    '10MB' is returned if you did not specify otherwise.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            You can initialize this validator with a string, which will then be used to set the <code>max</code> option.
            You can also use the methods <code>setMin()</code> and <code>setMax()</code> to set both
            options after construction, along with <code>getMin()</code> and <code>getMax()</code> to retrieve the
            values that have been set previously.
        </para>

        <para>
            The size itself is also accepted in SI notation as handled by most operating systems. That is, instead of
            specifying <emphasis role="strong">20000 bytes</emphasis>, <emphasis role="strong">20kB</emphasis> may be given. All file sizes are converted
            using 1024 as the base value. The following Units are accepted: <code>kB</code>, <code>MB</code>,
            <code>GB</code>, <code>TB</code>, <code>PB</code> and <code>EB</code>. Note that 1kB is equal to 1024 bytes, 1MB is equal to 1024kB, and so on.
        </para>

        <example id="zend.file.transfer.validators.filessize.example">
            <title>Using the FilesSize Validator</title>

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

// Limit the size of all files to be uploaded to 40000 bytes
$upload->addValidator('FilesSize', false, 40000);

// Limit the size of all files to be uploaded to maximum 4MB and mimimum 10kB
$upload->addValidator('FilesSize',
                      false,
                      array('min' => '10kB', 'max' => '4MB'));

// As before, but returns the plain file size instead of a user-friendly string
$upload->addValidator('FilesSize',
                      false,
                      array('min' => '10kB',
                            'max' => '4MB',
                            'bytestring' => false));
]]></programlisting>

        </example>
        <note>
            <para>
                Note that this validator internally stores the file size of checked files. The file which
                exceeds the size will be returned as an error.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.imagesize">
        <title>ImageSize Validator</title>

        <para>
            The <code>ImageSize</code> validator checks the size of image files.
            It supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>minheight</code>: Sets the minimum image height.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>maxheight</code>: Sets the maximum image height.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>minwidth</code>: Sets the minimum image width.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>maxwidth</code>: Sets the maximum image width.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            The methods <code>setImageMin()</code> and <code>setImageMax()</code> also set
            both minimum and maximum values, while the methods <code>getMin()</code> and
            <code>getMax()</code> return the currently set values.
        </para>

        <para>
            For your convenience there are also the <code>setImageWidth()</code> and <code>setImageHeight()</code>
            methods, which set the minimum and maximum height and width of the image file. They, too, have corresponding
            <code>getImageWidth()</code> and <code>getImageHeight()</code> methods to retrieve the currently set values.
        </para>

        <para>
            To bypass validation of a particular dimension, the relevent option simply should not be set.
        </para>

        <example id="zend.file.transfer.validators.imagesize.example">
            <title>Using the ImageSize Validator</title>

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

// Limit the size of a image to a height of 100-200 and a width of
// 40-80 pixel
$upload->addValidator('ImageSize', false,
                      array('minwidth' => 40,
                            'maxwidth' => 80,
                            'minheight' => 100,
                            'maxheight' => 200)
                      );

// Reset the width for validation
$upload->setImageWidth(array('minwidth' => 20, 'maxwidth' => 200));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.validators.iscompressed">
        <title>IsCompressed Validator</title>

        <para>
            The <code>IsCompressed</code> validator checks if a transferred file is a compressed archive,
            such as zip or arc. This validator is based on the <code>MimeType</code> validator and supports
            the same methods and options. You may also limit this validator to particular compression types with
            the methods described there.
        </para>

        <example id="zend.file.transfer.validators.iscompressed.example">
            <title>Using the IsCompressed Validator</title>

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

// Checks is the uploaded file is a compressed archive
$upload->addValidator('IsCompressed', false);

// Limits this validator to zip files only
$upload->addValidator('IsCompressed', false, array('application/zip'));

// Limits this validator to zip files only using simpler notation
$upload->addValidator('IsCompressed', false, 'zip');
]]></programlisting>
        </example>

        <note>
            <para>
                Note that there is no check if you set a MIME type that is not a archive. For example, it
                would be possible to define gif files to be accepted by this validator. Using the
                'MimeType' validator for files which are not archived will result in more readable code.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.isimage">
        <title>IsImage Validator</title>

        <para>
            The <code>IsImage</code> validator checks if a transferred file is a image file, such as gif or
            jpeg. This validator is based on the <code>MimeType</code> validator and supports
            the same methods and options. You can limit this validator to particular image types with
            the methods described there.
        </para>

        <example id="zend.file.transfer.validators.isimage.example">
            <title>Using the IsImage Validator</title>

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

// Checks whether the uploaded file is a image file
$upload->addValidator('IsImage', false);

// Limits this validator to gif files only
$upload->addValidator('IsImage', false, array('application/gif'));

// Limits this validator to jpeg files only using a simpler notation
$upload->addValidator('IsImage', false, 'jpeg');
]]></programlisting>
        </example>

        <note>
            <para>
                Note that there is no check if you set a MIME type that is not an image. For example, it
                would be possible to define zip files to be accepted by this validator. Using the
                'MimeType' validator for files which are not images will result in more readable code.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.hash">
        <title>Hash Validator</title>

        <para>
            The <code>Hash</code> validator checks the content of a transferred file by hashing it.
            This validator uses the hash extension from PHP. It supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: Takes any key or use a numeric array. Sets the hash to validate against.
                </para>

                <para>
                    You can set multiple hashes by passing them as an array. Each file is checked, and the validation will fail only if all files fail validation.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>algorithm</code>: Sets the algorithm to use for hashing the content.
                </para>

                <para>
                    You can set multiple algorithm by calling the <code>addHash()</code> method multiple times.
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.validators.hash.example">
            <title>Using the Hash Validator</title>

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

// Checks if the content of the uploaded file contains the given hash
$upload->addValidator('Hash', false, '3b3652f');

// Limits this validator to two different hashes
$upload->addValidator('Hash', false, array('3b3652f', 'e612b69'));

// Sets a different algorithm to check against
$upload->addValidator('Hash',
                      false,
                      array('315b3cd8273d44912a7',
                            'algorithm' => 'md5'));
]]></programlisting>
        </example>

        <note>
            <para>
                This validator supports about 34 different hash algorithms. The most common include 'crc32',
                'md5' and 'sha1'. A comprehesive list of supports hash algorithms can be found at the
                <ulink url="http://php.net/hash_algos">hash_algos method</ulink> on the <ulink url="http://php.net">php.net site</ulink>.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.md5">
        <title>Md5 Validator</title>

        <para>
            The <code>Md5</code> validator checks the content of a transferred file by hashing it.
            This validator uses the hash extension for PHP with the md5 algorithm.
            It supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: Takes any key or use a numeric array.
                </para>

                <para>
                    You can set multiple hashes by passing them as an array. Each file is checked, and the validation will fail only if all files fail validation.
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.validators.md5.example">
            <title>Using the Md5 Validator</title>

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

// Checks if the content of the uploaded file has the given hash
$upload->addValidator('Md5', false, '3b3652f336522365223');

// Limits this validator to two different hashes
$upload->addValidator('Md5',
                      false,
                      array('3b3652f336522365223',
                            'eb3365f3365ddc65365'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.validators.mimetype">
        <title>MimeType Validator</title>

        <para>
            The <code>MimeType</code> validator checks the MIME type of transferred files.
            It supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: Sets any key or use a numeric array. Sets the MIME type type to validate against.
                </para>

                <para>
                    Defines the MIME type of files to be accepted.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>magicfile</code>: The magicfile to be used.
                </para>

                <para>
                    With this option you can define which magicfile to use. When it's not set or empty, the
                    MAGIC constant will be used instead. This option is available since Zend Framework 1.7.1.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            This validator accepts multiple MIME type, either as a comma-delimited string, or as an
            array. You may also use the methods <code>setMimeType()</code>, <code>addMimeType()</code>,
            and <code>getMimeType()</code> to set and retrieve MIME type.
        </para>

        <para>
            You can also set the magicfile which shall be used by fileinfo with the 'magicfile' option.
            Additionally there are convenient <code>setMagicFile()</code> and <code>getMagicFile()</code>
            methods which allow later setting and retrieving of the magicfile parameter. This methods are
            available since Zend Framework 1.7.1.
        </para>

        <example id="zend.file.transfer.validators.mimetype.example">
            <title>Using the MimeType Validator</title>

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

// Limit the MIME type of all given files to gif images
$upload->addValidator('MimeType', false, 'image/gif');

// Limit the MIME type of all given files to gif and jpeg images
$upload->addValidator('MimeType', false, array('image/gif', 'image/jpeg');

// Limit the MIME type of all given files to the group images
$upload->addValidator('MimeType', false, 'image');

// Use a different magicfile
$upload->addValidator('MimeType',
                      false,
                      array('image',
                            'magicfile' => '/path/to/magicfile.mgx'));
]]></programlisting>
        </example>

        <para>
            The above example shows that it is also possible to limit the accepted MIME type to a group of
            MIME types. To allow all images just use 'image' as MIME type. This can be used for all groups
            of MIME types like 'image', 'audio', 'video', 'text, and so on.
        </para>

        <note>
            <para>
                Note that allowing groups of MIME types will accept all members of this group even if your
                application does not support them. When you allow 'image' you will also get
                'image/xpixmap' or 'image/vasa' which could be problematic. When you are not sure if your
                application supports all types you should better allow only defined MIME types instead
                of the complete group.
            </para>
        </note>

        <note>
            <para>
                This component will use the <code>fileinfo</code> extension if it is available. If it's not,
                it will degrade to the <code>mime_content_type</code> function. And if the function call fails
                it will use the MIME type which is given by HTTP.
            </para>

            <para>
                You should be aware of possible security problems when you have whether <code>fileinfo</code>
                nor <code>mime_content_type</code> available. The MIME type given by HTTP is not secure and
                can be easily manipulated.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.validators.notexists">
        <title>NotExists Validator</title>

        <para>
            The <code>NotExists</code> validator checks for the existence of the provided files. It
            supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: Set any key or use a numeric array. Checks whether the file exists in the given directory.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            This validator accepts multiple directories either as a comma-delimited string, or as an
            array. You may also use the methods <code>setDirectory()</code>, <code>addDirectory()</code>,
            and <code>getDirectory()</code> to set and retrieve directories.
        </para>

        <example id="zend.file.transfer.validators.notexists.example">
            <title>Using the NotExists Validator</title>

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

// Add the temp directory to check
$upload->addValidator('NotExists', false, '\temp');

// Add two directories using the array notation
$upload->addValidator('NotExists', false,
                      array('\home\images',
                            '\home\uploads')
                     );
]]></programlisting>

        </example>
        <note>
            <para>
                Note that this validator checks if the file does not exist in all of the provided directories.
                The validation will fail if the file does exist in any of the given directories.
            </para>
        </note>
    </sect2>

<sect2 id="zend.file.transfer.validators.sha1">
        <title>Sha1 Validator</title>

        <para>
            The <code>Sha1</code> validator checks the content of a transferred file by hashing it.
            This validator uses the hash extension for PHP with the sha1 algorithm.
            It supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>*</code>: Takes any key or use a numeric array.
                </para>

                <para>
                    You can set multiple hashes by passing them as an array. Each file is checked, and the validation will fail only if all files fail validation.
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.validators.sha1.example">
            <title>Using the sha1 Validator</title>

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

// Checks if the content of the uploaded file has the given hash
$upload->addValidator('sha1', false, '3b3652f336522365223');

// Limits this validator to two different hashes
$upload->addValidator('Sha1',
                      false, array('3b3652f336522365223',
                                   'eb3365f3365ddc65365'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.validators.size">
        <title>Size Validator</title>

        <para>
            The <code>Size</code> validator checks for the size of a single file. It
            supports the following options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>min</code>: Sets the minimum file size.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>max</code>: Sets the maximum file size.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>bytestring</code>: Defines whether a failure is returned with a user-friendly number, or
                    with the plain file size.
                </para>

                <para>
                    With this option you can define if the user gets '10864' or '10MB'. Default value is true
                    which returns '10MB'.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            You can initialize this validator with a string, which will then be used to set the <code>max</code> option.
            You can also use the methods <code>setMin()</code> and <code>setMax()</code> to set both
            options after construction, along with <code>getMin()</code> and <code>getMax()</code> to retrieve the
            values that have been set previously.
        </para>

        <para>
            The size itself is also accepted in SI notation as handled by most operating systems. That is, instead of
            specifying <emphasis role="strong">20000 bytes</emphasis>, <emphasis role="strong">20kB</emphasis> may be given. All file sizes are converted
            using 1024 as the base value. The following Units are accepted: <code>kB</code>, <code>MB</code>,
            <code>GB</code>, <code>TB</code>, <code>PB</code> and <code>EB</code>. Note that 1kB is equal to 1024 bytes, 1MB is equal to 1024kB, and so on.
        </para>

        <example id="zend.file.transfer.validators.size.example">
            <title>Using the Size Validator</title>

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

// Limit the size of a file to 40000 bytes
$upload->addValidator('Size', false, 40000);

// Limit the size a given file to maximum 4MB and mimimum 10kB
// Also returns the plain number in case of an error
// instead of a user-friendly number
$upload->addValidator('Size',
                      false,
                      array('min' => '10kB',
                            'max' => '4MB',
                            'bytestring' => false));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.validators.wordcount">
        <title>WordCount Validator</title>

        <para>
            The <code>WordCount</code> validator checks for the number of words within provided files. It
            supports the following option keys:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>min</code>: Sets the minimum number of words to be found.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>max</code>: Sets the maximum number of words to be found.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            If you initiate this validator with a string or integer, the value will be used as <code>max</code>.
            Or you can also use the methods <code>setMin()</code> and <code>setMax()</code> to set both
            options afterwards and <code>getMin()</code> and <code>getMax()</code> to retrieve the actual
            set values.
        </para>

        <example id="zend.file.transfer.validators.wordcount.example">
            <title>Using the WordCount Validator</title>

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

// Limit the amount of words within files to maximum 2000
$upload->addValidator('WordCount', false, 2000);

// Limit the amount of words within files to maximum 5000 and minimum 1000 words
$upload->addValidator('WordCount', false, array('min' => 1000, 'max' => 5000));
]]></programlisting>

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