repo_zf1/documentation/manual/en/module_specs/Zend_Currency-Migrating.xml

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

    <title>Migrating from Previous Versions</title>

    <para>
        The <acronym>API</acronym> of <classname>Zend_Currency</classname> has changed in the past
        to enhance usability. If you started using <classname>Zend_Currency</classname> with a
        version which is mentioned in this chapter follow the guidelines below
        to migrate your scripts to the new <acronym>API</acronym>.
    </para>

    <sect2 id="zend.currency.usage.migration.fromonezerotwo">

        <title>Migrating from 1.0.2 to 1.0.3 or Newer</title>

        <para>
            Creating an object of <classname>Zend_Currency</classname> has become simpler.
            You no longer have to give a script or set it to <constant>NULL</constant>. The optional
            script parameter is now an option which can be set through the
            <methodname>setFormat()</methodname> method.
        </para>

        <programlisting language="php"><![CDATA[
$currency = new Zend_Currency($currency, $locale);
]]></programlisting>

        <para>
            The <methodname>setFormat()</methodname> method takes now an array of options. These
            options are set permanently and override all previously set values. Also a new option
            'precision' has been added. The following options have been refactored:
        </para>

        <itemizedlist mark='opencircle'>
            <listitem>
                <para>
                    <emphasis>position</emphasis>:
                    Replacement for the old 'rules' parameter.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>script</emphasis>:
                    Replacement for the old 'script' parameter.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>format</emphasis>:
                    Replacement for the old 'locale' parameter which does not
                    set new currencies but only the number format.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>display</emphasis>:
                    Replacement for the old 'rules' parameter.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>precision</emphasis>:
                    New parameter.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>name</emphasis>:
                    Replacement for the ole 'rules' parameter. Sets the full
                    currencies name.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>currency</emphasis>:
                    New parameter.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>symbol</emphasis>:
                    New parameter.
                </para>
            </listitem>
        </itemizedlist>

        <programlisting language="php"><![CDATA[
$currency->setFormat(array $options);
]]></programlisting>

        <para>
            The <methodname>toCurrency()</methodname> method no longer supports the optional
            'script' and 'locale' parameters. Instead it takes an options array which
            can contain the same keys as for the <methodname>setFormat()</methodname> method.
        </para>

        <programlisting language="php"><![CDATA[
$currency->toCurrency($value, array $options);
]]></programlisting>

        <para>
            The methods <methodname>getSymbol()</methodname>,
            <methodname>getShortName()</methodname>, <methodname>getName()</methodname>,
            <methodname>getRegionList()</methodname> and
            <methodname>getCurrencyList()</methodname> are no longer static and can be called
            from within the object. They return the set values of the object if no
            parameter has been set.
        </para>

    </sect2>

</sect1>