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>: <classname>Zend_Filter_File_Rename($oldfile, $newfile,
                            $overwrite)</classname>
                    </para></listitem>

                    <listitem><para>
                        New method <acronym>API</acronym>: <methodname>Zend_Filter_File_Rename($options)</methodname>
                        where $options accepts the following array keys:
                        <emphasis>source</emphasis> equals to $oldfile,
                        <emphasis>target</emphasis> equals to $newfile,
                        <emphasis>overwrite</emphasis> equals to $overwrite
                    </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 $options accepts the following array keys:
                        <emphasis>min</emphasis> equals to $min,
                        <emphasis>max</emphasis> equals to $max,
                    </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>: <classname>Zend_Validate_File_Extension($extension,
                            $case)</classname>
                    </para></listitem>

                    <listitem><para>
                        New method <acronym>API</acronym>:
                        <methodname>Zend_Validate_File_Extension($options)</methodname> where $options
                        accepts the following array keys:
                        <emphasis>*</emphasis> equals to $extension and can have any other key,
                        <emphasis>case</emphasis> equals to $case,
                    </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>: <classname>Zend_Validate_File_FilesSize($min, $max,
                            $bytestring)</classname>
                    </para></listitem>

                    <listitem><para>
                        New method <acronym>API</acronym>:
                        <methodname>Zend_Validate_File_FilesSize($options)</methodname> where $options
                        accepts the following array keys:
                        <emphasis>min</emphasis> equals to $min,
                        <emphasis>max</emphasis> equals to $max,
                        <emphasis>bytestring</emphasis> equals to $bytestring
                    </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>: <classname>Zend_Validate_File_Hash($hash,
                            $algorithm)</classname>
                    </para></listitem>

                    <listitem><para>
                        New method <acronym>API</acronym>: <methodname>Zend_Validate_File_Hash($options)</methodname>
                        where $options accepts the following array keys:
                        <emphasis>*</emphasis> equals to $hash and can have any other key,
                        <emphasis>algorithm</emphasis> equals to $algorithm,
                    </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>: <classname>Zend_Validate_File_ImageSize($minwidth,
                            $minheight, $maxwidth, $maxheight)</classname>
                    </para></listitem>

                    <listitem><para>
                        New method <acronym>API</acronym>:
                        <methodname>Zend_Validate_File_FilesSize($options)</methodname> where $options
                        accepts the following array keys: <emphasis>minwidth</emphasis> equals to
                        $minwidth, <emphasis>maxwidth</emphasis> equals to $maxwidth,
                        <emphasis>minheight</emphasis> equals to $minheight,
                        <emphasis>maxheight</emphasis> equals to $maxheight,
                    </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>: <classname>Zend_Validate_File_Size($min, $max,
                            $bytestring)</classname>
                    </para></listitem>

                    <listitem><para>
                        New method <acronym>API</acronym>: <methodname>Zend_Validate_File_Size($options)</methodname>
                        where $options accepts the following array keys:
                        <emphasis>min</emphasis> equals to $min,
                        <emphasis>max</emphasis> equals to $max,
                        <emphasis>bytestring</emphasis> equals to $bytestring
                    </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 isLocale() 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 isLocale() 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 getDefault() method has been change due to the fact that we
                integrated a framework locale which can be set with setDefault(). 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 getDefault() 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 false 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 true. It defaults to false.
            </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 API 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 (LFI) 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 LFI 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:
-->