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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="migration.17">
   4     <title>Zend Framework 1.7</title>
   5
   6     <para>
   7         When upgrading from a previous release to Zend Framework 1.7 or higher you
   8         should note the following migration notes.
   9     </para>
  10
  11     <sect2 id="migration.17.zend.controller">
  12         <title>Zend_Controller</title>
  13
  14         <sect3 id="migration.17.zend.controller.dispatcher">
  15             <title>Dispatcher Interface Changes</title>
  16
  17             <para>
  18                 Users brought to our attention the fact that
  19                 <classname>Zend_Controller_Action_Helper_ViewRenderer</classname> were
  20                 using a method of the dispatcher abstract class that was not in
  21                 the dispatcher interface. We have now added the following method to
  22                 ensure that custom dispatchers will continue to work with the
  23                 shipped implementations:
  24             </para>
  25
  26             <itemizedlist>
  27                 <listitem>
  28                     <para>
  29                         <methodname>formatModuleName()</methodname>: should be used to take a raw
  30                         controller name, such as one that would be packaged inside a request
  31                         object, and reformat it to a proper class name that a class extending
  32                         <classname>Zend_Controller_Action</classname> would use
  33                     </para>
  34                 </listitem>
  35             </itemizedlist>
  36         </sect3>
  37     </sect2>
  38
  39     <sect2 id="migration.17.zend.file.transfer">
  40         <title>Zend_File_Transfer</title>
  41
  42         <sect3 id="migration.17.zend.file.transfer.validators">
  43             <title>Changes when using filters and validators</title>
  44
  45             <para>
  46                 As noted by users, the validators from <classname>Zend_File_Transfer</classname>
  47                 do not work in conjunction with <classname>Zend_Config</classname> due to the fact
  48                 that they have not used named arrays.
  49             </para>
  50
  51             <para>
  52                 Therefor, all filters and validators for <classname>Zend_File_Transfer</classname>
  53                 have been reworked. While the old signatures continue to work,
  54                 they have been marked as deprecated, and will emit a <acronym>PHP</acronym> notice
  55                 asking you to fix them.
  56             </para>
  57
  58             <para>
  59                 The following list shows you the changes you will have to do for proper
  60                 usage of the parameters.
  61             </para>
  62
  63             <sect4 id="migration.17.zend.file.transfer.validators.rename">
  64                 <title>Filter: Rename</title>
  65
  66                 <itemizedlist>
  67                     <listitem>
  68                         <para>
  69                             Old method <acronym>API</acronym>:
  70                             <methodname>Zend_Filter_File_Rename($oldfile, $newfile,
  71                                 $overwrite)</methodname>
  72                         </para>
  73                     </listitem>
  74
  75                     <listitem>
  76                         <para>
  77                             New method <acronym>API</acronym>:
  78                             <methodname>Zend_Filter_File_Rename($options)</methodname>
  79                             where <varname>$options</varname> accepts the following array keys:
  80                             <emphasis>source</emphasis> equals to <varname>$oldfile</varname>,
  81                             <emphasis>target</emphasis> equals to <varname>$newfile</varname>,
  82                             <emphasis>overwrite</emphasis> equals to <varname>$overwrite</varname>.
  83                         </para>
  84                     </listitem>
  85                 </itemizedlist>
  86
  87                 <example id="migration.17.zend.file.transfer.validators.rename.example">
  88                     <title>Changes for the rename filter from 1.6 to 1.7</title>
  89
  90                     <programlisting language="php"><![CDATA[
  91 // Example for 1.6
  92 $upload = new Zend_File_Transfer_Adapter_Http();
  93 $upload->addFilter('Rename',
  94                    array('/path/to/oldfile', '/path/to/newfile', true));
  95
  96 // Same example for 1.7
  97 $upload = new Zend_File_Transfer_Adapter_Http();
  98 $upload->addFilter('Rename',
  99                    array('source' => '/path/to/oldfile',
 100                          'target' => '/path/to/newfile',
 101                          'overwrite' => true));
 102 ]]></programlisting>
 103                 </example>
 104             </sect4>
 105
 106             <sect4 id="migration.17.zend.file.transfer.validators.count">
 107                 <title>Validator: Count</title>
 108
 109                 <itemizedlist>
 110                     <listitem>
 111                         <para>
 112                             Old method <acronym>API</acronym>:
 113                             <methodname>Zend_Validate_File_Count($min, $max)</methodname>
 114                         </para>
 115                     </listitem>
 116
 117                     <listitem>
 118                         <para>
 119                             New method <acronym>API</acronym>:
 120                             <methodname>Zend_Validate_File_Count($options)</methodname>
 121                             where <varname>$options</varname> accepts the following array keys:
 122                             <emphasis>min</emphasis> equals to <varname>$min</varname>,
 123                             <emphasis>max</emphasis> equals to <varname>$max</varname>.
 124                         </para>
 125                     </listitem>
 126                 </itemizedlist>
 127
 128                 <example id="migration.17.zend.file.transfer.validators.count.example">
 129                     <title>Changes for the count validator from 1.6 to 1.7</title>
 130
 131                     <programlisting language="php"><![CDATA[
 132 // Example for 1.6
 133 $upload = new Zend_File_Transfer_Adapter_Http();
 134 $upload->addValidator('Count',
 135                       array(2, 3));
 136
 137 // Same example for 1.7
 138 $upload = new Zend_File_Transfer_Adapter_Http();
 139 $upload->addValidator('Count',
 140                       false,
 141                       array('min' => 2,
 142                             'max' => 3));
 143 ]]></programlisting>
 144                 </example>
 145             </sect4>
 146
 147             <sect4 id="migration.17.zend.file.transfer.validators.extension">
 148                 <title>Validator:Extension</title>
 149
 150                 <itemizedlist>
 151                     <listitem>
 152                         <para>
 153                             Old method <acronym>API</acronym>:
 154                             <methodname>Zend_Validate_File_Extension($extension, $case)</methodname>
 155                         </para>
 156                     </listitem>
 157
 158                     <listitem>
 159                         <para>
 160                             New method <acronym>API</acronym>:
 161                             <methodname>Zend_Validate_File_Extension($options)</methodname> where
 162                             <varname>$options</varname> accepts the following array keys:
 163                             <emphasis>*</emphasis> equals to <varname>$extension</varname> and can
 164                             have any other key, <emphasis>case</emphasis> equals to
 165                             <varname>$case</varname>.
 166                         </para>
 167                     </listitem>
 168                 </itemizedlist>
 169
 170                 <example id="migration.17.zend.file.transfer.validators.extension.example">
 171                     <title>Changes for the extension validator from 1.6 to 1.7</title>
 172
 173                     <programlisting language="php"><![CDATA[
 174 // Example for 1.6
 175 $upload = new Zend_File_Transfer_Adapter_Http();
 176 $upload->addValidator('Extension',
 177                       array('jpg,gif,bmp', true));
 178
 179 // Same example for 1.7
 180 $upload = new Zend_File_Transfer_Adapter_Http();
 181 $upload->addValidator('Extension',
 182                       false,
 183                       array('extension1' => 'jpg,gif,bmp',
 184                             'case' => true));
 185 ]]></programlisting>
 186                 </example>
 187             </sect4>
 188
 189             <sect4 id="migration.17.zend.file.transfer.validators.filessize">
 190                 <title>Validator: FilesSize</title>
 191
 192                 <itemizedlist>
 193                     <listitem>
 194                         <para>
 195                             Old method <acronym>API</acronym>:
 196                             <methodname>Zend_Validate_File_FilesSize($min, $max,
 197                                 $bytestring)</methodname>
 198                         </para>
 199                     </listitem>
 200
 201                     <listitem>
 202                         <para>
 203                             New method <acronym>API</acronym>:
 204                             <methodname>Zend_Validate_File_FilesSize($options)</methodname> where
 205                             <varname>$options</varname> accepts the following array keys:
 206                             <emphasis>min</emphasis> equals to <varname>$min</varname>,
 207                             <emphasis>max</emphasis> equals to <varname>$max</varname>,
 208                             <emphasis>bytestring</emphasis> equals to
 209                             <varname>$bytestring</varname>.
 210                         </para>
 211                     </listitem>
 212                 </itemizedlist>
 213
 214                 <para>
 215                     Additionally, the <methodname>useByteString()</methodname> method
 216                     signature has changed. It can only be used to test if the
 217                     validator is expecting to use byte strings in generated
 218                     messages. To set the value of the flag, use the
 219                     <methodname>setUseByteString()</methodname> method.
 220                 </para>
 221
 222                 <example id="migration.17.zend.file.transfer.validators.filessize.example">
 223                     <title>Changes for the filessize validator from 1.6 to 1.7</title>
 224
 225                     <programlisting language="php"><![CDATA[
 226 // Example for 1.6
 227 $upload = new Zend_File_Transfer_Adapter_Http();
 228 $upload->addValidator('FilesSize',
 229                    array(100, 10000, true));
 230
 231 // Same example for 1.7
 232 $upload = new Zend_File_Transfer_Adapter_Http();
 233 $upload->addValidator('FilesSize',
 234                       false,
 235                       array('min' => 100,
 236                             'max' => 10000,
 237                             'bytestring' => true));
 238
 239 // Example for 1.6
 240 $upload->useByteString(true); // set flag
 241
 242 // Same example for 1.7
 243 $upload->setUseByteSting(true); // set flag
 244 ]]></programlisting>
 245                 </example>
 246             </sect4>
 247
 248             <sect4 id="migration.17.zend.file.transfer.validators.hash">
 249                 <title>Validator: Hash</title>
 250
 251                 <itemizedlist>
 252                     <listitem>
 253                         <para>
 254                             Old method <acronym>API</acronym>:
 255                             <methodname>Zend_Validate_File_Hash($hash, $algorithm)</methodname>
 256                         </para>
 257                     </listitem>
 258
 259                     <listitem>
 260                         <para>
 261                             New method <acronym>API</acronym>:
 262                             <methodname>Zend_Validate_File_Hash($options)</methodname>
 263                             where <varname>$options</varname> accepts the following array keys:
 264                             <emphasis>*</emphasis> equals to <varname>$hash</varname> and can have
 265                             any other key, <emphasis>algorithm</emphasis> equals to
 266                             <varname>$algorithm</varname>.
 267                         </para>
 268                     </listitem>
 269                 </itemizedlist>
 270
 271                 <example id="migration.17.zend.file.transfer.validators.hash.example">
 272                     <title>Changes for the hash validator from 1.6 to 1.7</title>
 273
 274                     <programlisting language="php"><![CDATA[
 275 // Example for 1.6
 276 $upload = new Zend_File_Transfer_Adapter_Http();
 277 $upload->addValidator('Hash',
 278                    array('12345', 'md5'));
 279
 280 // Same example for 1.7
 281 $upload = new Zend_File_Transfer_Adapter_Http();
 282 $upload->addValidator('Hash',
 283                       false,
 284                       array('hash1' => '12345',
 285                             'algorithm' => 'md5'));
 286 ]]></programlisting>
 287                 </example>
 288             </sect4>
 289
 290             <sect4 id="migration.17.zend.file.transfer.validators.imagesize">
 291                 <title>Validator: ImageSize</title>
 292
 293                 <itemizedlist>
 294                     <listitem>
 295                         <para>
 296                             Old method <acronym>API</acronym>:
 297                             <methodname>Zend_Validate_File_ImageSize($minwidth, $minheight,
 298                                 $maxwidth, $maxheight)</methodname>
 299                         </para>
 300                     </listitem>
 301
 302                     <listitem>
 303                         <para>
 304                             New method <acronym>API</acronym>:
 305                             <methodname>Zend_Validate_File_FilesSize($options)</methodname> where
 306                             <varname>$options</varname> accepts the following array keys:
 307                             <emphasis>minwidth</emphasis> equals to <varname>$minwidth</varname>,
 308                             <emphasis>maxwidth</emphasis> equals to <varname>$maxwidth</varname>,
 309                             <emphasis>minheight</emphasis> equals to <varname>$minheight</varname>,
 310                             <emphasis>maxheight</emphasis> equals to <varname>$maxheight</varname>.
 311                         </para>
 312                     </listitem>
 313                 </itemizedlist>
 314
 315                 <example id="migration.17.zend.file.transfer.validators.imagesize.example">
 316                     <title>Changes for the imagesize validator from 1.6 to 1.7</title>
 317
 318                     <programlisting language="php"><![CDATA[
 319 // Example for 1.6
 320 $upload = new Zend_File_Transfer_Adapter_Http();
 321 $upload->addValidator('ImageSize',
 322                       array(10, 10, 100, 100));
 323
 324 // Same example for 1.7
 325 $upload = new Zend_File_Transfer_Adapter_Http();
 326 $upload->addValidator('ImageSize',
 327                       false,
 328                       array('minwidth' => 10,
 329                             'minheight' => 10,
 330                             'maxwidth' => 100,
 331                             'maxheight' => 100));
 332 ]]></programlisting>
 333                 </example>
 334             </sect4>
 335
 336             <sect4 id="migration.17.zend.file.transfer.validators.size">
 337                 <title>Validator: Size</title>
 338
 339                 <itemizedlist>
 340                     <listitem>
 341                         <para>
 342                             Old method <acronym>API</acronym>:
 343                                 <methodname>Zend_Validate_File_Size($min, $max,
 344                                 $bytestring)</methodname>
 345                         </para>
 346                     </listitem>
 347
 348                     <listitem>
 349                         <para>
 350                             New method <acronym>API</acronym>:
 351                             <methodname>Zend_Validate_File_Size($options)</methodname>
 352                             where <varname>$options</varname> accepts the following array keys:
 353                             <emphasis>min</emphasis> equals to <varname>$min</varname>,
 354                             <emphasis>max</emphasis> equals to <varname>$max</varname>,
 355                             <emphasis>bytestring</emphasis> equals to
 356                             <varname>$bytestring</varname>.
 357                         </para>
 358                     </listitem>
 359                 </itemizedlist>
 360
 361                 <example id="migration.17.zend.file.transfer.validators.size.example">
 362                     <title>Changes for the size validator from 1.6 to 1.7</title>
 363
 364                     <programlisting language="php"><![CDATA[
 365 // Example for 1.6
 366 $upload = new Zend_File_Transfer_Adapter_Http();
 367 $upload->addValidator('Size',
 368                       array(100, 10000, true));
 369
 370 // Same example for 1.7
 371 $upload = new Zend_File_Transfer_Adapter_Http();
 372 $upload->addValidator('Size',
 373                       false,
 374                       array('min' => 100,
 375                             'max' => 10000,
 376                             'bytestring' => true));
 377 ]]></programlisting>
 378                 </example>
 379             </sect4>
 380         </sect3>
 381     </sect2>
 382
 383     <sect2 id="migration.17.zend.locale">
 384         <title>Zend_Locale</title>
 385
 386         <sect3 id="migration.17.zend.locale.islocale">
 387             <title>Changes when using isLocale()</title>
 388
 389             <para>
 390                 According to the coding standards <methodname>isLocale()</methodname> had to be
 391                 changed to return a boolean. In previous releases a string was returned on success.
 392                 For release 1.7 a compatibility mode has been added which allows to use the
 393                 old behaviour of a returned string, but it triggers a user warning to
 394                 mention you to change to the new behaviour. The rerouting which the old
 395                 behaviour of <methodname>isLocale()</methodname> could have done is no longer
 396                 neccessary as all I18n will now process a rerouting themself.
 397             </para>
 398
 399             <para>
 400                 To migrate your scripts to the new <acronym>API</acronym>, simply use the method as
 401                 shown below.
 402             </para>
 403
 404             <example id="migration.17.zend.locale.islocale.example">
 405                 <title>How to change isLocale() from 1.6 to 1.7</title>
 406
 407                 <programlisting language="php"><![CDATA[
 408 // Example for 1.6
 409 if ($locale = Zend_Locale::isLocale($locale)) {
 410     // do something
 411 }
 412
 413 // Same example for 1.7
 414
 415 // You should change the compatiblity mode to prevent user warnings
 416 // But you can do this in your bootstrap
 417 Zend_Locale::$compatibilityMode = false;
 418
 419 if (Zend_Locale::isLocale($locale)) {
 420 }
 421 ]]></programlisting>
 422
 423                 <para>
 424                     Note that you can use the second parameter to see if the locale is correct
 425                     without processing a rerouting.
 426                 </para>
 427
 428                 <programlisting language="php"><![CDATA[
 429 // Example for 1.6
 430 if ($locale = Zend_Locale::isLocale($locale, false)) {
 431     // do something
 432 }
 433
 434 // Same example for 1.7
 435
 436 // You should change the compatiblity mode to prevent user warnings
 437 // But you can do this in your bootstrap
 438 Zend_Locale::$compatibilityMode = false;
 439
 440 if (Zend_Locale::isLocale($locale, false)) {
 441     if (Zend_Locale::isLocale($locale, true)) {
 442         // no locale at all
 443     }
 444
 445     // original string is no locale but can be rerouted
 446 }
 447 ]]></programlisting>
 448             </example>
 449         </sect3>
 450
 451         <sect3 id="migration.17.zend.locale.islocale.getdefault">
 452             <title>Changes when using getDefault()</title>
 453
 454             <para>
 455                 The meaning of the <methodname>getDefault()</methodname> method has been change due
 456                 to the fact that we integrated a framework locale which can be set with
 457                 <methodname>setDefault()</methodname>. It does no longer return the locale chain
 458                 but only the set framework locale.
 459             </para>
 460
 461             <para>
 462                 To migrate your scripts to the new <acronym>API</acronym>, simply use the method as
 463                 shown below.
 464             </para>
 465
 466             <example id="migration.17.zend.locale.islocale.getdefault.example">
 467                 <title>How to change getDefault() from 1.6 to 1.7</title>
 468
 469                 <programlisting language="php"><![CDATA[
 470 // Example for 1.6
 471 $locales = $locale->getDefault(Zend_Locale::BROWSER);
 472
 473 // Same example for 1.7
 474
 475 // You should change the compatiblity mode to prevent user warnings
 476 // But you can do this in your bootstrap
 477 Zend_Locale::$compatibilityMode = false;
 478
 479 $locale = Zend_Locale::getOrder(Zend_Locale::BROWSER);
 480 ]]></programlisting>
 481
 482                 <para>
 483                     Note that the second parameter of the old <methodname>getDefault()</methodname>
 484                     implementation is not available anymore, but the returned values are the same.
 485                 </para>
 486             </example>
 487
 488             <note>
 489                 <para>
 490                     Per default the old behaviour is still active, but throws a user warning.
 491                     When you have changed your code to the new behaviour you should also change
 492                     the compatibility mode to <constant>FALSE</constant> so that no warning is
 493                     thrown anymore.
 494                 </para>
 495             </note>
 496         </sect3>
 497     </sect2>
 498
 499     <sect2 id="migration.17.zend.translate">
 500         <title>Zend_Translate</title>
 501
 502         <sect3 id="migration.17.zend.translate.languages">
 503             <title>Setting languages</title>
 504
 505             <para>
 506                 When using automatic detection of languages, or setting languages manually
 507                 to <classname>Zend_Translate</classname> you may have mentioned that from time to
 508                 time a notice is thrown about not added or empty translations. In some previous
 509                 release also an exception was raised in some cases.
 510             </para>
 511
 512             <para>
 513                 The reason is, that when a user requests a non existing language, you
 514                 have no simple way to detect what's going wrong. So we added those
 515                 notices which show up in your log and tell you that the user requested
 516                 a language which you do not support. Note that the code, even when
 517                 we trigger such an notice, keeps working without problems.
 518             </para>
 519
 520             <para>
 521                 But when you use a own error or exception handler, like xdebug, you
 522                 will get all notices returned, even if this was not your intention.
 523                 This is due to the fact that these handlers override all settings
 524                 from within <acronym>PHP</acronym>.
 525             </para>
 526
 527             <para>
 528                 To get rid of these notices you can simply set the new option
 529                 'disableNotices' to <constant>TRUE</constant>. It defaults to
 530                 <constant>FALSE</constant>.
 531             </para>
 532
 533             <example id="migration.17.zend.translate.example">
 534                 <title>Setting languages without getting notices</title>
 535
 536                 <para>
 537                     Let's assume that we have 'en' available and our user requests
 538                     'fr' which is not in our portfolio of translated languages.
 539                 </para>
 540
 541                 <programlisting language="php"><![CDATA[
 542 $language = new Zend_Translate('gettext',
 543                                '/path/to/translations',
 544                                'auto');
 545 ]]></programlisting>
 546
 547                 <para>
 548                     In this case we will get an notice about a not available language 'fr'.
 549                     Simply add the option and the notices will be disabled.
 550                 </para>
 551
 552                 <programlisting language="php"><![CDATA[
 553 $language = new Zend_Translate('gettext',
 554                                '/path/to/translations',
 555                                'auto',
 556                                array('disableNotices' => true));
 557 ]]></programlisting>
 558             </example>
 559         </sect3>
 560     </sect2>
 561
 562     <sect2 id="migration.17.zend.view">
 563         <title>Zend_View</title>
 564
 565         <note>
 566             <para>
 567                 The <acronym>API</acronym> changes within <classname>Zend_View</classname> are only
 568                 notable for you when you are upgrading to release 1.7.5 or higher.
 569             </para>
 570         </note>
 571
 572         <para>
 573             Prior to the 1.7.5 release, the Zend Framework team was notified of
 574             a potential Local File Inclusion (<acronym>LFI</acronym>) vulnerability in the
 575             <methodname>Zend_View::render()</methodname> method. Prior to 1.7.5, the method
 576             allowed, by default, the ability to specify view scripts that
 577             included parent directory notation (e.g., "../" or "..\"). This
 578             opens the possibility for an <acronym>LFI</acronym> attack if unfiltered user input is
 579             passed to the <methodname>render()</methodname> method:
 580         </para>
 581
 582         <programlisting language="php"><![CDATA[
 583 // Where $_GET['foobar'] = '../../../../etc/passwd'
 584 echo $view->render($_GET['foobar']); // LFI inclusion
 585 ]]></programlisting>
 586
 587         <para>
 588             <classname>Zend_View</classname> now by default raises an exception when such
 589             a view script is requested.
 590         </para>
 591
 592         <sect3 id="migration.17.zend.view.disabling">
 593             <title>Disabling LFI protection for the render() method</title>
 594
 595             <para>
 596                 Since a number of developers reported that they were using such
 597                 notation within their applications that was <emphasis>not</emphasis>
 598                 the result of user input, a special flag was created to allow
 599                 disabling the default protection. You have two methods for doing so:
 600                 by passing the 'lfiProtectionOn' key to the constructor options, or
 601                 by explicitly calling the <methodname>setLfiProtection()</methodname> method.
 602             </para>
 603
 604             <programlisting language="php"><![CDATA[
 605 // Disabling via constructor
 606 $view = new Zend_View(array('lfiProtectionOn' => false));
 607
 608 // Disabling via exlicit method call:
 609 $view = new Zend_View();
 610 $view->setLfiProtection(false);
 611 ]]></programlisting>
 612         </sect3>
 613     </sect2>
 614 </sect1>
 615 <!--
 616 vim:se ts=4 sw=4 et:
 617 -->