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

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

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

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

        <sect3 id="migration.17.zend.controller.dispatcher">
            <title>Dispatcher Interface Changes</title>

            <para>
                Users brought to our attention the fact that
                <classname>Zend_Controller_Action_Helper_ViewRenderer</classname> were
                using a method of the dispatcher abstract class that was not in
                the dispatcher interface. We have now added the following method to
                ensure that custom dispatchers will continue to work with the
                shipped implementations:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>formatModuleName()</methodname>: should be used to take a raw
                        controller name, such as one that would be packaged inside a request
                        object, and reformat it to a proper class name that a class extending
                        <classname>Zend_Controller_Action</classname> would use
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>

    <sect2 id="migration.17.zend.file.transfer">
        <title>Zend_File_Transfer</title>

        <sect3 id="migration.17.zend.file.transfer.validators">
            <title>Changes when using filters and validators</title>

            <para>
                As noted by users, the validators from <classname>Zend_File_Transfer</classname>
                do not work in conjunction with <classname>Zend_Config</classname> due to the fact
                that they have not used named arrays.
            </para>

            <para>
                Therefor, all filters and validators for <classname>Zend_File_Transfer</classname>
                have been reworked. While the old signatures continue to work,
                they have been marked as deprecated, and will emit a <acronym>PHP</acronym> notice
                asking you to fix them.
            </para>

            <para>
                The following list shows you the changes you will have to do for proper
                usage of the parameters.
            </para>

            <sect4 id="migration.17.zend.file.transfer.validators.rename">
                <title>Filter: Rename</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Old method <acronym>API</acronym>:
                            <methodname>Zend_Filter_File_Rename($oldfile, $newfile,
                                $overwrite)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            New method <acronym>API</acronym>:
                            <methodname>Zend_Filter_File_Rename($options)</methodname>
                            where <varname>$options</varname> accepts the following array keys:
                            <emphasis>source</emphasis> equals to <varname>$oldfile</varname>,
                            <emphasis>target</emphasis> equals to <varname>$newfile</varname>,
                            <emphasis>overwrite</emphasis> equals to <varname>$overwrite</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.rename.example">
                    <title>Changes for the rename filter from 1.6 to 1.7</title>

                    <programlisting language="php"><![CDATA[
// Example for 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addFilter('Rename',
                   array('/path/to/oldfile', '/path/to/newfile', true));

// Same example for 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addFilter('Rename',
                   array('source' => '/path/to/oldfile',
                         'target' => '/path/to/newfile',
                         'overwrite' => true));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.count">
                <title>Validator: Count</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Old method <acronym>API</acronym>:
                            <methodname>Zend_Validate_File_Count($min, $max)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            New method <acronym>API</acronym>:
                            <methodname>Zend_Validate_File_Count($options)</methodname>
                            where <varname>$options</varname> accepts the following array keys:
                            <emphasis>min</emphasis> equals to <varname>$min</varname>,
                            <emphasis>max</emphasis> equals to <varname>$max</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.count.example">
                    <title>Changes for the count validator from 1.6 to 1.7</title>

                    <programlisting language="php"><![CDATA[
// Example for 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Count',
                      array(2, 3));

// Same example for 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Count',
                      false,
                      array('min' => 2,
                            'max' => 3));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.extension">
                <title>Validator:Extension</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Old method <acronym>API</acronym>:
                            <methodname>Zend_Validate_File_Extension($extension, $case)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            New method <acronym>API</acronym>:
                            <methodname>Zend_Validate_File_Extension($options)</methodname> where
                            <varname>$options</varname> accepts the following array keys:
                            <emphasis>*</emphasis> equals to <varname>$extension</varname> and can
                            have any other key, <emphasis>case</emphasis> equals to
                            <varname>$case</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.extension.example">
                    <title>Changes for the extension validator from 1.6 to 1.7</title>

                    <programlisting language="php"><![CDATA[
// Example for 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Extension',
                      array('jpg,gif,bmp', true));

// Same example for 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Extension',
                      false,
                      array('extension1' => 'jpg,gif,bmp',
                            'case' => true));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.filessize">
                <title>Validator: FilesSize</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Old method <acronym>API</acronym>:
                            <methodname>Zend_Validate_File_FilesSize($min, $max,
                                $bytestring)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            New method <acronym>API</acronym>:
                            <methodname>Zend_Validate_File_FilesSize($options)</methodname> where
                            <varname>$options</varname> accepts the following array keys:
                            <emphasis>min</emphasis> equals to <varname>$min</varname>,
                            <emphasis>max</emphasis> equals to <varname>$max</varname>,
                            <emphasis>bytestring</emphasis> equals to
                            <varname>$bytestring</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <para>
                    Additionally, the <methodname>useByteString()</methodname> method
                    signature has changed. It can only be used to test if the
                    validator is expecting to use byte strings in generated
                    messages. To set the value of the flag, use the
                    <methodname>setUseByteString()</methodname> method.
                </para>

                <example id="migration.17.zend.file.transfer.validators.filessize.example">
                    <title>Changes for the filessize validator from 1.6 to 1.7</title>

                    <programlisting language="php"><![CDATA[
// Example for 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('FilesSize',
                   array(100, 10000, true));

// Same example for 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('FilesSize',
                      false,
                      array('min' => 100,
                            'max' => 10000,
                            'bytestring' => true));

// Example for 1.6
$upload->useByteString(true); // set flag

// Same example for 1.7
$upload->setUseByteSting(true); // set flag
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.hash">
                <title>Validator: Hash</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Old method <acronym>API</acronym>:
                            <methodname>Zend_Validate_File_Hash($hash, $algorithm)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            New method <acronym>API</acronym>:
                            <methodname>Zend_Validate_File_Hash($options)</methodname>
                            where <varname>$options</varname> accepts the following array keys:
                            <emphasis>*</emphasis> equals to <varname>$hash</varname> and can have
                            any other key, <emphasis>algorithm</emphasis> equals to
                            <varname>$algorithm</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.hash.example">
                    <title>Changes for the hash validator from 1.6 to 1.7</title>

                    <programlisting language="php"><![CDATA[
// Example for 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Hash',
                   array('12345', 'md5'));

// Same example for 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Hash',
                      false,
                      array('hash1' => '12345',
                            'algorithm' => 'md5'));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.imagesize">
                <title>Validator: ImageSize</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Old method <acronym>API</acronym>:
                            <methodname>Zend_Validate_File_ImageSize($minwidth, $minheight,
                                $maxwidth, $maxheight)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            New method <acronym>API</acronym>:
                            <methodname>Zend_Validate_File_FilesSize($options)</methodname> where
                            <varname>$options</varname> accepts the following array keys:
                            <emphasis>minwidth</emphasis> equals to <varname>$minwidth</varname>,
                            <emphasis>maxwidth</emphasis> equals to <varname>$maxwidth</varname>,
                            <emphasis>minheight</emphasis> equals to <varname>$minheight</varname>,
                            <emphasis>maxheight</emphasis> equals to <varname>$maxheight</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.imagesize.example">
                    <title>Changes for the imagesize validator from 1.6 to 1.7</title>

                    <programlisting language="php"><![CDATA[
// Example for 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('ImageSize',
                      array(10, 10, 100, 100));

// Same example for 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('ImageSize',
                      false,
                      array('minwidth' => 10,
                            'minheight' => 10,
                            'maxwidth' => 100,
                            'maxheight' => 100));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.size">
                <title>Validator: Size</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Old method <acronym>API</acronym>:
                                <methodname>Zend_Validate_File_Size($min, $max,
                                $bytestring)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            New method <acronym>API</acronym>:
                            <methodname>Zend_Validate_File_Size($options)</methodname>
                            where <varname>$options</varname> accepts the following array keys:
                            <emphasis>min</emphasis> equals to <varname>$min</varname>,
                            <emphasis>max</emphasis> equals to <varname>$max</varname>,
                            <emphasis>bytestring</emphasis> equals to
                            <varname>$bytestring</varname>.
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.size.example">
                    <title>Changes for the size validator from 1.6 to 1.7</title>

                    <programlisting language="php"><![CDATA[
// Example for 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Size',
                      array(100, 10000, true));

// Same example for 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Size',
                      false,
                      array('min' => 100,
                            'max' => 10000,
                            'bytestring' => true));
]]></programlisting>
                </example>
            </sect4>
        </sect3>
    </sect2>

    <sect2 id="migration.17.zend.locale">
        <title>Zend_Locale</title>

        <sect3 id="migration.17.zend.locale.islocale">
            <title>Changes when using isLocale()</title>

            <para>
                According to the coding standards <methodname>isLocale()</methodname> had to be
                changed to return a boolean. In previous releases a string was returned on success.
                For release 1.7 a compatibility mode has been added which allows to use the
                old behaviour of a returned string, but it triggers a user warning to
                mention you to change to the new behaviour. The rerouting which the old
                behaviour of <methodname>isLocale()</methodname> could have done is no longer
                neccessary as all I18n will now process a rerouting themself.
            </para>

            <para>
                To migrate your scripts to the new <acronym>API</acronym>, simply use the method as
                shown below.
            </para>

            <example id="migration.17.zend.locale.islocale.example">
                <title>How to change isLocale() from 1.6 to 1.7</title>

                <programlisting language="php"><![CDATA[
// Example for 1.6
if ($locale = Zend_Locale::isLocale($locale)) {
    // do something
}

// Same example for 1.7

// You should change the compatiblity mode to prevent user warnings
// But you can do this in your bootstrap
Zend_Locale::$compatibilityMode = false;

if (Zend_Locale::isLocale($locale)) {
}
]]></programlisting>

                <para>
                    Note that you can use the second parameter to see if the locale is correct
                    without processing a rerouting.
                </para>

                <programlisting language="php"><![CDATA[
// Example for 1.6
if ($locale = Zend_Locale::isLocale($locale, false)) {
    // do something
}

// Same example for 1.7

// You should change the compatiblity mode to prevent user warnings
// But you can do this in your bootstrap
Zend_Locale::$compatibilityMode = false;

if (Zend_Locale::isLocale($locale, false)) {
    if (Zend_Locale::isLocale($locale, true)) {
        // no locale at all
    }

    // original string is no locale but can be rerouted
}
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="migration.17.zend.locale.islocale.getdefault">
            <title>Changes when using getDefault()</title>

            <para>
                The meaning of the <methodname>getDefault()</methodname> method has been change due
                to the fact that we integrated a framework locale which can be set with
                <methodname>setDefault()</methodname>. It does no longer return the locale chain
                but only the set framework locale.
            </para>

            <para>
                To migrate your scripts to the new <acronym>API</acronym>, simply use the method as
                shown below.
            </para>

            <example id="migration.17.zend.locale.islocale.getdefault.example">
                <title>How to change getDefault() from 1.6 to 1.7</title>

                <programlisting language="php"><![CDATA[
// Example for 1.6
$locales = $locale->getDefault(Zend_Locale::BROWSER);

// Same example for 1.7

// You should change the compatiblity mode to prevent user warnings
// But you can do this in your bootstrap
Zend_Locale::$compatibilityMode = false;

$locale = Zend_Locale::getOrder(Zend_Locale::BROWSER);
]]></programlisting>

                <para>
                    Note that the second parameter of the old <methodname>getDefault()</methodname>
                    implementation is not available anymore, but the returned values are the same.
                </para>
            </example>

            <note>
                <para>
                    Per default the old behaviour is still active, but throws a user warning.
                    When you have changed your code to the new behaviour you should also change
                    the compatibility mode to <constant>FALSE</constant> so that no warning is
                    thrown anymore.
                </para>
            </note>
        </sect3>
    </sect2>

    <sect2 id="migration.17.zend.translate">
        <title>Zend_Translate</title>

        <sect3 id="migration.17.zend.translate.languages">
            <title>Setting languages</title>

            <para>
                When using automatic detection of languages, or setting languages manually
                to <classname>Zend_Translate</classname> you may have mentioned that from time to
                time a notice is thrown about not added or empty translations. In some previous
                release also an exception was raised in some cases.
            </para>

            <para>
                The reason is, that when a user requests a non existing language, you
                have no simple way to detect what's going wrong. So we added those
                notices which show up in your log and tell you that the user requested
                a language which you do not support. Note that the code, even when
                we trigger such an notice, keeps working without problems.
            </para>

            <para>
                But when you use a own error or exception handler, like xdebug, you
                will get all notices returned, even if this was not your intention.
                This is due to the fact that these handlers override all settings
                from within <acronym>PHP</acronym>.
            </para>

            <para>
                To get rid of these notices you can simply set the new option
                'disableNotices' to <constant>TRUE</constant>. It defaults to
                <constant>FALSE</constant>.
            </para>

            <example id="migration.17.zend.translate.example">
                <title>Setting languages without getting notices</title>

                <para>
                    Let's assume that we have 'en' available and our user requests
                    'fr' which is not in our portfolio of translated languages.
                </para>

                <programlisting language="php"><![CDATA[
$language = new Zend_Translate('gettext',
                               '/path/to/translations',
                               'auto');
]]></programlisting>

                <para>
                    In this case we will get an notice about a not available language 'fr'.
                    Simply add the option and the notices will be disabled.
                </para>

                <programlisting language="php"><![CDATA[
$language = new Zend_Translate('gettext',
                               '/path/to/translations',
                               'auto',
                               array('disableNotices' => true));
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="migration.17.zend.view">
        <title>Zend_View</title>

        <note>
            <para>
                The <acronym>API</acronym> changes within <classname>Zend_View</classname> are only
                notable for you when you are upgrading to release 1.7.5 or higher.
            </para>
        </note>

        <para>
            Prior to the 1.7.5 release, the Zend Framework team was notified of
            a potential Local File Inclusion (<acronym>LFI</acronym>) vulnerability in the
            <methodname>Zend_View::render()</methodname> method. Prior to 1.7.5, the method
            allowed, by default, the ability to specify view scripts that
            included parent directory notation (e.g., "../" or "..\"). This
            opens the possibility for an <acronym>LFI</acronym> attack if unfiltered user input is
            passed to the <methodname>render()</methodname> method:
        </para>

        <programlisting language="php"><![CDATA[
// Where $_GET['foobar'] = '../../../../etc/passwd'
echo $view->render($_GET['foobar']); // LFI inclusion
]]></programlisting>

        <para>
            <classname>Zend_View</classname> now by default raises an exception when such
            a view script is requested.
        </para>

        <sect3 id="migration.17.zend.view.disabling">
            <title>Disabling LFI protection for the render() method</title>

            <para>
                Since a number of developers reported that they were using such
                notation within their applications that was <emphasis>not</emphasis>
                the result of user input, a special flag was created to allow
                disabling the default protection. You have two methods for doing so:
                by passing the 'lfiProtectionOn' key to the constructor options, or
                by explicitly calling the <methodname>setLfiProtection()</methodname> method.
            </para>

            <programlisting language="php"><![CDATA[
// Disabling via constructor
$view = new Zend_View(array('lfiProtectionOn' => false));

// Disabling via exlicit method call:
$view = new Zend_View();
$view->setLfiProtection(false);
]]></programlisting>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->