documentation/manual/fr/ref/migration-19.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 20876 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="migration.19">
   5     <title>Zend Framework 1.9</title>
   6
   7     <para>
   8         Lors de la migration d'une version précédente à Zend Framework 1.9.0 vers une version 1.9,
   9         vous devriez prendre note de ce qui suit.
  10     </para>
  11
  12     <sect2 id="migration.19.zend.file.transfer">
  13         <title>Zend_File_Transfer</title>
  14
  15         <sect3 id="migration.110.zend.file.transfer.mimetype">
  16             <title>MimeType validation</title>
  17
  18             <para>
  19                 For security reasons we had to turn off the default fallback mechanism of the
  20                 <classname>MimeType</classname>, <classname>ExcludeMimeType</classname>,
  21                 <classname>IsCompressed</classname> and <classname>IsImage</classname> validators.
  22                 This means, that if the <emphasis>fileInfo</emphasis> or
  23                 <emphasis>magicMime</emphasis> extensions can not be found, the validation will
  24                 always fail.
  25             </para>
  26
  27             <para>
  28                 If you are in need of validation by using the <acronym>HTTP</acronym> fields which
  29                 are provided by the user then you can turn on this feature by using the
  30                 <methodname>enableHeaderCheck()</methodname> method.
  31             </para>
  32
  33             <note>
  34                 <title>Security hint</title>
  35
  36                 <para>
  37                     You should note that relying on the <acronym>HTTP</acronym> fields, which are
  38                     provided by your user, is a security risk. They can easily be changed and could
  39                     allow your user to provide a malcious file.
  40                 </para>
  41             </note>
  42
  43             <example id="migration.110.zend.file.transfer.example">
  44                 <title>Allow the usage of the HTTP fields</title>
  45
  46                 <programlisting language="php"><![CDATA[
  47 // at initiation
  48 $valid = new Zend_File_Transfer_Adapter_Http(array('headerCheck' => true);
  49
  50 // or afterwards
  51 $valid->enableHeaderCheck();
  52 ]]></programlisting>
  53             </example>
  54         </sect3>
  55     </sect2>
  56
  57     <sect2 id="migration.19.zend.filter">
  58         <title>Zend_Filter</title>
  59
  60         <para>
  61             Avant la version 1.9, <classname>Zend_Filter</classname> permettait l'utilisation
  62             de la méthode statique <methodname>get()</methodname>. Avec la version 1.9 cette
  63             méthode a été renommée en <methodname>filterStatic()</methodname> afin d'être plus
  64             descriptive. L'ancienne méthode <methodname>get()</methodname> est marquée comme
  65             dépréciée.
  66         </para>
  67     </sect2>
  68
  69     <sect2 id="migration.19.zend.http.client">
  70         <title>Zend_Http_Client</title>
  71
  72         <sect3 id="migration.19.zend.http.client.fileuploadsarray">
  73             <title>Changement dans le stockage interne des fichiers d'upload</title>
  74
  75             <para>
  76                 Dans la version 1.9 de Zend Framework, il y a eu un changement dans la manière dont
  77                 <classname>Zend_Http_Client</classname> stocke en interne les informations concernant les
  78                 fichiers ayant été uploadés, affectés grâce à <methodname>Zend_Http_Client::setFileUpload()</methodname>
  79             </para>
  80
  81             <para>
  82                 Ce changement a été mis en place de manière à permettre l'envoi de plusieurs fichiers
  83                 avec le même nom dans le formulaire, en tant que tableau de fichiers. Plus d'informations à
  84                 ce sujet peuvent être trouvées dans ce
  85                 <ulink url="http://framework.zend.com/issues/browse/ZF-5744">rapport de bug</ulink>.
  86             </para>
  87
  88             <example id="migration.19.zend.http.client.fileuploadsarray.example">
  89                 <title>Stockage interne des informations sur les fichiers uploadés</title>
  90
  91                 <programlisting language="php"><![CDATA[
  92 // Uploade 2 fichiers avec le même nom d'élément de formulaire, en tant que tableau
  93 $client = new Zend_Http_Client();
  94 $client->setFileUpload('file1.txt', 'userfile[]', 'some raw data', 'text/plain');
  95 $client->setFileUpload('file2.txt', 'userfile[]', 'some other data', 'application/octet-stream');
  96
  97 // Dans Zend Framework <=1.8, la valeur de l'attribut protégé $client->files est:
  98 // $client->files = array(
  99 //     'userfile[]' => array('file2.txt', 'application/octet-stream', 'some other data')
 100 // );
 101
 102 // Dans Zend Framework >=1.9, la valeur de $client->files est:
 103 // $client->files = array(
 104 //     array(
 105 //         'formname' => 'userfile[]',
 106 //         'filename' => 'file1.txt,
 107 //         'ctype'    => 'text/plain',
 108 //         'data'     => 'some raw data'
 109 //     ),
 110 //     array(
 111 //         'formname' => 'userfile[]',
 112 //         'filename' => 'file2.txt',
 113 //         'formname' => 'application/octet-stream',
 114 //         'formname' => 'some other data'
 115 //     )
 116 // );
 117 ]]></programlisting>
 118             </example>
 119
 120             <para>
 121                 Comme vous le voyez, ce changement permet l'utilisation du même élément de formulaire avec plusieurs
 122                 fichiers. Cependant ceci introduit un changement subtile dans l'API interne, il est donc signalé ici.
 123             </para>
 124         </sect3>
 125
 126         <sect3 id="migration.19.zend.http.client.getparamsrecursize">
 127             <title>Deprecation of Zend_Http_Client::_getParametersRecursive()</title>
 128
 129             <para>
 130                 Starting from version 1.9, the protected method <methodname>_getParametersRecursive()</methodname>
 131                 is no longer used by <classname>Zend_Http_Client</classname> and is deprecated.
 132                 Using it will cause an E_NOTICE message to be emitted by <acronym>PHP</acronym>.
 133             </para>
 134
 135             <para>
 136                 If you subclass <classname>Zend_Http_Client</classname> and call this method, you
 137                 should look into using the <methodname>Zend_Http_Client::_flattenParametersArray()</methodname>
 138                 static method instead.
 139             </para>
 140
 141             <para>
 142                 Again, since this <classname>_getParametersRecursive</classname> is a protected method,
 143                 this change will only affect users who subclass <classname>Zend_Http_Client</classname>.
 144             </para>
 145         </sect3>
 146     </sect2>
 147
 148     <sect2 id="migration.19.zend.locale">
 149         <title>Zend_Locale</title>
 150
 151         <sect3 id="migration.19.zend.locale.depreciated">
 152             <title>Méthodes dépréciées</title>
 153
 154             <para>
 155                 Quelques méthodes de traductions spéciales ont été dépréciées car elles dupliquaient
 156                 un comportement existant. Notez cependant que les anciens appels vont toujours
 157                 fonctionner, mais une notice utilisateur, qui décrira le nouvel appel, sera émise.
 158                 Ces méthodes seront effacées en 2.0. Ci-dessous la liste des anciens et nouveaux
 159                 appels&#160;:
 160             </para>
 161
 162             <table id="migration.19.zend.locale.depreciated.table-1">
 163                 <title>Liste des types de mesures</title>
 164
 165                 <tgroup cols="2">
 166                     <thead>
 167                         <row>
 168                             <entry>Ancien appel</entry>
 169                             <entry>Nouvel appel</entry>
 170                         </row>
 171                     </thead>
 172                     <tbody>
 173                         <row>
 174                             <entry>getLanguageTranslationList($locale)</entry>
 175                             <entry>getTranslationList('language', $locale)</entry>
 176                         </row>
 177                         <row>
 178                             <entry>getScriptTranslationList($locale)</entry>
 179                             <entry>getTranslationList('script', $locale)</entry>
 180                         </row>
 181                         <row>
 182                             <entry>getCountryTranslationList($locale)</entry>
 183                             <entry>getTranslationList('territory', $locale, 2)</entry>
 184                         </row>
 185                         <row>
 186                             <entry>getTerritoryTranslationList($locale)</entry>
 187                             <entry>getTranslationList('territory', $locale, 1)</entry>
 188                         </row>
 189                         <row>
 190                             <entry>getLanguageTranslation($value, $locale)</entry>
 191                             <entry>getTranslation($value, 'language', $locale)</entry>
 192                         </row>
 193                         <row>
 194                             <entry>getScriptTranslation($value, $locale)</entry>
 195                             <entry>getTranslation($value, 'script', $locale)</entry>
 196                         </row>
 197                         <row>
 198                             <entry>getCountryTranslation($value, $locale)</entry>
 199                             <entry>getTranslation($value, 'country', $locale)</entry>
 200                         </row>
 201                         <row>
 202                             <entry>getTerritoryTranslation($value, $locale)</entry>
 203                             <entry>getTranslation($value, 'territory', $locale)</entry>
 204                         </row>
 205                     </tbody>
 206                 </tgroup>
 207             </table>
 208         </sect3>
 209     </sect2>
 210
 211     <sect2 id="migration.19.zend.view.helper.navigation">
 212         <title>Zend_View_Helper_Navigation</title>
 213
 214         <para>
 215             Prior to the 1.9 release, the menu helper
 216             (<classname>Zend_View_Helper_Navigation_Menu</classname>) did not
 217             render sub menus correctly. When the <code>onlyActiveBranch</code>
 218             was <constant>TRUE</constant> and the option <code>renderParents</code>
 219             <constant>FALSE</constant>, nothing would be rendered if the deepest active
 220             page was at a depth lower than the <code>minDepth</code> option.
 221         </para>
 222
 223         <para>
 224             In simpler words; if <code>minDepth</code> was set to <code>1</code>
 225             and the active page was at one of the first level pages, nothing
 226             would be rendered, as the following example shows.
 227         </para>
 228
 229         <para>
 230             Consider the following container setup:
 231         </para>
 232
 233         <programlisting language="php"><![CDATA[
 234 $container = new Zend_Navigation(array(
 235     array(
 236         'label' => 'Home',
 237         'uri'   => '#'
 238     ),
 239     array(
 240         'label'  => 'Products',
 241         'uri'    => '#',
 242         'active' => true,
 243         'pages'  => array(
 244             array(
 245                 'label' => 'Server',
 246                 'uri'   => '#'
 247             ),
 248             array(
 249                 'label' => 'Studio',
 250                 'uri'   => '#'
 251             )
 252         )
 253     ),
 254     array(
 255         'label' => 'Solutions',
 256         'uri'   => '#'
 257     )
 258 ));
 259 ]]></programlisting>
 260
 261         <para>
 262             The following code is used in a view script:
 263         </para>
 264
 265         <programlisting language="php"><![CDATA[
 266 echo $this->navigation()->menu()->renderMenu($container, array(
 267     'minDepth'         => 1,
 268     'onlyActiveBranch' => true,
 269     'renderParents'    => false
 270 ));
 271 ]]></programlisting>
 272
 273         <para>
 274             Before release 1.9, the code snippet above would output nothing.
 275         </para>
 276
 277         <para>
 278             Since release 1.9, the <methodname>_renderDeepestMenu()</methodname> method in
 279             <classname>Zend_View_Helper_Navigation_Menu</classname> will accept
 280             active pages at one level below <code>minDepth</code>, as long as
 281             the page has children.
 282         </para>
 283
 284         <para>
 285             The same code snippet will now output the following:
 286         </para>
 287
 288         <programlisting language="html"><![CDATA[
 289 <ul class="navigation">
 290     <li>
 291         <a href="#">Server</a>
 292     </li>
 293     <li>
 294         <a href="#">Studio</a>
 295     </li>
 296 </ul>
 297 ]]></programlisting>
 298     </sect2>
 299
 300     <sect2 id="migration.19.security">
 301         <title>Security fixes as with 1.9.7</title>
 302
 303         <para>
 304             Additionally, users of the 1.9 series may be affected by other changes starting in
 305             version 1.9.7. These are all security fixes that also have potential backwards
 306             compatibility implications.
 307         </para>
 308
 309         <sect3 id="migration.19.security.zend.dojo.editor">
 310             <title>Zend_Dojo_View_Helper_Editor</title>
 311
 312             <para>
 313                 A slight change was made in the 1.9 series to modify the default usage of the Editor
 314                 dijit to use <acronym>div</acronym> tags instead of a <acronym>textarea</acronym>
 315                 tag; the latter usage has <ulink
 316                     url="http://api.dojotoolkit.org/jsdoc/HEAD/dijit._editor.RichText">security
 317                 implications</ulink>, and usage of <acronym>div</acronym> tags is recommended by the
 318                 Dojo project.
 319             </para>
 320
 321             <para>
 322                 In order to still allow graceful degradation, a new <varname>degrade</varname>
 323                 option was added to the view helper; this would allow developers to optionally use a
 324                 <acronym>textarea</acronym> instead. However, this opens applications developed with
 325                 that usage to <acronym>XSS</acronym> vectors. In 1.9.7, we have removed this option.
 326                 Graceful degradation is still supported, however, via a <acronym>noscript</acronym>
 327                 tag that embeds a <acronym>textarea</acronym>. This solution addressess all security
 328                 concerns.
 329             </para>
 330
 331             <para>
 332                 The takeaway is that if you were using the <varname>degrade</varname> flag, it will
 333                 simply be ignored at this time.
 334             </para>
 335         </sect3>
 336
 337         <sect3 id="migration.19.security.zend.filter.html-entities">
 338             <title>Zend_Filter_HtmlEntities</title>
 339
 340             <para>
 341                 In order to default to a more secure character encoding,
 342                 <classname>Zend_Filter_HtmlEntities</classname> now defaults to
 343                 <acronym>UTF-8</acronym> instead of <acronym>ISO-8859-1</acronym>.
 344             </para>
 345
 346             <para>
 347                 Additionally, because the actual mechanism is dealing with character encodings and
 348                 not character sets, two new methods have been added,
 349                 <methodname>setEncoding()</methodname> and <methodname>getEncoding()</methodname>.
 350                 The previous methods <methodname>setCharSet()</methodname> and
 351                 <methodname>setCharSet()</methodname> are now deprecated and proxy to the new
 352                 methods. Finally, instead of using the protected members directly within the
 353                 <methodname>filter()</methodname> method, these members are retrieved by their
 354                 explicit accessors. If you were extending the filter in the past, please check your
 355                 code and unit tests to ensure everything still continues to work.
 356             </para>
 357         </sect3>
 358
 359         <sect3 id="migration.19.security.zend.filter.strip-tags">
 360             <title>Zend_Filter_StripTags</title>
 361
 362             <para>
 363                 <classname>Zend_Filter_StripTags</classname> contains a flag,
 364                 <varname>commentsAllowed</varname>, that, in previous versions, allowed you to
 365                 optionally whitelist HTML comments in HTML text filtered by the class. However, this
 366                 opens code enabling the flag to <acronym>XSS</acronym> attacks, particularly in
 367                 Internet Explorer (which allows specifying conditional functionality via HTML
 368                 comments). Starting in version 1.9.7 (and backported to versions 1.8.5 and 1.7.9),
 369                 the <varname>commentsAllowed</varname> flag no longer has any meaning, and all HTML
 370                 comments, including those containing other HTML tags or nested commments, will be
 371                 stripped from the final output of the filter.
 372             </para>
 373         </sect3>
 374     </sect2>
 375 </sect1>