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

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

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

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

        <para>
            Though most basic functionality remains the same, and all documented
            functionality remains the same, there is one particular
            <emphasis>undocumented</emphasis> "feature" that has changed.
        </para>

        <para>
            When writing <acronym>URL</acronym>s, the documented way to write camelCased action
            names is to use a word separator; these are '.' or '-' by default,
            but may be configured in the dispatcher. The dispatcher internally
            lowercases the action name, and uses these word separators to
            re-assemble the action method using camelCasing. However, because <acronym>PHP</acronym>
            functions are not case sensitive, you <emphasis>could</emphasis>
            still write <acronym>URL</acronym>s using camelCasing, and the dispatcher would resolve
            these to the same location. For example, 'camel-cased' would become
            'camelCasedAction' by the dispatcher, whereas 'camelCased' would
            become 'camelcasedAction'; however, due to the case insensitivity of
            <acronym>PHP</acronym>, both will execute the same method.
        </para>

        <para>
            This causes issues with the ViewRenderer when resolving view
            scripts. The canonical, documented way is that all word separators
            are converted to dashes, and the words lowercased. This creates
            a semantic tie between the actions and view scripts, and the
            normalization ensures that the scripts can be found. However, if the
            action 'camelCased' is called and actually resolves, the word
            separator is no longer present, and the ViewRenderer attempts to
            resolve to a different location -- <filename>camelcased.phtml</filename> instead of
            <filename>camel-cased.phtml</filename>.
        </para>

        <para>
            Some developers relied on this "feature", which was never intended.
            Several changes in the 1.5.0 tree, however, made it so that the
            ViewRenderer no longer resolves these paths; the semantic tie is now
            enforced. First among these, the dispatcher now enforces case
            sensitivity in action names. What this means is that referring to
            your actions on the url using camelCasing will no longer resolve to
            the same method as using word separators (i.e., 'camel-casing').
            This leads to the ViewRenderer now only honoring the word-separated
            actions when resolving view scripts.
        </para>

        <para>
            If you find that you were relying on this "feature", you have several
            options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Best option: rename your view scripts. Pros: forward
                    compatibility. Cons: if you have many view scripts that
                    relied on the former, unintended behavior, you will have a
                    lot of renaming to do.
                </para>
            </listitem>

            <listitem>
                <para>
                    Second best option: The ViewRenderer now delegates view
                    script resolution to <classname>Zend_Filter_Inflector</classname>; you
                    can modify the rules of the inflector to no longer separate
                    the words of an action with a dash:
                </para>

                <programlisting language="php"><![CDATA[
$viewRenderer =
    Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
$inflector = $viewRenderer->getInflector();
$inflector->setFilterRule(':action', array(
    new Zend_Filter_PregReplace(
        '#[^a-z0-9' . preg_quote(DIRECTORY_SEPARATOR, '#') . ']+#i',
        ''
    ),
    'StringToLower'
));
]]></programlisting>

                <para>
                    The above code will modify the inflector to no longer
                    separate the words with dash; you may also want to remove
                    the 'StringToLower' filter if you <emphasis>do</emphasis>
                    want the actual view script names camelCased as well.
                </para>

                <para>
                    If renaming your view scripts would be too tedious or time
                    consuming, this is your best option until you can find the
                    time to do so.
                </para>
            </listitem>

            <listitem>
                <para>
                    Least desirable option: You can force the dispatcher to
                    dispatch camelCased action names with a new front controller
                    flag, <property>useCaseSensitiveActions</property>:
                </para>

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

                <para>
                    This will allow you to use camelCasing on the url and still
                    have it resolve to the same action as when you use word
                    separators. However, this will mean that the original issues
                    will cascade on through; you will likely need to use the
                    second option above in addition to this for things to work
                    at all reliably.
                </para>

                <para>
                    Note, also, that usage of this flag will raise a notice that
                    this usage is deprecated.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->