<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.file.transfer.filters">
    <title>Filtres pour Zend_File_Transfer</title>

    <para>
        <classname>Zend_File_Transfer</classname> est fourni avec de multiples filtres qui
        peuvent être utilisés pour réaliser différentes tâches qui doivent être réalisées souvent
        sur les fichier. Notez que tout filtre est appliqué après la validation. De plus les filtres
        de fichiers se comportent légèrement différemment des autres filtres. Ils retourneront
        toujours le nom de fichier et non le contenu modifié (ce qui serait une mauvaise idée en
        travaillant avec un fichier d'1Go par exemple). Tous les filtres fournis avec
        <classname>Zend_File_Transfer</classname> peuvent être trouvés dans le composant
        <classname>Zend_Filter</classname> et sont nommés <classname>Zend_Filter_File_*</classname>.
        Les filtres suivants sont actuellement disponibles&#160;:
    </para>

    <itemizedlist>
        <listitem>
            <para><code>Decrypt</code>&#160;: ce filtre peut décrypter un fichier.</para>
        </listitem>

        <listitem>
            <para><code>Encrypt</code>&#160;: ce filtre peut crypter un fichier.</para>
        </listitem>

        <listitem>
            <para>
                <code>LowerCase </code>&#160;: ce filtre peut mettre en minuscule le contenu d'un
                fichier texte.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>Rename</code>&#160;: ce filtre peut renommer les fichiers, changer leur
                localisation et même forcer l'écrasement de fichiers existants.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>UpperCase </code>&#160;: ce filtre peut mettre en majuscule le contenu d'un
                fichier texte.
            </para>
        </listitem>
    </itemizedlist>

    <sect2 id="zend.file.transfer.filters.usage">
        <title>Utiliser les filtres avec Zend_File_Transfer</title>

        <para>
            L'utilisation des filtres est assez simple. Il existe de multiples méthodes pour
            ajouter et manipuler les filtres.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>addFilter($filter, $options = null, $files = null)</methodname>&#160;: ajoute
                    le filtre à la pile des filtres (optionnellement seul le(s) fichier(s)
                    spécifié(s)). <varname>$filter</varname> peut être soit une instance d'un filtre réel,
                    ou un nom court spécifiant le filtre (par exemple, "Rename").
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>addFilters(array $filters, $files = null)</methodname>&#160;: ajoute les
                    filtres à la pile des filtres. Chaque entrée peut être soit une paire
                    type/options, ou un tableau avec la clé "filtre" spécifiant le filtre (tous les
                    autres options seront considérées comme des options du filtre au moment de
                    l'instanciation).
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setFilters(array $filters, $files = null)</methodname>&#160;: surcharge les
                    filtres existants avec les filtres spécifiés. Les filtres doivent respecter la
                    même syntaxe <methodname>addFilters()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>hasFilter($name)</methodname>&#160;: indique si le filtre est enregistré.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getFilter($name)</methodname>&#160;: retourne un filtre préalablement
                    enregistré.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getFilters($files = null)</methodname>&#160;: retourne les filtres
                    enregistrés&#160;; si <varname>$files</varname> est fourni, retourne les filtres pour
                    ce fichier en particulier ou pour tous les fichiers.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>removeFilter($name)</methodname>&#160;: enlève le filtre préalablement
                    enregistré.
                </para>
            </listitem>

            <listitem>
                <para><methodname>clearFilters()</methodname>&#160;: efface tous les filtres.</para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.filters.usage.example">
            <title>Ajouter les filtres au fichier transféré</title>

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

// Paramètre un dossier de destination
$upload->addFilter('Rename', 'C:\image\uploads');

// Paramètre un nouveau dossier de destination
// et surcharge pour les fichiers existants
$upload->addFilter('Rename', array('target' => 'C:\picture\uploads', 'overwrite' => true));
]]></programlisting>
        </example>

        <example id="zend.file.transfer.filters.usage.exampletwo">
            <title>Limiter les filtres à des fichiers uniques</title>

            <para>
                <methodname>addFilter()</methodname>, <methodname>addFilters()</methodname>, and
                <methodname>setFilters()</methodname> accepte chacun un argument final <varname>$files</varname>. Cet
                argument peut être utilisé pour spécifier un fichier en particulier ou un tableau de
                fichiers sur lequel appliqué le filtre donné.
            </para>

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

// Paramètre un nouveau dossier de destination et
// le limite seulement à "file2"
$upload->addFilter('Rename', 'C:\image\uploads', 'file2');
]]></programlisting>
        </example>

        <para>
            Généralement vous devriez simplement utiliser la méthode
            <methodname>addFilters()</methodname>, qui peut être appelée plusieurs fois.
        </para>

        <example id="zend.file.transfer.filters.usage.examplemultiple">
            <title>Ajouter des filtres multiples</title>

            <para>
                Souvent il est plus simple d'appeler plusieurs fois <methodname>addFilter()</methodname> :
                un appel pour chaque filtre. Ceci améliore aussi la lisibilité et rend votre code
                plus maintenable. Comme toutes les méthodes fournissent un interface fluide, vous
                pouvez enchaîner les appels comme montré ci-dessous :
            </para>

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

// Renommer différemment chacun des fichiers
$upload->addFilter('Rename', 'file1', 'C:\picture\newjpg')
       ->addFilter('Rename', 'file2', 'C:\picture\newgif');
]]></programlisting>
        </example>

        <note>
            <para>
                Notez que même si l'ajout du même filtre plusieurs fois est autorisé, faire
                ceci peut entraîner des problèmes si vous utilisez différentes options pour le même
                filtre.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.filters.decrypt">
        <title>Filtre Decrypt</title>

        <para>Le filtre <code>Decrypt</code> permet de décrypter un fichier crypté.</para>

        <para>
            Ce filtre se sert de <classname>Zend_Filter_Decrypt</classname>. Il supporte les
            extensions <acronym>PHP</acronym> <code>Mcrypt</code> et <code>OpenSSL</code>. Reportez vous à la section
            associée pour voir les détails des possibilités d'options pour le décryptage et
            connaître les options supportées.
        </para>

        <para>
            Ce filtre supporte une option additionnelle qui peut être utilisée pour
            sauvegarder le fichier décrypté avec un autre nom de fichier. Spécifiez l'option
            <code>filename</code> pour changer le nom de fichier dans lequel le fichier décrypté
            sera stocké. Si vous supprimez cette option le fichier décrypté écrasera le fichier
            chiffré original.
        </para>

        <example id="zend.file.transfer.filters.decrypt.example1">
            <title>Utiliser le filtre Decrypt avec Mcrypt</title>

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

// Adds a filter to decrypt the uploaded encrypted file
// with mcrypt and the key mykey
$upload->addFilter('Decrypt',
    array('adapter' => 'mcrypt', 'key' => 'mykey'));
]]></programlisting>
        </example>

        <example id="zend.file.transfer.filters.decrypt.example2">
            <title>Utiliser le filtre Decrypt avec OpenSSL</title>

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

// Adds a filter to decrypt the uploaded encrypted file
// with openssl and the provided keys
$upload->addFilter('Decrypt',
    array('adapter' => 'openssl',
          'private' => '/path/to/privatekey.pem',
          'envelope' => '/path/to/envelopekey.pem'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.filters.encrypt">
        <title>Filtre Encrypt</title>

        <para>Le filtre <code>Encrypt</code> permet de crypter un fichier.</para>

        <para>
            Ce filtre se sert de <classname>Zend_Filter_Encrypt</classname>. Il supporte les
            extensions <acronym>PHP</acronym> <code>Mcrypt</code> et <code>OpenSSL</code>. Reportez vous à la section
            associée pour voir les détails des possibilités d'options pour le chiffrement et
            connaître les options supportées.
        </para>

        <para>
            Ce filtre supporte une option additionnelle qui peut être utilisée pour
            sauvegarder le fichier chiffré avec un autre nom de fichier. Spécifiez l'option
            <code>filename</code> pour changer le nom de fichier dans lequel le fichier chiffré sera
            stocké. Si vous supprimez cette option le fichier chiffré écrasera le fichier
            original.
        </para>

        <example id="zend.file.transfer.filters.encrypt.example1">
            <title>Utiliser le filtre Encrypt avec Mcrypt</title>

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

// Adds a filter to encrypt the uploaded file
// with mcrypt and the key mykey
$upload->addFilter('Encrypt',
    array('adapter' => 'mcrypt', 'key' => 'mykey'));
]]></programlisting>
        </example>

        <example id="zend.file.transfer.filters.encrypt.example2">
            <title>Utiliser le filtre Encrypt avec OpenSSL</title>

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

// Adds a filter to encrypt the uploaded file
// with openssl and the provided keys
$upload->addFilter('Encrypt',
    array('adapter' => 'openssl',
          'public' => '/path/to/publickey.pem'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.filters.lowercase">
        <title>Filtre LowerCase</title>

        <para>
            Le filtre <code>LowerCase</code> vous permet de mettre en minuscule le contenu
            d'un fichier. Vous devriez utiliser ce filtre seulement sur les fichiers texte.
        </para>

        <para>
            Lors de l'initialisation vous pouvez fournir qui sera utilisée en tant
            qu'encodage. Ou vous pouvez utiliser la méthode <methodname>setEncoding()</methodname> pour le
            paramétrer plus tard.
        </para>

        <example id="zend.file.transfer.filters.lowercase.example">
            <title>Utiliser le filtre LowerCase</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('MimeType', 'text');

// Ajoute un filtre pour mettre en minuscule les fichiers texte uploadés
$upload->addFilter('LowerCase');

// Ajoute un filtre pour mettre en minuscule seulement le fichier uploadé "uploadfile1"
$upload->addFilter('LowerCase', null, 'uploadfile1');

// Ajoute un filtre pour mettre en minuscule avec un encodage ISO-8859-1
$upload->addFilter('LowerCase', 'ISO-8859-1');
]]></programlisting>
        </example>

        <note>
            <para>
                Notez que les options du filtre LowerCase sont optionnelles, vous devez
                fournir un <constant>NULL</constant> en second paramètre quand vous souhaitez limiter le
                filtre à un fichier unique.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.file.transfer.filters.rename">
        <title>Filtre Rename</title>

        <para>
            Le filtre <code>Rename</code> vous permet de changer le dossier de destination du
            fichier uploadé, de changer le nom de fichier et aussi d'écraser des fichiers existants.
            Il supporte les options suivantes :
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>source</code> : le nom et le dossier de l'ancien fichier qui doit
                    être renommé.
                </para>
            </listitem>

            <listitem>
                <para><code>target</code> : le nouveau dossier ou nom du fichier.</para>
            </listitem>

            <listitem>
                <para>
                    <code>overwrite</code> : paramètre si l'ancien fichier écrase le nouveau
                    fichier s'il existe déjà. La valeur par défaut est <constant>FALSE</constant>.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            De plus vous pouvez utiliser la méthode <methodname>setFile()</methodname> pour paramétrer des
            fichiers, ce qui effacera ceux précédemment paramétrés, <methodname>addFile()</methodname> pour
            ajouter un nouveau fichier à ceux déjà présent, et <methodname>getFile()</methodname> pour récupérer
            les fichiers actuellement paramétrés. Pour simplifier les choses, ce filtre accepte de
            multiples notations et ces méthodes et constructeur comprennent les mêmes
            notations.
        </para>

        <example id="zend.file.transfer.filters.rename.example">
            <title>Utiliser le filtre Rename</title>

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

// Paramètre un nouveau dossier pour tous les fichiers
$upload->addFilter('Rename', 'C:\mypics\new');

// Paramètre un nouveau dossier seulement pour uploadfile1
$upload->addFilter('Rename', 'C:\mypics\newgifs', 'uploadfile1');
]]></programlisting>
        </example>

        <para>
            Vous pouvez utiliser différentes notations. Ci-dessous vous trouverez une table
            fournissant la description et le but des notations supportées. Notez que quand vous
            utilisez l'"Adapter" ou le "Form Element", vous ne pourrez pas utiliser toutes les
            notations décrites.
        </para>

        <table id="zend.file.transfer.filters.rename.notations">
            <title>Notations différentes du filtre "Rename" et leurs significations</title>

            <tgroup align="left" cols="2">
                <thead>
                    <row>
                        <entry>notation</entry>
                        <entry>description</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry>addFile('C:\uploads')</entry>
                        <entry>Spécifie un nouveau dossier pour tous les fichiers quand la
                        chaîne est un dossier. Notez que vous aurez une exception si le fichier
                        existe déjà, voir le paramètre d'écrasement.</entry>
                    </row>

                    <row>
                        <entry>addFile('C:\uploads\file.ext')</entry>
                        <entry>Spécifie un nouveau dossier et un nom de fichier pour tous les
                        fichiers quand la chaîne n'est pas un dossier. Notez que vous aurez une
                        exception si le fichier existe déjà, voir le paramètre
                        d'écrasement.</entry>
                    </row>

                    <row>
                        <entry>addFile('C:\uploads\file.ext', 'overwrite' =&gt; true)</entry>
                        <entry>Spécifie un nouveau dossier et un nom de fichier pour tous les
                        fichiers quand la chaîne n'est pas un dossier et écrase le fichier
                        existant si celui-ci existe. Notez que vous aurez pas de notification en
                        cas d'écrasement.</entry>
                    </row>

                    <row>
                        <entry>addFile(array('source' =&gt; 'C:\temp\uploads', 'target' =&gt;
                        'C:\uploads'))</entry>
                        <entry>Spécifie un nouveau dossier pour tous les fichiers qui sont
                        présent dans l'ancien dossier quand la chaîne est un dossier. Notez que
                        vous aurez une exception si le fichier existe déjà, voir le paramètre
                        d'écrasement.</entry>
                    </row>

                    <row>
                        <entry>addFile(array('source' =&gt; 'C:\temp\uploads', 'target' =&gt;
                        'C:\uploads', 'overwrite' =&gt; true))</entry>
                        <entry>Spécifie un nouveau dossier pour tous les fichiers qui sont
                        présent dans l'ancien dossier quand la chaîne est un dossier. Notez que
                        vous aurez pas de notification en cas d'écrasement.</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>

    <sect2 id="zend.file.transfer.filters.uppercase">
        <title>Filtre UpperCase</title>

        <para>
            Le filtre <code>UpperCase</code> vous permet de mettre en minuscule le contenu
            d'un fichier. Vous devriez utiliser ce filtre seulement sur les fichiers texte.
        </para>

        <para>
            Lors de l'initialisation vous pouvez fournir qui sera utilisée en tant
            qu'encodage. Ou vous pouvez utiliser la méthode <methodname>setEncoding()</methodname> pour le
            paramétrer plus tard.
        </para>

        <example id="zend.file.transfer.filters.uppercase.example">
            <title>Utiliser le filtre UpperCase</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('MimeType', 'text');

// Ajoute un filtre pour mettre en majuscule les fichiers textes uploadés
$upload->addFilter('UpperCase');

// Ajoute un filtre pour mettre en majuscule seulement le fichier uploadé "uploadfile1"
$upload->addFilter('UpperCase', null, 'uploadfile1');

// Ajoute un filtre pour mettre en majuscule avec un encodage ISO-8859-1
$upload->addFilter('UpperCase', 'ISO-8859-1');
]]></programlisting>
        </example>

        <note>
            <para>
                Notez que les options du filtre UpperCase sont optionnelles, vous devez
                fournir un <constant>NULL</constant> en second paramètre quand vous souhaitez limiter le
                filtre à un fichier unique.
            </para>
        </note>
    </sect2>
</sect1>