Sankuru

Quite a few people have complained in the Virtuemart forums about the very limited number of currencies supported by the convertECB.php currency convertor script. The ECB, that is, the European Central Bank, publishes daily exchange rates for just a handful of currencies. After a bit of googling, I came across http://foxrate.org. The currency exchange rates published at http://foxrate.org are collected by http://fxtrade.oanda.com, apparently, a quite serious currency trader.

So, I went about writing a plugin, convertFOX.php, in order to read the exchange rates from http://foxrate.org into Virtuemart. In a similar way to what the convertECB.php does, I cache the exchange rates in the cache directory for joomla. I simply use one file per currency. For example, EUR.txt, contains the exchange rate for the Euro. USD.txt contains the exchange rate for the US Dollar. And so on. The convertFOX.php plugin just looks up these files, and uses them for the exchange rate conversion. The convertFOX.php does not really know where these files come from. It just tries to find them in the cache directory, and when it finds them, it uses them. If it cannot find the file for a particular currency, the plugin will raise an error. Note that one currency file should simply contain the value 1. This currency is the home currency.

Now how to feed these files from the http://foxrate.org website?

Like in many ad-hoc server-side scripting projects, I tend to favour using the shell. It's simple, short, and easily debugged by looking at what output shows up at the command line. Errors are quickly corrected, and the thing is usually live in no time. You can find the scripts in the folder virtuemart-convert-fox-shellscripts.

The http://foxrate.org website exposes a freely accessible XML-RPC webservice to the outside world. In theory, I should bother about the XML-RPC protocol and how it functions. In this case, I just took a shortcut. The XML-RPC request is formatted as following:

<?xml version='1.0'?>
<methodCall>
           <methodName> foxrate.currencyConvert </methodName>
    <params>
        <param>
            <value>
                <string>CURR_TO</string>
            </value>
        </param>
        <param>
            <value>
                <string>CURR_FROM</string>
            </value>
        </param>
        <param>
            <value>
                <double>UNITS</double>
            </value>
        </param>
    </params>
</methodCall>

This template is stored in the file fox.org.rpc.request.template.  As you can see, we still need to replace CURR_FROM, CURR_TO, and UNITS. How do you replace variables in a template? There are many ways, but I am inclined to grab the sed utility:

#!/bin/sh

# written by Dit e-mailadres is beveiligd tegen spambots, u heeft JavaScript nodig om het te kunnen bekijken , feb 2009
# licensed under the General Public License, GPL (same as Virtuemart)


CURR_FROM=$1
CURR_TO=$2
UNITS=$3

sed -e "s/CURR_FROM/${CURR_FROM}/" \
    -e "s/CURR_TO/${CURR_TO}/" \
    -e "s/UNITS/${UNITS}/" \
    < fox.org.rpc.request.template

This script, fill-rpc-request-template.sh, will read the variables CURR_FROM, CURR_TO, and UNITS as commandline arguments, read the template file, and replace the variables in the template. The resulting output, will simply go to stdout. You could use Perl, Php, or any other language to replace these template variables. It wouldn't make any difference. I just like using sed, because it properly solves the problem without too much fuss. For example:

$ ./fill-rpc-request-template.sh EUR USD 1

Now we need to deliver the request to the http://foxrate.org site, by posting it over http to the http://foxrate.org/rpc address. Now, there are many ways to do this. I just grabbed curl for this job. Why? Because curl is not self-important. It just takes a file in, and then posts it to the address you told it to post it to, and then dumps the server response to stdout. The script rpc-fox-retrieve.sh does exactly that. No fuss, and easy to test:

#!/bin/sh


# written by Dit e-mailadres is beveiligd tegen spambots, u heeft JavaScript nodig om het te kunnen bekijken , feb 2009
# licensed under the General Public License, GPL (same as Virtuemart)

CURR_FROM=$1
CURR_TO=$2
UNITS=$3

request=`./fill-rpc-request-template.sh \
        $CURR_FROM $CURR_TO $UNITS`

curl -s --data "$request" http://foxrate.org/rpc
 

You can test the script by invoking it on the commandline:

$ ./rpc-fox-retrieve.sh EUR USD 1

The output looks like this:

<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value>
        <struct>
  <member><name>flerror</name><value><int>0</int></value></member>
  <member><name>amount</name><value><double>0.794</double></value></member>
  <member><name>message</name><value><string>cached</string></value></member>
</struct>
      </value>
    </param>
  </params>
</methodResponse>
 

Now, when I do extensive XML parsing at the command line, I tend to use XML Starlet (http://xmlstar.sourceforge.net). In this case, however, I thought that XML Starlet would be overkill. Also, it would require every user of these scripts to install XML Starlet.

In this case the sed utility would also perfectly well be able to handle the parsing. It needs to retrieve the member flerror. And when this value is zero (no error), retrieve the member amount, and save the value for amount to the currency file in the cache folder. The script rpc-fox.sh does this:

#!/bin/sh
# written by Dit e-mailadres is beveiligd tegen spambots, u heeft JavaScript nodig om het te kunnen bekijken , feb 2009
# licensed under the General Public License, GPL (same as Virtuemart)

CURR_FROM=$1
CURR_TO=$2
UNITS=$3
SAVETO_DIR=$4

response=$(./rpc-fox-retrieve.sh $CURR_FROM $CURR_TO $UNITS)
flerror=$(echo $response | \
   sed 's_\(.*\)<member><name>flerror</name><value><int>\(.*\)</int></value></member>\(.*\)_\2_')
if [ $flerror="0" ]; then
    #no error
    amount=$(echo $response | \
        sed 's_\(.*\)<member><name>amount</name><value><double>\(.*\)</double></value></member>\(.*\)_\2_')
    echo $amount > $SAVETO_DIR/$CURR_FROM.txt
    timestamp=$(date +"%Y-%m-%d--%H-%M-%S")
    echo $timestamp > $SAVETO_DIR/$CURR_FROM.lastupdated.txt   
else
    #error --> handle error
    echo "error retrieving the conversion rate $CURR_FROM $CURR_TO $UNITS"
fi

You can invoke the rpc-fox.sh script at the command line as in the example below:

$ ./rpc-fox.sh EUR USD 1 /var/www/cache

This command line invocation will retrieve the exchange rate EUR/USD from http://foxrate.org and store the result in the file /var/www/cache/EUR.txt. The script will also store the date it retrieved the exchange rate in the file /var/www/cache/EUR.lastupdated.txt.

If we need to retrieve five different exchange, we would need to invoke this script five times. One time for each currency. Of course,the exchange rate for the home currency would be 1. You can configure this in the script rpc-fox.config:

#!/bin/sh

#convert every currency into units of the following base currency
basecurr="USD"

#save all currency files to the following directory
savedir=/var/www/cache

#list all currencies for which the exchange rate must be retrieved, separated by spaces
currencies="EUR CHF"
 

The script rpc-fox-all.sh will use this configuration file to retrieve all exchange rates needed, and store each of them in its own currency file. It will also create a file with the exchange rate 1 for the home currency:

#!/bin/bash

source rpc-fox.config

for currency in $currencies
do
    ./rpc-fox.sh $currency $basecurr 1 $savedir
done
echo "1" > $savedir/$basecurr.txt

You can invoke the rpc-fox-all.sh script at the command line as in the example below:

$ ./rpc-fox-all.sh

After invoking the script, all exchange rates will be stored in their currency files in the cache directory. If you want to run this script on a daily basis, you can use the cron utility to schedule the execution of this script.