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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="migration.10">
   4     <title>Zend Framework 1.0</title>
   5
   6     <para>
   7         When upgrading from a previous release to Zend Framework 1.0 or higher you
   8         should note the following migration notes.
   9     </para>
  10
  11     <sect2 id="migration.10.zend.controller">
  12         <title>Zend_Controller</title>
  13
  14         <para>
  15             The principal changes introduced in 1.0.0RC1 are the introduction of
  16             and default enabling of the
  17             <link
  18                 linkend="zend.controller.plugins.standard.errorhandler">ErrorHandler</link>
  19             plugin and the <link
  20                 linkend="zend.controller.actionhelpers.viewrenderer">ViewRenderer</link>
  21             action helper. Please read the documentation to each thoroughly to
  22             see how they work and what effect they may have on your
  23             applications.
  24         </para>
  25
  26         <para>
  27             The <classname>ErrorHandler</classname> plugin runs during
  28             <methodname>postDispatch()</methodname> checking for exceptions, and forwarding
  29             to a specified error handler controller. You should include such a
  30             controller in your application. You may disable it by setting the
  31             front controller parameter <property>noErrorHandler</property>:
  32         </para>
  33
  34         <programlisting language="php"><![CDATA[
  35 $front->setParam('noErrorHandler', true);
  36 ]]></programlisting>
  37
  38         <para>
  39             The <classname>ViewRenderer</classname> action helper automates view injection
  40             into action controllers as well as autorendering of view scripts
  41             based on the current action. The primary issue you may encounter is
  42             if you have actions that do not render view scripts and neither
  43             forward or redirect, as the <classname>ViewRenderer</classname> will attempt
  44             to render a view script based on the action name.
  45         </para>
  46
  47         <para>
  48             There are several strategies you can take to update your code. In
  49             the short term, you can globally disable the
  50             <classname>ViewRenderer</classname> in your front controller bootstrap prior
  51             to dispatching:
  52         </para>
  53
  54         <programlisting language="php"><![CDATA[
  55 // Assuming $front is an instance of Zend_Controller_Front
  56 $front->setParam('noViewRenderer', true);
  57 ]]></programlisting>
  58
  59         <para>
  60             However, this is not a good long term strategy, as it means most
  61             likely you'll be writing more code.
  62         </para>
  63
  64         <para>
  65             When you're ready to start using the <classname>ViewRenderer</classname>
  66             functionality, there are several things to look for in your
  67             controller code. First, look at your action methods (the methods
  68             ending in 'Action'), and determine what each is doing. If none of
  69             the following is happening, you'll need to make changes:
  70         </para>
  71
  72         <itemizedlist>
  73             <listitem><para>Calls to <command>$this->render();</command></para></listitem>
  74             <listitem><para>Calls to <command>$this->_forward();</command></para></listitem>
  75             <listitem><para>Calls to <command>$this->_redirect();</command></para></listitem>
  76
  77             <listitem>
  78                 <para>Calls to the <classname>Redirector</classname> action helper</para>
  79             </listitem>
  80         </itemizedlist>
  81
  82         <para>
  83             The easiest change is to disable auto-rendering for that method:
  84         </para>
  85
  86         <programlisting language="php"><![CDATA[
  87 $this->_helper->viewRenderer->setNoRender();
  88 ]]></programlisting>
  89
  90         <para>
  91             If you find that none of your action methods are rendering,
  92             forwarding, or redirecting, you will likely want to put the above
  93             line in your <methodname>preDispatch()</methodname> or <methodname>init()</methodname>
  94             methods:
  95         </para>
  96
  97         <programlisting language="php"><![CDATA[
  98 public function preDispatch()
  99 {
 100     // disable view script autorendering
 101     $this->_helper->viewRenderer->setNoRender()
 102     // .. do other things...
 103 }
 104 ]]></programlisting>
 105
 106         <para>
 107             If you are calling <methodname>render()</methodname>, and you're using <link
 108                 linkend="zend.controller.modular">the Conventional Modular
 109                 directory structure</link>, you'll want to change your code to
 110             make use of autorendering:
 111         </para>
 112
 113         <itemizedlist>
 114             <listitem>
 115                 <para>
 116                     If you're rendering multiple view scripts in a single
 117                     action, you don't need to change a thing.
 118                 </para>
 119             </listitem>
 120
 121             <listitem>
 122                 <para>
 123                     If you're simply calling <methodname>render()</methodname> with no
 124                     arguments, you can remove such lines.
 125                 </para>
 126             </listitem>
 127
 128             <listitem>
 129                 <para>
 130                     If you're calling <methodname>render()</methodname> with arguments, and
 131                     not doing any processing afterwards or rendering multiple
 132                     view scripts, you can change these calls to read
 133                     <command>$this->_helper->viewRenderer();</command>.
 134                 </para>
 135             </listitem>
 136         </itemizedlist>
 137
 138         <para>
 139             If you're not using the conventional modular directory structure,
 140             there are a variety of methods for setting the view base path and
 141             script path specifications so that you can make use of the
 142             <classname>ViewRenderer</classname>. Please read the <link
 143                 linkend="zend.controller.actionhelpers.viewrenderer">ViewRenderer
 144                 documentation</link> for information on these methods.
 145         </para>
 146
 147         <para>
 148             If you're using a view object from the registry, or customizing your
 149             view object, or using a different view implementation, you'll want
 150             to inject the <classname>ViewRenderer</classname> with this object. This can
 151             be done easily at any time.
 152         </para>
 153
 154         <itemizedlist>
 155             <listitem>
 156                 <para>
 157                     Prior to dispatching a front controller instance:
 158                 </para>
 159
 160                 <programlisting language="php"><![CDATA[
 161 // Assuming $view has already been defined
 162 $viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer($view);
 163 Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
 164 ]]></programlisting>
 165             </listitem>
 166
 167             <listitem>
 168                 <para>
 169                     Any time during the bootstrap process:
 170                 </para>
 171
 172                 <programlisting language="php"><![CDATA[
 173 $viewRenderer =
 174     Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
 175 $viewRenderer->setView($view);
 176 ]]></programlisting>
 177             </listitem>
 178         </itemizedlist>
 179
 180         <para>
 181             There are many ways to modify the <classname>ViewRenderer</classname>,
 182             including setting a different view script to render, specifying
 183             replacements for all replaceable elements of a view script path
 184             (including the suffix), choosing a response named segment to
 185             utilize, and more. If you aren't using the conventional modular
 186             directory structure, you can even associate different path
 187             specifications with the <classname>ViewRenderer</classname>.
 188         </para>
 189
 190         <para>
 191             We encourage you to adapt your code to use the
 192             <classname>ErrorHandler</classname> and <classname>ViewRenderer</classname> as they are
 193             now core functionality.
 194         </para>
 195     </sect2>
 196
 197     <sect2 id="migration.10.zend.currency">
 198         <title>Zend_Currency</title>
 199
 200         <para>
 201             Creating an object of <classname>Zend_Currency</classname> has become simpler.
 202             You no longer have to give a script or set it to <constant>NULL</constant>. The optional
 203             script parameter is now an option which can be set through the
 204             <methodname>setFormat()</methodname> method.
 205         </para>
 206
 207         <programlisting language="php"><![CDATA[
 208 $currency = new Zend_Currency($currency, $locale);
 209 ]]></programlisting>
 210
 211         <para>
 212             The <methodname>setFormat()</methodname> method takes now an array of options. These
 213             options are set permanently and override all previously set values. Also a new option
 214             'precision' has been added. The following options have been refactored:
 215         </para>
 216
 217         <itemizedlist mark='opencircle'>
 218             <listitem>
 219                 <para>
 220                     <emphasis>position</emphasis>:
 221                     Replacement for the old 'rules' parameter.
 222                 </para>
 223             </listitem>
 224
 225             <listitem>
 226                 <para>
 227                     <emphasis>script</emphasis>:
 228                     Replacement for the old 'script' parameter.
 229                 </para>
 230             </listitem>
 231
 232             <listitem>
 233                 <para>
 234                     <emphasis>format</emphasis>:
 235                     Replacement for the old 'locale' parameter which does not
 236                     set new currencies but only the number format.
 237                 </para>
 238             </listitem>
 239
 240             <listitem>
 241                 <para>
 242                     <emphasis>display</emphasis>:
 243                     Replacement for the old 'rules' parameter.
 244                 </para>
 245             </listitem>
 246
 247             <listitem>
 248                 <para>
 249                     <emphasis>precision</emphasis>:
 250                     New parameter.
 251                 </para>
 252             </listitem>
 253
 254             <listitem>
 255                 <para>
 256                     <emphasis>name</emphasis>:
 257                     Replacement for the ole 'rules' parameter. Sets the full
 258                     currencies name.
 259                 </para>
 260             </listitem>
 261
 262             <listitem>
 263                 <para>
 264                     <emphasis>currency</emphasis>:
 265                     New parameter.
 266                 </para>
 267             </listitem>
 268
 269             <listitem>
 270                 <para>
 271                     <emphasis>symbol</emphasis>:
 272                     New parameter.
 273                 </para>
 274             </listitem>
 275         </itemizedlist>
 276
 277         <programlisting language="php"><![CDATA[
 278 $currency->setFormat(array $options);
 279 ]]></programlisting>
 280
 281         <para>
 282             The <methodname>toCurrency()</methodname> method no longer supports the optional
 283             'script' and 'locale' parameters. Instead it takes an options array which
 284             can contain the same keys as for the <methodname>setFormat()</methodname> method.
 285         </para>
 286
 287         <programlisting language="php"><![CDATA[
 288 $currency->toCurrency($value, array $options);
 289 ]]></programlisting>
 290
 291         <para>
 292             The methods <methodname>getSymbol()</methodname>,
 293             <methodname>getShortName()</methodname>, <methodname>getName()</methodname>,
 294             <methodname>getRegionList()</methodname> and
 295             <methodname>getCurrencyList()</methodname> are no longer static and can be called
 296             from within the object. They return the set values of the object if no
 297             parameter has been set.
 298         </para>
 299     </sect2>
 300 </sect1>
 301 <!--
 302 vim:se ts=4 sw=4 et:
 303 -->