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

    <para>
        <classname>Zend_File_Transfer</classname> permet aux développeurs de contrôler
        l'upload de fichiers mais aussi le téléchargement. Il vous permet d'utiliser les validateurs
        incorporés pour le traitement de fichier et même la possibilité de changer les fichiers avec
        des filtres. <classname>Zend_File_Transfer</classname> fonctionne avec des adaptateurs ce
        qui vous permet d'utiliser la même <acronym>API</acronym> pour différents protocoles de transfert <acronym>HTTP</acronym>, FTP,
        WEBDAV et plus encore.
    </para>

    <note>
        <title>Limitation</title>

        <para>
            L'implémentation actuelle de <classname>Zend_File_Transfer</classname> est limitée
            aux uploads de type <acronym>HTTP</acronym> Post. Le téléchargement de fichiers et les autres adaptateurs
            seront ajoutés dans les prochaines versions. Les méthodes non implémentées pour le
            moment lèveront une exception. Donc réellement vous devriez directement utiliser une
            instance de <classname>Zend_File_Transfer_Adapter_Http</classname>. Ceci changera dans
            le futur, dès qu'il existera des adaptateurs disponibles.
        </para>
    </note>

    <note>
        <title>Formulaires</title>

        <para>
            Quand vous utilisez <classname>Zend_Form</classname> vous devriez lire et suivre
            les exemples décrits dans le chapitre <classname>Zend_Form</classname> et ne pas
            utiliser manuellement <classname>Zend_File_Transfer</classname>. Mais les informations
            que vous pourrez lire dans le présent chapitre vous seront malgré tout utile, même si
            vous ne l'utilisez pas directement. Toutes les considérations, descriptions et solutions
            sont les mêmes quand vous utilisez <classname>Zend_File_Transfer</classname> au travers
            de <classname>Zend_Form</classname>.
        </para>
    </note>

    <para>
        L'utilisation de <classname>Zend_File_Transfer</classname> est assez simple. Il
        consiste en deux parties. Le formulaire <acronym>HTTP</acronym> qui réalise l'upload, et la gestion des
        fichiers uploadés avec <classname>Zend_File_Transfer</classname>. Regardez l'exemple suivant
        :
    </para>

    <example id="zend.file.transfer.introduction.example">
        <title>Formulaire simple d'upload de fichier</title>

        <para>
            Cet exemple illustre un upload de fichier basique avec
            <classname>Zend_File_Transfer</classname>. La première partie est le formulaire. Dans
            notre exemple, il n'y a qu'un seul fichier que nous souhaitons uploadé.
        </para>

        <programlisting><![CDATA[
<form enctype="multipart/form-data" action="/file/upload" method="POST">
    <input type="hidden" name="MAX_FILE_SIZE" value="100000" />
        Choose a file to upload:
        <input name="uploadedfile" type="file" />
        <br />
    <input type="submit" value="Upload File" />
</form>
]]></programlisting>

        <para>
            Notez que vous devriez utiliser <link
            linkend="zend.form.standardElements.file">Zend_Form_Element_File</link> par simplicité
            plutôt que de créer le HTML manuellement.
        </para>

        <para>
            L'étape suivante est de créer le récepteur de l'upload. Dans notre exemple le
            récepteur est "<code>/file/upload</code>". Donc nous créons le contrôleur
            <code>file</code> avec l'action <code>upload</code>.
        </para>

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

$adapter->setDestination('C:\temp');

if (!$adapter->receive()) {
    $messages = $adapter->getMessages();
    echo implode("\n", $messages);
}
]]></programlisting>

        <para>
            Comme vous le voyez, l'utilisation la plus simple est de définir une destination
            avec la méthode <code>setDestination</code> et d'appeler la méthode
            <methodname>receive()</methodname>. S'il apparaît des erreurs au cours de l'upload, alors vous les
            récupérerez grâce à une exception qui sera retournée.
        </para>
    </example>

    <note>
        <title>Attention</title>

        <para>
            Maintenez à l'esprit qu'il s'agit de l'utilisation la plus simple. Vous
            <emphasis>ne devez jamais</emphasis> utiliser cet exemple en environnement de production
            car il causerait de graves problèmes de sécurité. Vous devez toujours utiliser des
            validateurs pour accroître la sécurité.
        </para>
    </note>

    <sect2 id="zend.file.transfer.introduction.adapters">
        <title>Adaptateurs supportés par Zend_File_Transfer</title>

        <para>
            <classname>Zend_File_Transfer</classname> est construit pour supporter différents
            adaptateurs et différentes directions. Il est conçu pour permettre l'upload, le
            téléchargement et même l'envoi bidirectionnel (upload avec un adaptateur et télécharge
            avec un autre adaptateur en même temps) de fichiers.
        </para>
    </sect2>

    <sect2 id="zend.file.transfer.introduction.options">
        <title>Options de Zend_File_Transfer</title>

        <para>
            <classname>Zend_File_Transfer</classname> et ses adaptateurs supportent plusieurs
            options. Vous pouvez paramétrer toutes les options soit en les fournissant au
            constructeur, ou en utilisant <methodname>setOptions($options)</methodname>.
            <methodname>getOptions()</methodname> retournera les options actuellement paramétrées. Ci-dessous,
            vous trouverez la liste des options supportées :
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>ignoreNoFile</code> : si cette option vaut <constant>TRUE</constant>, tous
                    les validateurs ignoreront le fait que le fichier à été uploadé ou non par le
                    formulaire. Cette option vaut par défaut <constant>FALSE</constant>, ce qui lance une
                    erreur indiquant que le fichier n'a pas été fourni.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.file.transfer.introduction.checking">
        <title>Vérification des fichiers</title>

        <para>
            <classname>Zend_File_Transfer</classname> possède plusieurs méthodes qui
            permettent de vérifier suivant différentes considérations. Ceci est particulièrement
            utile quand vous devez travailler avec des fichiers qui ont été uploadés.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>isValid($files = null)</methodname> : cette méthode vérifie si le(s)
                    fichier(s) est(sont) valide(s), en se basant sur les validateurs affectés à
                    chacun de ces fichiers. Si aucun fichier n'est fourni, tous les fichiers seront
                    vérifiés. Notez que cette méthode sera appelée en dernier quand les fichiers
                    seront reçus.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>isUploaded($files = null)</methodname> : cette méthode vérifie si le(s)
                    fichier(s) fourni(s) a (ont) été uploadé(s) par l'utilisateur. Ceci est utile si
                    vous avez défini que certains fichiers sont optionnels. Si aucun fichier n'est
                    fourni, tous les fichiers seront vérifiés.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>isReceived($files = null)</methodname> : cette méthode vérifie si le(s)
                    fichier(s) fourni(s) a (ont) bien été reçu(s). Si aucun fichier n'est fourni,
                    tous les fichiers seront vérifiés.
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.introduction.checking.example">
            <title>Vérification de fichiers</title>

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

// Retourne toutes les informations connues sur le fichier
$files = $upload->getFileInfo();

foreach ($files as $file => $info) {
    // Fichier uploadé ?
    if (!$upload->isUploaded($file)) {
        print "Pourquoi n'avez-vous pas uploadé ce fichier ?";
        continue;
    }

    // Les validateurs sont-ils OK ?
    if (!$upload->isValid($file)) {
        print "Désolé mais $file ne correspond à ce que nous attendons";
        continue;
    }
}

$upload->receive();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.file.transfer.introduction.informations">
        <title>Informations complémentaires sur les fichiers</title>

        <para>
            <classname>Zend_File_Transfer</classname> peut fournir de multiples informations
            complémentaires sur les fichiers. Les méthodes suivantes sont disponibles :
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getFileName($file = null, $path = true)</methodname> : cette méthode
                    retourne le vrai nom de fichier d'un fichier transféré.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getFileInfo($file = null)</methodname> : cette méthode retourne tous les
                    informations internes concernant un fichier transféré donné.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getFileSize($file = null) </code>: cette méthode retourne la taille
                    réelle d'un fichier transféré donné.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getHash($hash = 'crc32', $files = null) </code>: cette méthode
                    retourne la valeur de hachage du contenu d'un fichier transféré donné.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getMimeType($files = null)</methodname> : cette méthode retourne le type
                    <acronym>MIME</acronym> d'un fichier transféré donné.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            <methodname>getFileName()</methodname> accepte le nom d'un élément entant que premier
            paramètre. Si aucun n'est fourni, tous les fichiers connus seront retournées sous la
            forme d'un tableau. Si le fichier est un "multifile", vous le récupérerez aussi sous la
            forme d'un tableau. S'il n'y a qu'un seul fichier alors une chaîne sera
            retournée.
        </para>

        <para>
            Par défaut les noms de fichier sont retournés avec leur chemin d'accès complet. Si
            vous souhaitez seulement le nom de fichier sans le chemin, vous pouvez paramétrer le
            second paramètre <varname>$path</varname> à <constant>FALSE</constant> ce qui tronquera le
            chemin.
        </para>

        <example id="zend.file.transfer.introduction.informations.example1">
            <title>Récupération du nom de fichier</title>

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

// Retourne le nom de fichier pour tous les fichiers
$names = $upload->getFileName();

// Retourne le nom de fichier de l'élément de formulaire "foo"
$names = $upload->getFileName('foo');
]]></programlisting>
        </example>

        <note>
            <para>
                Notez que le nom de fichier peut changer quand vous recevez le fichier. Ceci
                est du au fait qu'après la réception, tous les filtres sot appliqués. Donc vous ne
                devriez appeler <methodname>getFileName()</methodname> qu'après avoir reçu les fichiers.
            </para>
        </note>

        <para>
            <methodname>getFileSize()</methodname> retourne par défaut la taille réelle d'un fichier en
            notation SI ce qui signifie que vous récupérerez <code>2kB</code> au lieu de
            <constant>2048</constant>. Si vous voulez la taille brute, utilisez l'option
            <code>useByteString</code> à <constant>FALSE</constant>.
        </para>

        <example id="zend.file.transfer.introduction.informations.example.getfilesize">
            <title>Récupération de la taille de fichier</title>

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

// Retourne les tailles de tous les fichiers sous la forme
// d'un tableau si plus d'un fichier a été uploadé
$size = $upload->getFileSize();

// Bascule de la notation SI vers une taille brute
$upload->setOptions(array('useByteString' => false));
$size = $upload->getFileSize();
]]></programlisting>
        </example>

        <note>
            <title>Client given filesize</title>

            <para>
                Note that the filesize which is given by the client is not seen as save input.
                Therefor the real size of the file will be detected and returned instead of the
                filesize sent by the client.
            </para>
        </note>

        <para>
            <methodname>getHash()</methodname> accepte le nom de l'algorithme de hachage en tant que
            premier paramètre. Pour avoir une liste des algorithmes connus, regardez <ulink
            url="http://php.net/manual/fr/function.hash-algos.php">la méthode hash_algos de
            <acronym>PHP</acronym></ulink>. Si vous ne fournissez aucun algorithme, celui par défaut sera
            <code>crc32</code>.
        </para>

        <example id="zend.file.transfer.introduction.informations.example2">
            <title>Récupération d'un hash de fichier</title>

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

// Retourne le hachage de fichier pour tous les fichiers sous la forme
// d'un tableau si plusieurs fichiers sont fournis
$hash = $upload->getHash('md5');

// Retourne le hachage de l'élément de formulaire "foo"
$names = $upload->getHash('crc32', 'foo');
]]></programlisting>
        </example>

        <note>
            <title>Valeur retournée</title>

            <para>
                Notez que si un fichier ou un élément de formulaire donné contient plus d'un
                fichier, la valeur retournée sera un tableau.
            </para>
        </note>

        <para>
            <methodname>getMimeType()</methodname> retourne le type <acronym>MIME</acronym> d'un fichier. Si plus d'un
            fichier a été uploadé, elle retourne un tableau, sinon c'est une chaîne.
        </para>

        <example id="zend.file.transfer.introduction.informations.getmimetype">
            <title>Récupération du type MIME de fichier</title>

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

$mime = $upload->getMimeType();

// Retourne le type MIME pour l'élément de formulaire "foo"
$names = $upload->getMimeType('foo');
]]></programlisting>
        </example>

         <note>
            <title>Client given mimetype</title>

             <para>
                Note that the mimetype which is given by the client is not seen as save input.
                Therefor the real mimetype of the file will be detected and returned instead of the
                mimetype sent by the client.
            </para>
        </note>

        <warning>
            <title>Exception possible</title>

            <para>
                Notez que cette méthode utilise l'extension fileinfo si elle est disponible.
                Si elle n'est pas trouvé, elle utilise l'extension mimemagic. Quand aucune extension
                n'est fournie, une exception est levée.
            </para>
        </warning>

        <warning>
            <title>Original data within $_FILES</title>

            <para>
                Due to security reasons also the original data within $_FILES will be overridden
                as soon as <classname>Zend_File_Transfer</classname> is initiated. When you want
                to omit this behaviour and have the original data simply set the
                <property>detectInfos</property> option to <constant>FALSE</constant> at initiation.
            </para>

            <para>
                This option will have no effect after you initiated
                <classname>Zend_File_Transfer</classname>.
            </para>
        </warning>
    </sect2>

    <sect2 id="zend.file.transfer.introduction.uploadprogress">
        <title>Progress for file uploads</title>

        <para>
            <classname>Zend_File_Transfer</classname> can give you the actual state of a fileupload in progress. To use
            this feature you need either the <constant>APC</constant> extension which is provided with most default
            <acronym>PHP</acronym> installations, or the <code>uploadprogress</code> extension. Both extensions are detected
            and used automatically. To be able to get the progress you need to meet some prerequisites.
        </para>

        <para>
            First, you need to have either <constant>APC</constant> or <code>uploadprogress</code> to be enabled.
            Note that you can disable this feature of <constant>APC</constant> within your php.ini.
        </para>

        <para>
            Second, you need to have the proper hidden fields added in the form which sends the files. When you
            use <classname>Zend_Form_Element_File</classname> this hidden fields are automatically added by
            <classname>Zend_Form</classname>.
        </para>

        <para>
            When the above two points are provided then you are able to get the actual progress of the
            file upload by using the <code>getProgress</code> method. Actually there are 2 official ways to
            handle this.
        </para>

        <sect3 id="zend.file.transfer.introduction.uploadprogress.progressadapter">
            <title>Using a progressbar adapter</title>

            <para>
                You can use the convinient <emphasis>Zend_ProgressBar</emphasis> to get the actual progress
                and can display it in a simple manner to your user.
            </para>

            <para>
                To archive this, you have to add the wished <emphasis>Zend_ProgressBar_Adapter</emphasis> to
                <methodname>getProgress()</methodname> when you are calling it the first time. For details about the right
                adapter to use, look into the chapter
                <link linkend="zend.progressbar.adapters">Zend_ProgressBar Standard Adapters</link>.
            </para>

            <example id="zend.file.transfer.introduction.uploadprogress.progressadapter.example1">
                <title>Using the progressbar adapter to retrieve the actual state</title>

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

$upload = null;
while (!$upload['done']) {
    $upload = Zend_File_Transfer_Adapter_Http:getProgress($upload);
}
]]></programlisting>
            </example>

            <para>
                The complete handling is done by <methodname>getProgress()</methodname> for you in the background.
            </para>
        </sect3>

        <sect3 id="zend.file.transfer.introduction.uploadprogress.manually">
            <title>Using getProgress() manually</title>

            <para>
                You can also work manually with <methodname>getProgress()</methodname> without the usage of
                <classname>Zend_ProgressBar</classname>.
            </para>

            <para>
                Call <methodname>getProgress()</methodname> without settings. It will return you an array with several keys.
                They differ according to the used <acronym>PHP</acronym> extension. But the following keys are given independently
                of the extension:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>id</emphasis>: The ID of this upload. This ID identifies the
                        upload within the extension. You can set it to the value of the hidden key
                        which identified the upload when initially calling
                        <methodname>getProgress()</methodname>. Per default it is set to
                        <emphasis>progress_key</emphasis>. You must not change the ID afterwards.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>total</emphasis>: The total filesize of the uploaded files in bytes
                        as integer.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>current</emphasis>: The current uploaded filesize in bytes
                        as integer.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>rate</emphasis>: The average upload speed in bytes per second
                        as integer.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>done</emphasis>: Returns true when the upload is finished and false
                        otherwise.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>message</emphasis>: The actual message. Eighter the progress as
                        text in the form <emphasis>10kB / 200kB</emphasis>, or a helpful message
                        in the case of a problem. Problems could be, that there is no upload in progress, that
                        there was a failure while retrieving the data for the progress, or that the upload has
                        been canceled.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>progress</emphasis>: This optional key takes a instance of
                        Zend_ProgressBar_Adapter or Zend_ProgressBar and allows to get the actual upload state
                        within a progressbar.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>session</emphasis>: This optional key takes the name of a session
                        namespace which will be used within Zend_ProgressBar. When this key is not given it
                        defaults to <classname>Zend_File_Transfer_Adapter_Http_ProgressBar</classname>.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                All other returned keys are provided directly from the extensions and will not be checked.
            </para>

            <para>
                The following example shows a possible manual usage:
            </para>

            <example id="zend.file.transfer.introduction.uploadprogress.manually.example1">
                <title>Manual usage of the file progress</title>

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

while (!$upload['done']) {
    $upload = Zend_File_Transfer_Adapter_Http:getProgress($upload);
    print "\nActual progress:".$upload['message'];
    // do whatever you need
}
]]></programlisting>
            </example>

            <note>
                <title>Knowing the file to get the progress from</title>

                <para>
                    The above example works when your upload identified is set to 'progress_key'.
                    When you are using another identifier within your form you must give the used
                    identifier as first parameter to <methodname>getProgress()</methodname> on the
                    initial call.
                </para>
            </note>
        </sect3>
    </sect2>
</sect1>