repo_zf1/documentation/manual/fr/module_specs/Zend_File_Transfer-Migration.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 17175 -->
<!-- Reviewed: no -->
<sect1 id="zend.file.transfer.migration">
    <title>Migrer à partir des versions précédentes</title>

    <para>
        L'API de <classname>Zend_File_Transfer</classname> a changé au cours du temps. Si vous
        avez commencé à utiliser <classname>Zend_File_Transfer</classname> et ses sous-composants
        avec les versions précédentes, suivez les lignes directrices ci-dessous pour migrer vos
        scripts et ainsi utiliser la nouvelle <acronym>API</acronym>.
    </para>

    <sect2 id="zend.file.transfer.migration.fromonesixtooneseven">
        <title>Migrer de la version 1.6 vers 1.7 ou plus récent</title>

        <sect3 id="zend.file.transfer.migration.fromonesixtooneseven.validators">
            <title>Changements quand vous utilisez des filtres ou des validateurs</title>

            <para>
                Certaines remarques des utilisateurs indiquaient que les validateurs de
                <classname>Zend_File_Transfer</classname> ne fonctionnaient pas correctement avec
                <classname>Zend_Config</classname> dû au fait qu'ils n'utilisait pas de tableaux
                nommés.
            </para>

            <para>
                De plus, tous les filtres et validateurs de
                <classname>Zend_File_Transfer</classname> ont été réécrits. Même si les anciennes
                signatures continuent à fonctionner, elles ont été marqués comme dépréciées et
                émettent une notice <acronym>PHP</acronym> vous informant de faire le changement.
            </para>

            <para>
                La liste suivante vous montre les changements à réaliser pour une utilisation
                appropriée des paramètres.
            </para>

            <sect4 id="zend.file.transfer.migration.fromonesixtooneseven.validators.rename">
                <title>Filtre Rename</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Ancienne <acronym>API</acronym>&#160;: <classname>Zend_Filter_File_Rename($oldfile,
                            $newfile, $overwrite)</classname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Nouvelle <acronym>API</acronym>&#160;:
                            <methodname>Zend_Filter_File_Rename($options)</methodname> où
                            <varname>$options</varname> accepte un tableau avec les clés suivantes :
                            <emphasis>source</emphasis> est équivalent à <varname>$oldfile</varname>,
                            <emphasis>target</emphasis> est équivalent à <varname>$newfile</varname>,
                            <emphasis>overwrite</emphasis> est équivalent à
                            <code>$overwrite.</code>
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.validators.rename.example">
                    <title>Changer le filtre rename entre 1.6 et 1.7</title>

                    <programlisting language="php"><![CDATA[
// Exemple pour 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addFilter('Rename',
                   array('/path/to/oldfile', '/path/to/newfile', true));

// Même exemple pour 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addFilter('Rename',
                   array('source' => '/path/to/oldfile',
                         'target' => '/path/to/newfile',
                         'overwrite' => true));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.file.transfer.migration.fromonesixtooneseven.validators.count">
                <title>Validateur Count</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Ancienne <acronym>API</acronym>&#160;: <classname>Zend_Validate_File_Count($min,
                            $max)</classname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Nouvelle <acronym>API</acronym>&#160;:
                            <methodname>Zend_Validate_File_Count($options)</methodname> où
                            <varname>$options</varname> accepte un tableau avec les clés suivantes :
                            <emphasis>min</emphasis> est équivalent à <varname>$min</varname>,
                            <emphasis>max</emphasis> est équivalent à <varname>$max</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.validators.count.example">
                    <title>Changer le validateur count entre 1.6 et 1.7</title>

                    <programlisting language="php"><![CDATA[
// Exemple pour 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Count',
                      array(2, 3));

// Même exemple pour 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Count',
                      false,
                      array('min' => 2,
                            'max' => 3));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.file.transfer.migration.fromonesixtooneseven.validators.extension">
                <title>Validateur Extension</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Ancienne <acronym>API</acronym>&#160;: <classname>Zend_Validate_File_Extension($extension,
                            $case)</classname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Nouvelle <acronym>API</acronym>&#160;:
                            <methodname>Zend_Validate_File_Extension($options)</methodname> où
                            <varname>$options</varname> accepte un tableau avec les clés suivantes :
                            <emphasis>*</emphasis> est équivalent à <varname>$extension</varname> et peut
                            avoir tout autre clé, <emphasis>case</emphasis> est équivalent à
                            <varname>$case</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.validators.extension.example">
                    <title>Changer le validateur extension entre 1.6 et 1.7</title>

                    <programlisting language="php"><![CDATA[
// Exemple pour 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Extension',
                   array('jpg,gif,bmp', true));

// Même exemple pour 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Extension',
                      false,
                      array('extension1' => 'jpg,gif,bmp',
                            'case' => true));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.file.transfer.migration.fromonesixtooneseven.validators.filessize">
                <title>Validateur FilesSize</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Ancienne <acronym>API</acronym>&#160;: <classname>Zend_Validate_File_FilesSize($min, $max,
                            $bytestring)</classname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Nouvelle <acronym>API</acronym>&#160;:
                            <methodname>Zend_Validate_File_FilesSize($options)</methodname> où
                            <varname>$options</varname> accepte un tableau avec les clés suivantes :
                            <emphasis>min</emphasis> est équivalent à <varname>$min</varname>,
                            <emphasis>max</emphasis> est équivalent à <varname>$max</varname>,
                            <emphasis>bytestring</emphasis> est équivalent à
                            <varname>$bytestring</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <para>
                    De plus la signature de la méthode <methodname>useByteString()</methodname> a changé.
                    Elle peut être seulement utilisée pour tester si le validateur prévoie
                    d'utiliser les chaînes lisibles ou la valeur brute dans les messages générées.
                    Pour paramétrer la valeur de cette option, utilisez la méthode
                    <methodname>setUseByteString()</methodname>.
                </para>

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.validators.filessize.example">
                    <title>Changer le validateur filessize entre 1.6 et 1.7</title>

                    <programlisting language="php"><![CDATA[
// Exemple pour 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('FilesSize',
                      array(100, 10000, true));

// Même exemple pour 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('FilesSize',
                      false,
                      array('min' => 100,
                            'max' => 10000,
                            'bytestring' => true));

// Exemple pour 1.6
$upload->useByteString(true); // set flag

// Même exemple pour 1.7
$upload->setUseByteSting(true); // set flag
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.file.transfer.migration.fromonesixtooneseven.validators.hash">
                <title>Validateur Hash</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Ancienne <acronym>API</acronym>&#160;: <classname>Zend_Validate_File_Hash($hash,
                            $algorithm)</classname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Nouvelle <acronym>API</acronym>&#160;:
                            <methodname>Zend_Validate_File_Hash($options)</methodname> où
                            <varname>$options</varname> accepte un tableau avec les clés suivantes :
                            <emphasis>*</emphasis> est équivalent à <varname>$hash</varname> et peut avoir
                            tout autre clé, <emphasis>algorithm</emphasis> est équivalent à
                            <varname>$algorithm</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.validators.hash.example">
                    <title>Changer le validateur hash entre 1.6 et 1.7</title>

                    <programlisting language="php"><![CDATA[
// Exemple pour 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Hash',
                      array('12345', 'md5'));

// Même exemple pour 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Hash',
                      false,
                      array('hash1' => '12345',
                            'algorithm' => 'md5'));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.file.transfer.migration.fromonesixtooneseven.validators.imagesize">
                <title>Validateur ImageSize</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Ancienne <acronym>API</acronym>&#160;: <classname>Zend_Validate_File_ImageSize($minwidth,
                            $minheight, $maxwidth, $maxheight)</classname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Nouvelle <acronym>API</acronym>&#160;:
                            <methodname>Zend_Validate_File_FilesSize($options)</methodname> où
                            <varname>$options</varname> accepte un tableau avec les clés suivantes&#160;:
                            <emphasis>minwidth</emphasis> est équivalent à <varname>$minwidth</varname>,
                            <emphasis>maxwidth</emphasis> est équivalent à <varname>$maxwidth</varname>,
                            <emphasis>minheight</emphasis> est équivalent à <varname>$minheight</varname>,
                            <emphasis>maxheight</emphasis> est équivalent à
                            <varname>$maxheight</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.validators.imagesize.example">
                    <title>Changer le validateur imagesize entre 1.6 et 1.7</title>

                    <programlisting language="php"><![CDATA[
// Exemple pour 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('ImageSize',
                      array(10, 10, 100, 100));

// Même exemple pour 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('ImageSize',
                      false,
                      array('minwidth' => 10,
                            'minheight' => 10,
                            'maxwidth' => 100,
                            'maxheight' => 100));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.file.transfer.migration.fromonesixtooneseven.validators.size">
                <title>Validateur Size</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Ancienne <acronym>API</acronym>&#160;: <classname>Zend_Validate_File_Size($min, $max,
                            $bytestring)</classname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Nouvelle <acronym>API</acronym>&#160;:
                            <methodname>Zend_Validate_File_Size($options)</methodname> où
                            <varname>$options</varname> accepte un tableau avec les clés suivantes&#160;:
                            <emphasis>min</emphasis> est équivalent à <varname>$min</varname>,
                            <emphasis>max</emphasis> est équivalent à <varname>$max</varname>,
                            <emphasis>bytestring</emphasis> est équivalent à
                            <varname>$bytestring</varname>
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.validators.size.example">
                    <title>Changer le validateur size entre 1.6 et 1.7</title>

                    <programlisting language="php"><![CDATA[
// Exemple pour 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Size',
                      array(100, 10000, true));

// Même exemple pour 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Size',
                      false,
                      array('min' => 100,
                            'max' => 10000,
                            'bytestring' => true));
]]></programlisting>
                </example>
            </sect4>
        </sect3>
    </sect2>

    <sect2 id="zend.file.transfer.migration.fromonesixonetoonesixtwo">
        <title>Migrer de la version 1.6.1 vers 1.6.2 ou plus récent</title>

        <sect3 id="zend.file.transfer.migration.fromonesixonetoonesixtwo.validators">
            <title>Changements quand vous utilisez des validateurs</title>

            <para>
                Certaines remarques des utilisateurs indiquaient que les validateurs de
                <classname>Zend_File_Transfer</classname> ne fonctionnaient pas comme ceux par
                défaut fournis avec <classname>Zend_Form</classname>.
                <classname>Zend_Form</classname> permet par exemple l'utilisation du paramètre
                <code>breakChainOnFailure</code> qui stoppe la validation de tous les validateurs
                suivants dès qu'une erreur de validation apparaît.
            </para>

            <para>
                Nous avons donc ajouter ce paramètre à tous les validateurs existants pour
                <classname>Zend_File_Transfer</classname>.
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        Ancienne <acronym>API</acronym>&#160;: <code>addValidator($validator, $options,
                        $files)</code>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Nouvelle <acronym>API</acronym>&#160;: <code>addValidator($validator, $breakChainOnFailure,
                        $options, $files)</code>.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Pour migrer vos scripts vers la nouvelle <acronym>API</acronym>, ajoutez simplement un a
                <constant>FALSE</constant> après voir défini le validateur souhaité.
            </para>

            <example id="zend.file.transfer.migration.fromonesixonetoonesixtwo.example">
                <title>Changer les validateurs de fichiers de 1.6.1 vers 1.6.2</title>

                <programlisting language="php"><![CDATA[
// Exemple pour 1.6.1
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('FilesSize', array('1B', '100kB'));

// Même exemple pour 1.6.2 et plus récent
// Notez l'ajout du booléen false
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('FilesSize', false, array('1B', '100kB'));
]]></programlisting>
            </example>
        </sect3>
    </sect2>
</sect1>