+------+
| Note |
+------+

Read QUICKINSTALL if you want to get it running immediately. If any problems
occur, come back here to read the detailed installation instructions.

+--------------+
| Requirements |
+--------------+

Following packages are strongly recommended - but there are workarounds
provided if you do not have the possibility to use this packages.

* BCMath [ http://www.php.net/manual/en/ref.bc.php ]
  
* PHP as binary/CLI (command line interface)
  (Have a look whether there is a /usr/bin/php or /usr/local/bin/php)
  
* A scheduler (such as cron)

+--------------------+
| Installation Guide |
+--------------------+

This will explain how to install and use this package.

1. "Convert Currency" caches exchange rates as files in ./cache/ to allow faster
   operation. Of course this cache has to be updated regularly. There are two
   methods to accomplish this:

1.1  The first method is the less recommended one. It is listed first, because
     the average user will not have access to the required tools (cron etc.)
     to do it "right".

     First, make sure that the "cache" folder is writeable. You can do this by
     adding [w]rite and e[x]ecute permissions to "others/world/public" (or a
     similar term. This varies from program to program).
   
     Most FTP programs support this. Just right click the folder, chose "chmod"
     and activate this permissions. 

       [x] read
       [x] write
       [x] execute
        
     You could now fine-tune the time the cached data stays valid. Change the
     number of seconds with this variable [currency.php]:
   
       var $cache_time = 86400;
     
     where 86400 seconds is one day.

     This method is less recommended because it will call the update() function
     whenever the cached data has expired - thus, whoever requests your page
     then has to wait until the data has been refreshed. This is not a problem
     if you don't mind to wait a few additional seconds from time to time, but
     it can be a pain on a heavily loaded site.

1.2  Refreshing the cache with a scheduler is the recommended way of doing
     it. Create a cron-job by entering
   
       crontab -e
     
     and add the following line:

       0 0 * * * /path/to/update.php

     This would update the cache daily at midnight. Please read your local
     manpage "man crontab" about cron's data format.
   
     This also requires PHP als binary - have a look at the first line
     of [update.php] and adjust the path if necessary.
   
     If you have access to cron but there is no PHP as binary, then you might
     try something like this (don't forget to remove the #!/usr/bin/php when
     you are doing this):
   
       0 0 * * * lynx -dump http://host/path/to/update.php

     or

       0 0 * * * curl http://host/path/to/update.php
     
     Lynx is part of most linux distributions nowadays - curl is less
     widespread.

     Now open [currency.php] and disable auto-update:
   
       var $auto_update = false;   

     Note: the $cache_time has no meaning if you update the cache this way.
           It is only used when $auto_update is true.

2. The next thing is to check whether you have BCMath installed or not. You
   could either just start the script and see whether it spits out errors or
   not (try example.php) - or you could have a quick look at phpinfo().

   If BCMath is missing, open [currency.php] in your editor and
   uncomment the line where it says something like this (at the top):

     /* Uncomment this if you are missing the BCMath package
        ... */
     // include dirname(__FILE__) . "/bcmath.php";

   Just remove // in front of include. This will load "bcmath.php" which uses
   PHP's internal functions instead of BCMath. Just be warned, that these are
   not very precise.

3. After the package has been installed you have to learn how to use it.
   First, include the package, then create an instance of the class:
   
     include "currency.php";   
     $currency = new oanda_currency();

   Now do a conversion:
   
     $currency->convert(1, "USD", "CHF");
     
   to convert 1 USD to swiss francs. The function prototype is:
   
     function convert($value, $from, $to)         

   You will receive a number with many decimal places. I suggest you to use
   number_format() to make a nice output of it [ http://php.net/number_format ]

     echo number_format($currency->convert(1, "USD", "CHF"), 2) . " CHF<br>\n";

+------------------+
| Developers guide |
+------------------+

This will explain how to extend this package by writing your own handler
for any arbitrary data source.

First open [currency.php] and scroll down to the bottom. You will see
the provided example, the "oanda_currency" class.

In order to write your handler you have to create your own class which extends
the base class "currency". You don't necessarily have to know how the base class
works - just stick to the instructions and everything should work fine. 
   
  class my_currency extends currency {
 
  }
     
There are two things you have to rewrite from the base class: the file where
your data is cached and the update() function which refreshes the cache.
   
  class my_currency extends currency {

    var $cache_file = "cache/my.cache";
    
    function update() {
    
    }
  }

Note: You have to prepend the directory "cache" manually to the path.

The function update() has four things to do, of which step 1 and 4
stay same.

  1. Discard old data
  2. Retrieve new data
  3. Store into $this->exchange_rates
  4. Save data to disk

This looks like this:

  class my_currency extends currency {

    var $cache_file = "cache/my.cache";
    
    function update() {

      /*  1. Discard old data */
      unset($this->exchange_rates);

      /*  2. Retrieve new data
       *     fetch_url($url) retrieves a website and returns it as string
       *
       *     Then do some parsing stuff. This looks different depending
       *     on the data source (a website, an XML source, ..)
       */
      
      $page = $this->fetch_url("http://www.example.com/");
      
      /*  3. Store into $this->exchange_rates
       *     This is an associative array ("hash") with the format
       *    
       *       $this->exchange_rates[$from][$to] = $factor;
       *    
       *     Where $from and $to are currency codes such as USD, CHF, EUR
       *     and $factor is the factor used to convert the currency.
       *
       *     You also have to set the base currency:
       *
       *       $this->exchange_rates['base_currency'] = "USD";
       *
       *     (I usually also create a variable $base because it's
       *      used very often and improves the code readability)
       *
       *     Note: Make sure to stick to the functions from BCMath on
       *           any mathematical operations (instead of using PHP's
       *           mathematical operators such as +-*/%)
       */

      $this->exchange_rates['base_currency'] = $base = "USD";
      
      $this->exchange_rates[$base]["CHF"] = 1.6672;
      $this->exchange_rates["CHF"][$base] = 0.5999;
      
      $this->exchange_rates[$base]["CAD"] = 1.5773;
      $this->exchange_rates["CAD"][$base] = 0.6341;
      
      /*  4. Save it to disk */
       
      return $this->serialize_to_file($this->exchange_rates, $this->storage_path);
    }
  }

Have a closer look at my example if this does not make sense - or do a
var_dump($currency->exchange_rates); to see how it's built up.

That's it.