repo_zf1/documentation/manual/en/module_specs/Zend_Locale-Migration.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.locale.migration">

    <title>Migrating from previous versions</title>

    <para>
        The <acronym>API</acronym> of <classname>Zend_Locale</classname> has changed from time to time.
        If you started to use <classname>Zend_Locale</classname> and its subcomponents
        in earlier versions follow the guidelines below to migrate your scripts to
        use the new <acronym>API</acronym>.
    </para>

    <sect2 id="zend.locale.migration.fromoneeighttoonenine">
        <title>Migrating from 1.8 to 1.9 or newer</title>
        <sect3 id="zend.locale.migration.fromoneeighttoonenine.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="zend.locale.migration.fromoneeighttoonenine.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="zend.locale.migration.fromoneseventooneeight">
        <title>Migrating from 1.7 to 1.8 or newer</title>
        <sect3 id="zend.locale.migration.fromoneseventooneeight.defaultcaching">
            <title>Default caching</title>

            <para>
                As with Zend Framework 1.8 a default caching was added. The reason behind this
                change was, that most users had performance problems but did not add caching at
                all. As the I18n core is a bottleneck when no caching is used we decided to add
                a default caching when no cache has been set to <classname>Zend_Locale</classname>.
            </para>

            <para>
                Sometimes it is still wanted to prevent caching at all even if this decreases
                performance. To do so you can simply disable caching by using the
                <methodname>disableCache()</methodname> method.
            </para>

            <example id="zend.locale.migration.fromoneseventooneeight.example">
                <title>Disabling default caching</title>

                <programlisting language="php"><![CDATA[
Zend_Locale::disableCache(true);
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.locale.migration.fromonesixtooneseven">
        <title>Migrating from 1.6 to 1.7 or newer</title>
        <sect3 id="zend.locale.migration.fromonesixtooneseven.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="zend.locale.migration.fromonesixtooneseven.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="zend.locale.migration.fromonesixtooneseven.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="zend.locale.migration.fromonesixtooneseven.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>
</sect1>