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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="migration.10">
    <title>Zend Framework 1.0</title>

    <para>
        When upgrading from a previous release to Zend Framework 1.0 or higher you
        should note the following migration notes.
    </para>

    <sect2 id="migration.10.zend.controller">
        <title>Zend_Controller</title>

        <para>
            The principal changes introduced in 1.0.0RC1 are the introduction of
            and default enabling of the
            <link
                linkend="zend.controller.plugins.standard.errorhandler">ErrorHandler</link>
            plugin and the <link
                linkend="zend.controller.actionhelpers.viewrenderer">ViewRenderer</link>
            action helper. Please read the documentation to each thoroughly to
            see how they work and what effect they may have on your
            applications.
        </para>

        <para>
            The <classname>ErrorHandler</classname> plugin runs during
            <methodname>postDispatch()</methodname> checking for exceptions, and forwarding
            to a specified error handler controller. You should include such a
            controller in your application. You may disable it by setting the
            front controller parameter <property>noErrorHandler</property>:
        </para>

        <programlisting language="php"><![CDATA[
$front->setParam('noErrorHandler', true);
]]></programlisting>

        <para>
            The <classname>ViewRenderer</classname> action helper automates view injection
            into action controllers as well as autorendering of view scripts
            based on the current action. The primary issue you may encounter is
            if you have actions that do not render view scripts and neither
            forward or redirect, as the <classname>ViewRenderer</classname> will attempt
            to render a view script based on the action name.
        </para>

        <para>
            There are several strategies you can take to update your code. In
            the short term, you can globally disable the
            <classname>ViewRenderer</classname> in your front controller bootstrap prior
            to dispatching:
        </para>

        <programlisting language="php"><![CDATA[
// Assuming $front is an instance of Zend_Controller_Front
$front->setParam('noViewRenderer', true);
]]></programlisting>

        <para>
            However, this is not a good long term strategy, as it means most
            likely you'll be writing more code.
        </para>

        <para>
            When you're ready to start using the <classname>ViewRenderer</classname>
            functionality, there are several things to look for in your
            controller code. First, look at your action methods (the methods
            ending in 'Action'), and determine what each is doing. If none of
            the following is happening, you'll need to make changes:
        </para>

        <itemizedlist>
            <listitem><para>Calls to <command>$this->render();</command></para></listitem>
            <listitem><para>Calls to <command>$this->_forward();</command></para></listitem>
            <listitem><para>Calls to <command>$this->_redirect();</command></para></listitem>

            <listitem>
                <para>Calls to the <classname>Redirector</classname> action helper</para>
            </listitem>
        </itemizedlist>

        <para>
            The easiest change is to disable auto-rendering for that method:
        </para>

        <programlisting language="php"><![CDATA[
$this->_helper->viewRenderer->setNoRender();
]]></programlisting>

        <para>
            If you find that none of your action methods are rendering,
            forwarding, or redirecting, you will likely want to put the above
            line in your <methodname>preDispatch()</methodname> or <methodname>init()</methodname>
            methods:
        </para>

        <programlisting language="php"><![CDATA[
public function preDispatch()
{
    // disable view script autorendering
    $this->_helper->viewRenderer->setNoRender()
    // .. do other things...
}
]]></programlisting>

        <para>
            If you are calling <methodname>render()</methodname>, and you're using <link
                linkend="zend.controller.modular">the Conventional Modular
                directory structure</link>, you'll want to change your code to
            make use of autorendering:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    If you're rendering multiple view scripts in a single
                    action, you don't need to change a thing.
                </para>
            </listitem>

            <listitem>
                <para>
                    If you're simply calling <methodname>render()</methodname> with no
                    arguments, you can remove such lines.
                </para>
            </listitem>

            <listitem>
                <para>
                    If you're calling <methodname>render()</methodname> with arguments, and
                    not doing any processing afterwards or rendering multiple
                    view scripts, you can change these calls to read
                    <command>$this->_helper->viewRenderer();</command>.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            If you're not using the conventional modular directory structure,
            there are a variety of methods for setting the view base path and
            script path specifications so that you can make use of the
            <classname>ViewRenderer</classname>. Please read the <link
                linkend="zend.controller.actionhelpers.viewrenderer">ViewRenderer
                documentation</link> for information on these methods.
        </para>

        <para>
            If you're using a view object from the registry, or customizing your
            view object, or using a different view implementation, you'll want
            to inject the <classname>ViewRenderer</classname> with this object. This can
            be done easily at any time.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Prior to dispatching a front controller instance:
                </para>

                <programlisting language="php"><![CDATA[
// Assuming $view has already been defined
$viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer($view);
Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    Any time during the bootstrap process:
                </para>

                <programlisting language="php"><![CDATA[
$viewRenderer =
    Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
$viewRenderer->setView($view);
]]></programlisting>
            </listitem>
        </itemizedlist>

        <para>
            There are many ways to modify the <classname>ViewRenderer</classname>,
            including setting a different view script to render, specifying
            replacements for all replaceable elements of a view script path
            (including the suffix), choosing a response named segment to
            utilize, and more. If you aren't using the conventional modular
            directory structure, you can even associate different path
            specifications with the <classname>ViewRenderer</classname>.
        </para>

        <para>
            We encourage you to adapt your code to use the
            <classname>ErrorHandler</classname> and <classname>ViewRenderer</classname> as they are
            now core functionality.
        </para>
    </sect2>

    <sect2 id="migration.10.zend.currency">
        <title>Zend_Currency</title>

        <para>
            Creating an object of <classname>Zend_Currency</classname> has become simpler.
            You no longer have to give a script or set it to <constant>NULL</constant>. The optional
            script parameter is now an option which can be set through the
            <methodname>setFormat()</methodname> method.
        </para>

        <programlisting language="php"><![CDATA[
$currency = new Zend_Currency($currency, $locale);
]]></programlisting>

        <para>
            The <methodname>setFormat()</methodname> method takes now an array of options. These
            options are set permanently and override all previously set values. Also a new option
            'precision' has been added. The following options have been refactored:
        </para>

        <itemizedlist mark='opencircle'>
            <listitem>
                <para>
                    <emphasis>position</emphasis>:
                    Replacement for the old 'rules' parameter.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>script</emphasis>:
                    Replacement for the old 'script' parameter.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>format</emphasis>:
                    Replacement for the old 'locale' parameter which does not
                    set new currencies but only the number format.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>display</emphasis>:
                    Replacement for the old 'rules' parameter.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>precision</emphasis>:
                    New parameter.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>name</emphasis>:
                    Replacement for the ole 'rules' parameter. Sets the full
                    currencies name.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>currency</emphasis>:
                    New parameter.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>symbol</emphasis>:
                    New parameter.
                </para>
            </listitem>
        </itemizedlist>

        <programlisting language="php"><![CDATA[
$currency->setFormat(array $options);
]]></programlisting>

        <para>
            The <methodname>toCurrency()</methodname> method no longer supports the optional
            'script' and 'locale' parameters. Instead it takes an options array which
            can contain the same keys as for the <methodname>setFormat()</methodname> method.
        </para>

        <programlisting language="php"><![CDATA[
$currency->toCurrency($value, array $options);
]]></programlisting>

        <para>
            The methods <methodname>getSymbol()</methodname>,
            <methodname>getShortName()</methodname>, <methodname>getName()</methodname>,
            <methodname>getRegionList()</methodname> and
            <methodname>getCurrencyList()</methodname> are no longer static and can be called
            from within the object. They return the set values of the object if no
            parameter has been set.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->