repo_zf1/documentation/manual/fr/ref/migration-17.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="migration.17">
    <title>Zend Framework 1.7</title>

    <para>
        Lors de la migration d'un version précédente vers Zend Framework 1.7 ou plus récent
        vous devriez prendre note de ce qui suit.
    </para>

    <sect2 id="migration.17.zend.controller">
        <title>Zend_Controller</title>

        <sect3 id="migration.17.zend.controller.dispatcher">
            <title>Changement dans l'interface Dispatcher</title>

            <para>
                Les utilisateurs ont portés l'attention sur le fait que
                <classname>Zend_Controller_Action_Helper_ViewRenderer</classname> utilisait une
                méthode de la classe abstraite du distributeur standard qui n'était pas présente
                dans l'interface Dispatcher.La méthode suivante a donc été ajoutée pour s'assurer
                que les distributeurs personnalisés continueront à fonctionner avec les
                implémentations embarquées&#160;:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>formatModuleName()</methodname>&#160;: devrait être utilisé pour prendre
                        un nom de contrôleur brut, comme un qui aurait été embarqué dans un objet
                        requête, et pour le formater en un nom de classe approprié qu'une classe
                        étendant <classname>Zend_Controller_Action</classname> pourra
                        utiliser.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>

    <sect2 id="migration.17.zend.file.transfer">
        <title>Zend_File_Transfer</title>

        <sect3 id="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.file.transfer.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="migration.17.zend.locale">
        <title>Zend_Locale</title>

        <sect3 id="migration.17.zend.locale.islocale">
            <title>Changement dans l'utilisation de isLocale()</title>

            <para>
                Conformément aux standards de codage <methodname>isLocale()</methodname> a été changé pour
                retourner un booléen. Dans les versions précédentes une chaîne était retournée lors
                du succès. Pour la version 1.7 un mode de compatibilité a été ajouté qui vous permet
                d'utiliser l'ancien comportement (avec une chaîne retournée), mais ceci émet un
                warning pour vous informer de changer vers le nouveau comportement. Le reroutage que
                l'ancien comportement de <methodname>isLocale()</methodname> pouvait avoir à faire n'est plus
                nécessaire car tous les composants de l'I18N traiteront maintenant eux-mêmes le
                reroutage.
            </para>

            <para>
                Pour migrer vos scripts vers la nouvelle <acronym>API</acronym>, utilisez simplement la méthode
                décrite ci-dessous.
            </para>

            <example id="migration.17.zend.locale.example">
                <title>Comment changer l'appel de isLocale() de 1.6 vers 1.7 ?</title>

                <programlisting language="php"><![CDATA[
// Exemple pour ZF 1.6
if ($locale = Zend_Locale::isLocale($locale)) {
    // faire qqch
}

// Même exemple pour ZF 1.7

// Vous devez changer le mode de compatibilité pour empêcher l'émission de warning
// Mais ceci peut être fait dans votre bootstrap
Zend_Locale::$compatibilityMode = false;

if (Zend_Locale::isLocale($locale)) {
}
]]></programlisting>

                <para>
                    Notez que vous pouvez utiliser le second paramètre pour voir si la locale
                    est correcte sans nécessiter de reroutage.
                </para>

                <programlisting language="php"><![CDATA[
// Exemple pour ZF 1.6
if ($locale = Zend_Locale::isLocale($locale, false)) {
    // do something
}

// Même exemple pour ZF 1.7

// Vous devez changer le mode de compatibilité pour empêcher l'émission de warning
// Mais ceci peut être fait dans votre bootstrap
Zend_Locale::$compatibilityMode = false;

if (Zend_Locale::isLocale($locale, false)) {
    if (Zend_Locale::isLocale($locale, true)) {
        // pas de locale du tout
    }

    // original string is no locale but can be rerouted
}
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="migration.17.zend.locale.getdefault">
            <title>Changement dans l'utilisation de getDefault()</title>

            <para>
                La signification de la méthode <methodname>getDefault()</methodname> a été changé étant
                donné que nous avons intégré une locale de framework qui peut être paramétrée avec
                <methodname>setDefault()</methodname>. Ceci ne renvoie plus la chaîne de la locale mais
                seulement la locale du framework.
            </para>

            <para>
                Pour migrer vos scripts vers la nouvelle <acronym>API</acronym>, utilisez simplement la méthode
                décrite ci-dessous.
            </para>

            <example id="migration.17.zend.locale.getdefault.example">
                <title>Comment changer l'appel de getDefaut() de 1.6 vers 1.7 ?</title>

                <programlisting language="php"><![CDATA[
// Exemple pour ZF 1.6
$locales = $locale->getDefault(Zend_Locale::BROWSER);

// Même exemple pour ZF 1.7

// Vous devez changer le mode de compatibilité pour empêcher l'émission de warning
// Mais ceci peut être fait dans votre bootstrap
Zend_Locale::$compatibilityMode = false;

$locale = Zend_Locale::getOrder(Zend_Locale::BROWSER);
]]></programlisting>

                <para>
                    Notez que le second paramètre de l'ancienne implémentation de
                    <methodname>getDefault()</methodname> n'est plus disponible non plus, mais les valeurs
                    retournées sont les mêmes.
                </para>
            </example>

            <note>
                <para>
                    Par défaut l'ancien comportement est toujours actif, mais émet un warning.
                    Quand vous avez changé votre code vers le nouveau comportement, vous devriez
                    aussi changer le mode de compatibilité à <constant>FALSE</constant> ainsi aucun nouveau
                    warning ne sera émis.
                </para>
            </note>
        </sect3>
    </sect2>

    <sect2 id="migration.17.zend.translate">
        <title>Zend_Translate</title>

        <sect3 id="migration.17.zend.translate.languages">
            <title>Paramétrer les langues</title>

            <para>
                Lors de l'utilisation de la détection automatique des langues, ou du réglage
                manuel des langues de <classname>Zend_Translate</classname>, vous avez peut-être
                remarqué que de temps en temps une notice est envoyée concernant le non-ajout de
                traductions vides. Dans certaines versions précédentes, une exception était levée
                dans certains cas.
            </para>

            <para>
                Ceci intervient quand un utilisateur requête une langue non existante, vous
                n'avez alors aucun moyen simple de détecter ce qui ne va pas. Nous avons donc ajouté
                ces notices qui apparaîtront dans votre historisation et qui vous diront qu'un
                utilisateur a requêté une langue que vous ne supportez pas. Notez bien que votre
                code, même si une notice est déclenchée, fonctionnera sans problèmes.
            </para>

            <para>
                Mais quand vous utilisez votre propre gestionnaire d'erreur ou d'exception,
                comme xDebug, toutes les notices vous seront retournées, même si ce n'est pas votre
                intention initiale. Ceci est du au fait, que ces gestionnaires surchargent tous les
                réglages internes de <acronym>PHP</acronym>.
            </para>

            <para>
                Pour vous affranchir de ces notices, vous pouvez simplement paramétrer la
                nouvelle option <code>disableNotices</code> à <constant>TRUE</constant>, sa valeur par
                défaut étant <constant>FALSE</constant>.
            </para>

            <example id="migration.17.zend.translate.example">
                <title>Paramétrer les langues sans avoir de notices</title>

                <para>
                    Assumons que "<code>fr</code>" soit disponible et qu'un utilisateur
                    requête pour "<code>de</code>" qui ne fait pas partie de votre portefeuille de
                    traductions.
                </para>

                <programlisting language="php"><![CDATA[
$language = new Zend_Translate('gettext',
                               '/chemin/vers/les/traductions',
                               'auto');
]]></programlisting>

                <para>
                    Dans ce cas nous aurons une notice indiquant la non-disponibilité de la
                    langue "<code>de</code>". Ajoutez simplement l'option et les notices seront
                    désactivées.
                </para>

                <programlisting language="php"><![CDATA[
$language = new Zend_Translate('gettext',
                               '/chemin/vers/les/traductions',
                               'auto',
                               array('disableNotices' => true));
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="migration.17.zend.view">
        <title>Zend_View</title>

        <note>
            <para>
                Les changements de l'API de <classname>Zend_View</classname> sont seulement
                notables pour vous si vous mettez à jour vers les version 1.7.5 ou plus récent.
            </para>
        </note>

        <para>
            Avant la version 1.7.5, l'équipe de Zend Framework a été avertie d'une faille
            potentielle d'inclusion de fichier local ("Local File Inclusion" (LFI)) dans la méthode
            <methodname>Zend_View::render()</methodname>. Avant 1.7.5, la méthode acceptait par défaut
            la possibilité de spécifier des scripts de vue comportant des indications de dossier
            parent (comme, "../" ou "..\"). Ceci ouvre la possibilité à une attaque LFI si des
            données utilisateurs non filtrées sont passées directement à la méthode
            <methodname>render()</methodname>:
        </para>

        <programlisting language="php"><![CDATA[
// Ici, $_GET['foobar'] = '../../../../etc/passwd'
echo $view->render($_GET['foobar']); // inclusion LFI
]]></programlisting>

        <para>
            <classname>Zend_View</classname> émet maintenant une exception dans un tel
            cas.
        </para>

        <sect3 id="zend.view.migration.zf5748.disabling">
            <title>Désactiver la protection LFI de render()</title>

            <para>
                Comme des développeurs utilisaient de telles notations, mais qui n'étaient
                <emphasis>pas</emphasis> des données en provenance de l'extérieur, un drapeau
                spécial a été crée, il permet de désactiver la protection. Pour manipuler ce
                drapeau, il existe 2 moyens&#160;: le paramètre 'lfiProtectionOn' du constructeur de
                votre vue, ou encore la méthode <methodname>setLfiProtection()</methodname>.
            </para>

            <programlisting language="php"><![CDATA[
// Désactivation de la protection par le constructeur
$view = new Zend_View(array('lfiProtectionOn' => false));

// Désactivation de la protection par la méthode dédiée
$view = new Zend_View();
$view->setLfiProtection(false);
]]></programlisting>
        </sect3>
    </sect2>
</sect1>