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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="migration.06">
   4     <title>Zend Framework 0.6</title>
   5
   6     <para>
   7         When upgrading from a previous release to Zend Framework 0.6 or higher you
   8         should note the following migration notes.
   9     </para>
  10
  11     <sect2 id="migration.06.zend.controller">
  12         <title>Zend_Controller</title>
  13
  14         <para>
  15             The most basic usage of the <acronym>MVC</acronym> components has not changed; you can
  16             still do each of the following:
  17         </para>
  18
  19         <programlisting language="php"><![CDATA[
  20 Zend_Controller_Front::run('/path/to/controllers');
  21 ]]></programlisting>
  22
  23         <programlisting language="php"><![CDATA[
  24 /* -- create a router -- */
  25 $router = new Zend_Controller_RewriteRouter();
  26 $router->addRoute('user',
  27                   'user/:username',
  28                   array('controller' => 'user', 'action' => 'info')
  29 );
  30
  31 /* -- set it in a controller -- */
  32 $ctrl = Zend_Controller_Front::getInstance();
  33 $ctrl->setRouter($router);
  34
  35 /* -- set controller directory and dispatch -- */
  36 $ctrl->setControllerDirectory('/path/to/controllers');
  37 $ctrl->dispatch();
  38 ]]></programlisting>
  39
  40         <para>
  41             We encourage use of the Response object to aggregate content and
  42             headers. This will allow for more flexible output format switching
  43             (for instance, <acronym>JSON</acronym> or <acronym>XML</acronym> instead of
  44             <acronym>XHTML</acronym>) in your applications.
  45             By default, <methodname>dispatch()</methodname> will render the response, sending both
  46             headers and rendering any content. You may also have the front
  47             controller return the response using <methodname>returnResponse()</methodname>,
  48             and then render the response using your own logic. A future version
  49             of the front controller may enforce use of the response object via
  50             output buffering.
  51         </para>
  52
  53         <para>
  54             There are many additional features that extend the existing <acronym>API</acronym>,
  55             and these are noted in the documentation.
  56         </para>
  57
  58         <para>
  59             The main changes you will need to be aware of will be found when
  60             subclassing the various components. Key amongst these are:
  61         </para>
  62
  63         <itemizedlist>
  64             <listitem>
  65                 <para>
  66                     <methodname>Zend_Controller_Front::dispatch()</methodname> by default
  67                     traps exceptions in the response object, and does not render
  68                     them, in order to prevent sensitive system information from
  69                     being rendered. You can override this in several ways:
  70                 </para>
  71
  72                 <itemizedlist>
  73                     <listitem>
  74                         <para>
  75                             Set <methodname>throwExceptions()</methodname> in the front
  76                             controller:
  77                         </para>
  78
  79                         <programlisting language="php"><![CDATA[
  80 $front->throwExceptions(true);
  81 ]]></programlisting>
  82                     </listitem>
  83
  84                     <listitem>
  85                         <para>
  86                             Set <methodname>renderExceptions()</methodname> in the response
  87                             object:
  88                         </para>
  89
  90                         <programlisting language="php"><![CDATA[
  91 $response->renderExceptions(true);
  92 $front->setResponse($response);
  93 $front->dispatch();
  94
  95 // or:
  96 $front->returnResponse(true);
  97 $response = $front->dispatch();
  98 $response->renderExceptions(true);
  99 echo $response;
 100 ]]></programlisting>
 101                     </listitem>
 102                 </itemizedlist>
 103             </listitem>
 104
 105             <listitem>
 106                 <para>
 107                     <methodname>Zend_Controller_Dispatcher_Interface::dispatch()</methodname>
 108                     now accepts and returns a <link linkend="zend.controller.request">The
 109                     Request Object</link> instead of a dispatcher token.
 110                 </para>
 111             </listitem>
 112
 113             <listitem>
 114                 <para>
 115                     <methodname>Zend_Controller_Router_Interface::route()</methodname>
 116                     now accepts and returns a <link linkend="zend.controller.request">The
 117                     Request Object</link> instead of a dispatcher token.
 118                 </para>
 119             </listitem>
 120
 121             <listitem>
 122                 <para><classname>Zend_Controller_Action</classname> changes include:</para>
 123
 124                 <itemizedlist>
 125                     <listitem>
 126                         <para>
 127                             The constructor now accepts exactly three arguments,
 128                             <classname>Zend_Controller_Request_Abstract</classname>
 129                             <varname>$request</varname>,
 130                             <classname>Zend_Controller_Response_Abstract</classname>
 131                             <varname>$response</varname>,
 132                             and <type>Array</type> <varname>$params</varname> (optional).
 133                             <methodname>Zend_Controller_Action::__construct()</methodname> uses
 134                             these to set the request, response, and invokeArgs
 135                             properties of the object, and if overriding the
 136                             constructor, you should do so as well. Better yet, use
 137                             the <methodname>init()</methodname> method to do any instance
 138                             configuration, as this method is called as the final
 139                             action of the constructor.
 140                         </para>
 141                     </listitem>
 142
 143                     <listitem>
 144                         <para>
 145                             <methodname>run()</methodname> is no longer defined as final, but is
 146                             also no longer used by the front controller; its sole
 147                             purpose is for using the class as a page controller. It
 148                             now takes two optional arguments, a
 149                             <classname>Zend_Controller_Request_Abstract</classname>
 150                             <varname>$request</varname>
 151                             and a <classname>Zend_Controller_Response_Abstract</classname>
 152                             <varname>$response</varname>.
 153                         </para>
 154                     </listitem>
 155
 156                     <listitem>
 157                         <para>
 158                             <methodname>indexAction()</methodname> no longer needs to be
 159                             defined, but is encouraged as the default action. This
 160                             allows using the RewriteRouter and action controllers to
 161                             specify different default action methods.
 162                         </para>
 163                     </listitem>
 164
 165                     <listitem>
 166                         <para>
 167                             <methodname>__call()</methodname> should be overridden to handle any
 168                             undefined actions automatically.
 169                         </para>
 170                     </listitem>
 171
 172                     <listitem>
 173                         <para>
 174                             <methodname>_redirect()</methodname> now takes an optional second
 175                             argument, the <acronym>HTTP</acronym> code to return with the redirect,
 176                             and an optional third argument, <varname>$prependBase</varname>,
 177                             that can indicate that the base <acronym>URL</acronym> registered with
 178                             the request object should be prepended to the url specified.
 179                         </para>
 180                     </listitem>
 181
 182                     <listitem>
 183                         <para>
 184                             The <varname>$_action</varname> property is no longer set. This property
 185                             was a <classname>Zend_Controller_Dispatcher_Token</classname>,
 186                             which no longer exists in the current incarnation.
 187                             The sole purpose of the token was to provide
 188                             information about the requested controller, action,
 189                             and <acronym>URL</acronym> parameters. This information is now
 190                             available in the request object, and can be accessed
 191                             as follows:
 192                         </para>
 193
 194                         <programlisting language="php"><![CDATA[
 195 // Retrieve the requested controller name
 196 // Access used to be via: $this->_action->getControllerName().
 197 // The example below uses getRequest(), though you may also directly
 198 // access the $_request property; using getRequest() is recommended as
 199 // a parent class may override access to the request object.
 200 $controller = $this->getRequest()->getControllerName();
 201
 202 // Retrieve the requested action name
 203 // Access used to be via: $this->_action->getActionName().
 204 $action = $this->getRequest()->getActionName();
 205
 206 // Retrieve the request parameters
 207 // This hasn't changed; the _getParams() and _getParam() methods simply
 208 // proxy to the request object now.
 209 $params = $this->_getParams();
 210 // request 'foo' parameter, using 'default' as default value if not found
 211 $foo = $this->_getParam('foo', 'default');
 212 ]]></programlisting>
 213                     </listitem>
 214
 215                     <listitem>
 216                         <para>
 217                             <methodname>noRouteAction()</methodname> has been removed. The
 218                             appropriate way to handle non-existent action
 219                             methods should you wish to route them to a default
 220                             action is using <methodname>__call()</methodname>:
 221                         </para>
 222
 223                         <programlisting language="php"><![CDATA[
 224 public function __call($method, $args)
 225 {
 226     // If an unmatched 'Action' method was requested, pass on to the
 227     // default action method:
 228     if ('Action' == substr($method, -6)) {
 229         return $this->defaultAction();
 230     }
 231
 232     throw new Zend_Controller_Exception('Invalid method called');
 233 }
 234 ]]></programlisting>
 235                     </listitem>
 236                 </itemizedlist>
 237             </listitem>
 238
 239             <listitem>
 240                 <para>
 241                     <methodname>Zend_Controller_RewriteRouter::setRewriteBase()</methodname> has
 242                     been removed. Use <methodname>Zend_Controller_Front::setBaseUrl()</methodname>
 243                     instead (or <methodname>Zend_Controller_Request_Http::setBaseUrl()</methodname>,
 244                     if using that request class).
 245                 </para>
 246             </listitem>
 247
 248             <listitem>
 249                 <para>
 250                     <classname>Zend_Controller_Plugin_Interface</classname> was replaced
 251                     by <classname>Zend_Controller_Plugin_Abstract</classname>. All methods now
 252                     accept and return a <link linkend="zend.controller.request">The Request
 253                     Object</link> instead of a dispatcher token.
 254                 </para>
 255             </listitem>
 256         </itemizedlist>
 257     </sect2>
 258 </sect1>
 259 <!--
 260 vim:se ts=4 sw=4 et:
 261 -->