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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="migration.19">
   4     <title>Zend Framework 1.9</title>
   5
   6     <para>
   7         When upgrading from a release of Zend Framework earlier than 1.9.0 to any 1.9 release, you
   8         should note the following migration notes.
   9     </para>
  10
  11     <sect2 id="migration.19.zend.file.transfer">
  12         <title>Zend_File_Transfer</title>
  13
  14         <sect3 id="migration.19.zend.file.transfer.mimetype">
  15             <title>MimeType validation</title>
  16
  17             <para>
  18                 For security reasons we had to turn off the default fallback mechanism of the
  19                 <classname>MimeType</classname>, <classname>ExcludeMimeType</classname>,
  20                 <classname>IsCompressed</classname> and <classname>IsImage</classname> validators.
  21                 This means, that if the <emphasis>fileInfo</emphasis> or
  22                 <emphasis>magicMime</emphasis> extensions can not be found, the validation will
  23                 always fail.
  24             </para>
  25
  26             <para>
  27                 If you are in need of validation by using the <acronym>HTTP</acronym> fields which
  28                 are provided by the user then you can turn on this feature by using the
  29                 <methodname>enableHeaderCheck()</methodname> method.
  30             </para>
  31
  32             <note>
  33                 <title>Security hint</title>
  34
  35                 <para>
  36                     You should note that relying on the <acronym>HTTP</acronym> fields, which are
  37                     provided by your user, is a security risk. They can easily be changed and could
  38                     allow your user to provide a malcious file.
  39                 </para>
  40             </note>
  41
  42             <example id="migration.19.zend.file.transfer.example">
  43                 <title>Allow the usage of the HTTP fields</title>
  44
  45                 <programlisting language="php"><![CDATA[
  46 // at initiation
  47 $valid = new Zend_File_Transfer_Adapter_Http(array('headerCheck' => true);
  48
  49 // or afterwards
  50 $valid->enableHeaderCheck();
  51 ]]></programlisting>
  52             </example>
  53         </sect3>
  54     </sect2>
  55
  56     <sect2 id="migration.19.zend.filter">
  57         <title>Zend_Filter</title>
  58
  59         <para>
  60             Prior to the 1.9 release, <classname>Zend_Filter</classname> allowed
  61             the usage of the static <methodname>get()</methodname> method. As with
  62             release 1.9 this method has been renamed to
  63             <methodname>filterStatic()</methodname> to be more descriptive. The
  64             old <methodname>get()</methodname> method is marked as deprecated.
  65         </para>
  66     </sect2>
  67
  68     <sect2 id="migration.19.zend.http.client">
  69         <title>Zend_Http_Client</title>
  70
  71         <sect3 id="migration.19.zend.http.client.fileuploadsarray">
  72             <title>Changes to internal uploaded file information storage</title>
  73
  74             <para>
  75                 In version 1.9 of Zend Framework, there has been a change in the way
  76                 <classname>Zend_Http_Client</classname> internally stores information about
  77                 files to be uploaded, set using the
  78                 <methodname>Zend_Http_Client::setFileUpload()</methodname> method.
  79             </para>
  80
  81             <para>
  82                 This change was introduced in order to allow multiple files to be uploaded
  83                 with the same form name, as an array of files. More information about this issue
  84                 can be found in <ulink
  85                     url="http://framework.zend.com/issues/browse/ZF-5744">this bug report</ulink>.
  86             </para>
  87
  88             <example id="migration.19.zend.http.client.fileuploadsarray.example">
  89                 <title>Internal storage of uploaded file information</title>
  90
  91                 <programlisting language="php"><![CDATA[
  92 // Upload two files with the same form element name, as an array
  93 $client = new Zend_Http_Client();
  94 $client->setFileUpload('file1.txt',
  95                        'userfile[]',
  96                        'some raw data',
  97                        'text/plain');
  98 $client->setFileUpload('file2.txt',
  99                        'userfile[]',
 100                        'some other data',
 101                        'application/octet-stream');
 102
 103 // In Zend Framework 1.8 or older, the value of
 104 // the protected member $client->files is:
 105 // $client->files = array(
 106 //     'userfile[]' => array('file2.txt',
 107                              'application/octet-stream',
 108                              'some other data')
 109 // );
 110
 111 // In Zend Framework 1.9 or newer, the value of $client->files is:
 112 // $client->files = array(
 113 //     array(
 114 //         'formname' => 'userfile[]',
 115 //         'filename' => 'file1.txt,
 116 //         'ctype'    => 'text/plain',
 117 //         'data'     => 'some raw data'
 118 //     ),
 119 //     array(
 120 //         'formname' => 'userfile[]',
 121 //         'filename' => 'file2.txt',
 122 //         'formname' => 'application/octet-stream',
 123 //         'formname' => 'some other data'
 124 //     )
 125 // );
 126 ]]></programlisting>
 127             </example>
 128
 129             <para>
 130                 As you can see, this change permits the usage of the same form element name with
 131                 more than one file - however, it introduces a subtle backwards-compatibility change
 132                 and as such should be noted.
 133             </para>
 134         </sect3>
 135
 136         <sect3 id="migration.19.zend.http.client.getparamsrecursize">
 137             <title>Deprecation of Zend_Http_Client::_getParametersRecursive()</title>
 138
 139             <para>
 140                 Starting from version 1.9, the protected method
 141                 <methodname>_getParametersRecursive()</methodname> is no longer used by
 142                 <classname>Zend_Http_Client</classname> and is deprecated. Using it will cause an
 143                 <constant>E_NOTICE</constant> message to be emitted by <acronym>PHP</acronym>.
 144             </para>
 145
 146             <para>
 147                 If you subclass <classname>Zend_Http_Client</classname> and call this method, you
 148                 should look into using the
 149                 <methodname>Zend_Http_Client::_flattenParametersArray()</methodname> static method
 150                 instead.
 151             </para>
 152
 153             <para>
 154                 Again, since this <methodname>_getParametersRecursive()</methodname> is a protected
 155                 method, this change will only affect users who subclass
 156                 <classname>Zend_Http_Client</classname>.
 157             </para>
 158         </sect3>
 159     </sect2>
 160
 161     <sect2 id="migration.19.zend.locale">
 162         <title>Zend_Locale</title>
 163
 164         <sect3 id="migration.19.zend.locale.deprecated">
 165             <title>Deprecated methods</title>
 166
 167             <para>
 168                 Some specialized translation methods have been deprecated because they duplicate
 169                 existing behaviour. Note that the old methods will still work, but a user notice is
 170                 triggered which describes the new call. The methods will be erased with 2.0.
 171                 See the following list for old and new method call.
 172             </para>
 173
 174             <table id="migration.19.zend.locale.deprecated.table-1">
 175                 <title>List of measurement types</title>
 176
 177                 <tgroup cols="2">
 178                     <thead>
 179                         <row>
 180                             <entry>Old call</entry>
 181                             <entry>New call</entry>
 182                         </row>
 183                     </thead>
 184
 185                     <tbody>
 186                         <row>
 187                             <entry>
 188                                 <methodname>getLanguageTranslationList($locale)</methodname>
 189                             </entry>
 190
 191                             <entry>
 192                                 <methodname>getTranslationList('language', $locale)</methodname>
 193                             </entry>
 194                         </row>
 195
 196                         <row>
 197                             <entry>
 198                                 <methodname>getScriptTranslationList($locale)</methodname>
 199                             </entry>
 200
 201                             <entry>
 202                                 <methodname>getTranslationList('script', $locale)</methodname>
 203                             </entry>
 204                         </row>
 205
 206                         <row>
 207                             <entry>
 208                                 <methodname>getCountryTranslationList($locale)</methodname>
 209                             </entry>
 210
 211                             <entry>
 212                                 <methodname>getTranslationList('territory', $locale, 2)</methodname>
 213                             </entry>
 214                         </row>
 215
 216                         <row>
 217                             <entry>
 218                                 <methodname>getTerritoryTranslationList($locale)</methodname>
 219                             </entry>
 220
 221                             <entry>
 222                                 <methodname>getTranslationList('territory', $locale, 1)</methodname>
 223                             </entry>
 224                         </row>
 225
 226                         <row>
 227                             <entry>
 228                                 <methodname>getLanguageTranslation($value, $locale)</methodname>
 229                             </entry>
 230
 231                             <entry>
 232                                 <methodname>getTranslation($value, 'language', $locale)</methodname>
 233                             </entry>
 234                         </row>
 235
 236                         <row>
 237                             <entry>
 238                                 <methodname>getScriptTranslation($value, $locale)</methodname>
 239                             </entry>
 240
 241                             <entry>
 242                                 <methodname>getTranslation($value, 'script', $locale)</methodname>
 243                             </entry>
 244                         </row>
 245
 246                         <row>
 247                             <entry>
 248                                 <methodname>getCountryTranslation($value, $locale)</methodname>
 249                             </entry>
 250
 251                             <entry>
 252                                 <methodname>getTranslation($value, 'country', $locale)</methodname>
 253                             </entry>
 254                         </row>
 255
 256                         <row>
 257                             <entry>
 258                                 <methodname>getTerritoryTranslation($value, $locale)</methodname>
 259                             </entry>
 260
 261                             <entry>
 262                                 <methodname>getTranslation($value, 'territory',
 263                                     $locale)</methodname>
 264                             </entry>
 265                         </row>
 266                     </tbody>
 267                 </tgroup>
 268             </table>
 269         </sect3>
 270     </sect2>
 271
 272     <sect2 id="migration.19.zend.view.helper.navigation">
 273         <title>Zend_View_Helper_Navigation</title>
 274
 275         <para>
 276             Prior to the 1.9 release, the menu helper
 277             (<classname>Zend_View_Helper_Navigation_Menu</classname>) did not
 278             render sub menus correctly. When <property>onlyActiveBranch</property>
 279             was <constant>TRUE</constant> and the option <property>renderParents</property>
 280             <constant>FALSE</constant>, nothing would be rendered if the deepest active
 281             page was at a depth lower than the <property>minDepth</property> option.
 282         </para>
 283
 284         <para>
 285             In simpler words; if <property>minDepth</property> was set to '1'
 286             and the active page was at one of the first level pages, nothing
 287             would be rendered, as the following example shows.
 288         </para>
 289
 290         <para>
 291             Consider the following container setup:
 292         </para>
 293
 294         <programlisting language="php"><![CDATA[
 295 <?php
 296 $container = new Zend_Navigation(array(
 297     array(
 298         'label' => 'Home',
 299         'uri'   => '#'
 300     ),
 301     array(
 302         'label'  => 'Products',
 303         'uri'    => '#',
 304         'active' => true,
 305         'pages'  => array(
 306             array(
 307                 'label' => 'Server',
 308                 'uri'   => '#'
 309             ),
 310             array(
 311                 'label' => 'Studio',
 312                 'uri'   => '#'
 313             )
 314         )
 315     ),
 316     array(
 317         'label' => 'Solutions',
 318         'uri'   => '#'
 319     )
 320 ));
 321 ]]></programlisting>
 322
 323         <para>
 324             The following code is used in a view script:
 325         </para>
 326
 327         <programlisting language="php"><![CDATA[
 328 <?php echo $this->navigation()->menu()->renderMenu($container, array(
 329     'minDepth'         => 1,
 330     'onlyActiveBranch' => true,
 331     'renderParents'    => false
 332 )); ?>
 333 ]]></programlisting>
 334
 335         <para>
 336             Before release 1.9, the code snippet above would output nothing.
 337         </para>
 338
 339         <para>
 340             Since release 1.9, the <methodname>_renderDeepestMenu()</methodname> method in
 341             <classname>Zend_View_Helper_Navigation_Menu</classname> will accept
 342             active pages at one level below <property>minDepth</property>, as long as
 343             the page has children.
 344         </para>
 345
 346         <para>
 347             The same code snippet will now output the following:
 348         </para>
 349
 350         <programlisting language="html"><![CDATA[
 351 <ul class="navigation">
 352     <li>
 353         <a href="#">Server</a>
 354     </li>
 355     <li>
 356         <a href="#">Studio</a>
 357     </li>
 358 </ul>
 359 ]]></programlisting>
 360     </sect2>
 361
 362     <sect2 id="migration.19.security">
 363         <title>Security fixes as with 1.9.7</title>
 364
 365         <para>
 366             Additionally, users of the 1.9 series may be affected by other changes starting in
 367             version 1.9.7. These are all security fixes that also have potential backwards
 368             compatibility implications.
 369         </para>
 370
 371         <sect3 id="migration.19.security.zend.dojo.editor">
 372             <title>Zend_Dojo_View_Helper_Editor</title>
 373
 374             <para>
 375                 A slight change was made in the 1.9 series to modify the default usage of the Editor
 376                 dijit to use <acronym>div</acronym> tags instead of a <acronym>textarea</acronym>
 377                 tag; the latter usage has <ulink
 378                     url="http://api.dojotoolkit.org/jsdoc/HEAD/dijit._editor.RichText">security
 379                 implications</ulink>, and usage of <acronym>div</acronym> tags is recommended by the
 380                 Dojo project.
 381             </para>
 382
 383             <para>
 384                 In order to still allow graceful degradation, a new <varname>degrade</varname>
 385                 option was added to the view helper; this would allow developers to optionally use a
 386                 <acronym>textarea</acronym> instead. However, this opens applications developed with
 387                 that usage to <acronym>XSS</acronym> vectors. In 1.9.7, we have removed this option.
 388                 Graceful degradation is still supported, however, via a <acronym>noscript</acronym>
 389                 tag that embeds a <acronym>textarea</acronym>. This solution addressess all security
 390                 concerns.
 391             </para>
 392
 393             <para>
 394                 The takeaway is that if you were using the <varname>degrade</varname> flag, it will
 395                 simply be ignored at this time.
 396             </para>
 397         </sect3>
 398
 399         <sect3 id="migration.19.security.zend.filter.html-entities">
 400             <title>Zend_Filter_HtmlEntities</title>
 401
 402             <para>
 403                 In order to default to a more secure character encoding,
 404                 <classname>Zend_Filter_HtmlEntities</classname> now defaults to
 405                 <acronym>UTF-8</acronym> instead of <acronym>ISO-8859-1</acronym>.
 406             </para>
 407
 408             <para>
 409                 Additionally, because the actual mechanism is dealing with character encodings and
 410                 not character sets, two new methods have been added,
 411                 <methodname>setEncoding()</methodname> and <methodname>getEncoding()</methodname>.
 412                 The previous methods <methodname>setCharSet()</methodname> and
 413                 <methodname>setCharSet()</methodname> are now deprecated and proxy to the new
 414                 methods. Finally, instead of using the protected members directly within the
 415                 <methodname>filter()</methodname> method, these members are retrieved by their
 416                 explicit accessors. If you were extending the filter in the past, please check your
 417                 code and unit tests to ensure everything still continues to work.
 418             </para>
 419         </sect3>
 420
 421         <sect3 id="migration.19.security.zend.filter.strip-tags">
 422             <title>Zend_Filter_StripTags</title>
 423
 424             <para>
 425                 <classname>Zend_Filter_StripTags</classname> contains a flag,
 426                 <varname>commentsAllowed</varname>, that, in previous versions, allowed you to
 427                 optionally whitelist <acronym>HTML</acronym> comments in <acronym>HTML</acronym>
 428                 text filtered by the class. However, this opens code enabling the flag to
 429                 <acronym>XSS</acronym> attacks, particularly in Internet Explorer (which allows
 430                 specifying conditional functionality via <acronym>HTML</acronym> comments). Starting
 431                 in version 1.9.7 (and backported to versions 1.8.5 and 1.7.9), the
 432                 <varname>commentsAllowed</varname> flag no longer has any meaning, and all
 433                 <acronym>HTML</acronym> comments, including those containing other
 434                 <acronym>HTML</acronym> tags or nested commments, will be stripped from the final
 435                 output of the filter.
 436             </para>
 437         </sect3>
 438     </sect2>
 439 </sect1>
 440 <!--
 441 vim:se ts=4 sw=4 et:
 442 -->