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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.currency.exchange">
    <title>Exchanging currencies</title>

    <para>
        Within the previous section we discussed currency calculations. But as you can imaging
        calculating currencies does often mean to calculate different currencies from different
        countries.
    </para>

    <para>
        In this case the currencies have to be exchanged so that both use the same currency.
        Within real live this information is available by banks or by daily papers. But as we
        are in web, we should use available exchange services.
        <classname>Zend_Currency</classname> allows their usage with a simple callback.
    </para>

    <para>
        First let's write a simple exchange service.
    </para>

    <programlisting language="php"><![CDATA[
class SimpleExchange implements Zend_Currency_CurrencyInterface
{
    public function getRate($from, $to)
    {
        if ($from !== "USD") {
            throw new Exception('We can only exchange USD');
        }

        switch ($to) {
            case 'EUR':
                return 2;
            case 'JPE':
                return 0.7;
       }

       throw new Exception('Unable to exchange $to');
    }
}
]]></programlisting>

    <para>
        We have now created a manual exchange service. It will not fit the real live, but it
        shows you how currency exchange works.
    </para>

    <para>
        Your exchange class must implement the
        <classname>Zend_Currency_CurrencyInterface</classname> interface. This interface
        requires the single method <methodname>getRate()</methodname> to be implemented. This
        method has two parameters it will receive. Both are the short names for the given
        currencies. <classname>Zend_Currency</classname> on the other side needs the exchange
        rate to be returned.
    </para>

    <para>
        In a living exchange class you would probably ask the service provider for the correct
        exchange rates. For our example the manual rate will be ok.
    </para>

    <para>
        Now we will simply attach our exchange class with <classname>Zend_Currency</classname>.
        There are two ways to do this. Eigher by attaching a instance of the Exchange class, or
        by simply giving a string with the classname.
    </para>

    <programlisting language="php"><![CDATA[
$currency = new Zend_Currency(
    array(
        'value'    => 1000,
        'currency' => 'EUR',
    )
);

$service  = new SimpleExchange();

// attach the exchange service
$currency->setService($service);

$currency2 = new Zend_Currency(
    array(
        'value'    => 1000,
        'currency' => 'USD',
    )
);

print $currency->add($currency2);
]]></programlisting>

    <para>
        The above example will return '$ 3.000' because the 1.000 <acronym>USD</acronym> will be
        converted by a rate of 2 to 2.000 <acronym>EUR</acronym>.
    </para>

    <note>
        <title>Calculation without exchange service</title>

        <para>
            When you try to calculate two currency objects which do not use the same currency
            and have no exchange service attached, you will get an exception. The reason is
            that <classname>Zend_Currency</classname> is then not able to switch between the
            different currencies.
        </para>
    </note>
</sect1>