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

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

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

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

        <sect3 id="migration.19.zend.file.transfer.mimetype">
            <title>MimeType validation</title>

            <para>
                For security reasons we had to turn off the default fallback mechanism of the
                <classname>MimeType</classname>, <classname>ExcludeMimeType</classname>,
                <classname>IsCompressed</classname> and <classname>IsImage</classname> validators.
                This means, that if the <emphasis>fileInfo</emphasis> or
                <emphasis>magicMime</emphasis> extensions can not be found, the validation will
                always fail.
            </para>

            <para>
                If you are in need of validation by using the <acronym>HTTP</acronym> fields which
                are provided by the user then you can turn on this feature by using the
                <methodname>enableHeaderCheck()</methodname> method.
            </para>

            <note>
                <title>Security hint</title>

                <para>
                    You should note that relying on the <acronym>HTTP</acronym> fields, which are
                    provided by your user, is a security risk. They can easily be changed and could
                    allow your user to provide a malcious file.
                </para>
            </note>

            <example id="migration.19.zend.file.transfer.example">
                <title>Allow the usage of the HTTP fields</title>

                <programlisting language="php"><![CDATA[
// at initiation
$valid = new Zend_File_Transfer_Adapter_Http(array('headerCheck' => true);

// or afterwards
$valid->enableHeaderCheck();
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="migration.19.zend.filter">
        <title>Zend_Filter</title>

        <para>
            Prior to the 1.9 release, <classname>Zend_Filter</classname> allowed
            the usage of the static <methodname>get()</methodname> method. As with
            release 1.9 this method has been renamed to
            <methodname>filterStatic()</methodname> to be more descriptive. The
            old <methodname>get()</methodname> method is marked as deprecated.
        </para>
    </sect2>

    <sect2 id="migration.19.zend.http.client">
        <title>Zend_Http_Client</title>

        <sect3 id="migration.19.zend.http.client.fileuploadsarray">
            <title>Changes to internal uploaded file information storage</title>

            <para>
                In version 1.9 of Zend Framework, there has been a change in the way
                <classname>Zend_Http_Client</classname> internally stores information about
                files to be uploaded, set using the <methodname>Zend_Http_Client::setFileUpload()</methodname>
                method.
            </para>

            <para>
                This change was introduced in order to allow multiple files to be uploaded
                with the same form name, as an array of files. More information about this issue
                can be found in <ulink url="http://framework.zend.com/issues/browse/ZF-5744">this bug report</ulink>.
            </para>

            <example id="migration.19.zend.http.client.fileuploadsarray.example">
                <title>Internal storage of uploaded file information</title>

                <programlisting language="php"><![CDATA[
// Upload two files with the same form element name, as an array
$client = new Zend_Http_Client();
$client->setFileUpload('file1.txt',
                       'userfile[]',
                       'some raw data',
                       'text/plain');
$client->setFileUpload('file2.txt',
                       'userfile[]',
                       'some other data',
                       'application/octet-stream');

// In Zend Framework 1.8 or older, the value of
// the protected member $client->files is:
// $client->files = array(
//     'userfile[]' => array('file2.txt',
                             'application/octet-stream',
                             'some other data')
// );

// In Zend Framework 1.9 or newer, the value of $client->files is:
// $client->files = array(
//     array(
//         'formname' => 'userfile[]',
//         'filename' => 'file1.txt,
//         'ctype'    => 'text/plain',
//         'data'     => 'some raw data'
//     ),
//     array(
//         'formname' => 'userfile[]',
//         'filename' => 'file2.txt',
//         'formname' => 'application/octet-stream',
//         'formname' => 'some other data'
//     )
// );
]]></programlisting>
            </example>

            <para>
                As you can see, this change permits the usage of the same form element name with
                more than one file - however, it introduces a subtle backwards-compatibility change
                and as such should be noted.
            </para>
        </sect3>

        <sect3 id="migration.19.zend.http.client.getparamsrecursize">
            <title>Deprecation of Zend_Http_Client::_getParametersRecursive()</title>

            <para>
                Starting from version 1.9, the protected method <methodname>_getParametersRecursive()</methodname>
                is no longer used by <classname>Zend_Http_Client</classname> and is deprecated.
                Using it will cause an E_NOTICE message to be emitted by <acronym>PHP</acronym>.
            </para>

            <para>
                If you subclass <classname>Zend_Http_Client</classname> and call this method, you
                should look into using the <methodname>Zend_Http_Client::_flattenParametersArray()</methodname>
                static method instead.
            </para>

            <para>
                Again, since this <classname>_getParametersRecursive</classname> is a protected method,
                this change will only affect users who subclass <classname>Zend_Http_Client</classname>.
            </para>
        </sect3>
    </sect2>

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

        <sect3 id="migration.19.zend.locale.depreciated">
            <title>Depreciated methods</title>

            <para>
                Some specialized translation methods have been depreciated because they duplicate
                existing behaviour. Note that the old methods will still work, but a user notice is
                triggered which describes the new call. The methods will be erased with 2.0.
                See the following list for old and new method call.
            </para>

            <table id="migration.19.zend.locale.depreciated.table-1">
                <title>List of measurement types</title>

                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>Old call</entry>
                            <entry>New call</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>getLanguageTranslationList($locale)</entry>
                            <entry>getTranslationList('language', $locale)</entry>
                        </row>
                        <row>
                            <entry>getScriptTranslationList($locale)</entry>
                            <entry>getTranslationList('script', $locale)</entry>
                        </row>
                        <row>
                            <entry>getCountryTranslationList($locale)</entry>
                            <entry>getTranslationList('territory', $locale, 2)</entry>
                        </row>
                        <row>
                            <entry>getTerritoryTranslationList($locale)</entry>
                            <entry>getTranslationList('territory', $locale, 1)</entry>
                        </row>
                        <row>
                            <entry>getLanguageTranslation($value, $locale)</entry>
                            <entry>getTranslation($value, 'language', $locale)</entry>
                        </row>
                        <row>
                            <entry>getScriptTranslation($value, $locale)</entry>
                            <entry>getTranslation($value, 'script', $locale)</entry>
                        </row>
                        <row>
                            <entry>getCountryTranslation($value, $locale)</entry>
                            <entry>getTranslation($value, 'country', $locale)</entry>
                        </row>
                        <row>
                            <entry>getTerritoryTranslation($value, $locale)</entry>
                            <entry>getTranslation($value, 'territory', $locale)</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect3>
    </sect2>

    <sect2 id="migration.19.zend.view.helper.navigation">
        <title>Zend_View_Helper_Navigation</title>

        <para>
            Prior to the 1.9 release, the menu helper
            (<classname>Zend_View_Helper_Navigation_Menu</classname>) did not
            render sub menus correctly. When the <code>onlyActiveBranch</code>
            was <constant>TRUE</constant> and the option <code>renderParents</code>
            <constant>FALSE</constant>, nothing would be rendered if the deepest active
            page was at a depth lower than the <code>minDepth</code> option.
        </para>

        <para>
            In simpler words; if <code>minDepth</code> was set to <code>1</code>
            and the active page was at one of the first level pages, nothing
            would be rendered, as the following example shows.
        </para>

        <para>
            Consider the following container setup:
        </para>

        <programlisting language="php"><![CDATA[
<?php
$container = new Zend_Navigation(array(
    array(
        'label' => 'Home',
        'uri'   => '#'
    ),
    array(
        'label'  => 'Products',
        'uri'    => '#',
        'active' => true,
        'pages'  => array(
            array(
                'label' => 'Server',
                'uri'   => '#'
            ),
            array(
                'label' => 'Studio',
                'uri'   => '#'
            )
        )
    ),
    array(
        'label' => 'Solutions',
        'uri'   => '#'
    )
));
]]></programlisting>

        <para>
            The following code is used in a view script:
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->navigation()->menu()->renderMenu($container, array(
    'minDepth'         => 1,
    'onlyActiveBranch' => true,
    'renderParents'    => false
)); ?>
]]></programlisting>

        <para>
            Before release 1.9, the code snippet above would output nothing.
        </para>

        <para>
            Since release 1.9, the <methodname>_renderDeepestMenu()</methodname> method in
            <classname>Zend_View_Helper_Navigation_Menu</classname> will accept
            active pages at one level below <code>minDepth</code>, as long as
            the page has children.
        </para>

        <para>
            The same code snippet will now output the following:
        </para>

        <programlisting language="html"><![CDATA[
<ul class="navigation">
    <li>
        <a href="#">Server</a>
    </li>
    <li>
        <a href="#">Studio</a>
    </li>
</ul>
]]></programlisting>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->