Location: PHPKode > scripts > CurrencyConvert > currencyconvert/readme.txt
***********************************************************************************

Name:       CurrencyConvert
Version:    2.0.4
Author:     Stephen Smith
            hide@address.com


Copyright © 2007-2009 Stephen Smith
email: hide@address.com

This file is part of CurrencyConvert.

CurrencyConvert is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

CurrencyConvert is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with CurrencyConvert; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

***********************************************************************************



Function
========
CurrencyConvert is a simple PHP4+ Class that performs online currency conversion
lookup, providing exchange rates between more than 150 currencies.

This Class scrapes currency converter pages; currently the data sources supported are:

Yahoo (default) - Yahoo! quotation file download at http://finance.yahoo.com/d/
Google          - Google Currency Converter at http://finance.google.com/finance/converter
Yahoo2          - Yahoo! Currency Converter at http://finance.yahoo.com/currency-converter

Please ensure that you acknowledge the source if you use this conversion Class.


Requirements
============
PHP 4.2.0 or higher
PHP cURL extension (for Google and Yahoo2 data sources)


Usage
=====
1:  Include the CurrencyConvert class file in your script.

        require_once( 'CurrencyConvert.class.php' ) ;

2.  Instantiate a CurrencyConvert object. The only parameter is the exchange rate source
    either 'Yahoo', 'Yahoo2' or 'Google' (defaults to 'Yahoo' if omitted).

        $quote = new CurrencyConvert( 'Google' ) ;

3.  [OPTIONAL] You can get a list of available currency symbols and names
    (as an array) by using the created object's currencies() method.

        $currency_list = $quote->currencies() ;

4.  Use the object to look up the exchange rates between two currencies. The first
    argument is the 'converting from' currency, the second is the 'converting to' 
    currency. You must use the three-character symbols for the currencies.

        $result = $quote->convert( 'GBP', 'EUR' ) ;

    If you are using Yahoo2 as the source, an optional third parameter can be used to 
    look up historical rates, and is the date for which you want the exchange rate; 
    if this parameter is omitted then most recent rate for the current day is used. 
    The date can be either a Unix timestamp or in a (US English) readable format.

        $result = $quote->convert( 'GBP', 'EUR', '23-Nov-2008' ) ;

        $result = $quote->convert( 'GBP', 'EUR', 1227398400 ) ;

    The convert() method carries out checks to make sure it can correctly parse the
    conversion response, and returns a boolean result to indicate the success of the
    lookup: TRUE if successful, FALSE if not. This can be used for error handling, e.g.:

        $quote->convert( 'GBP', 'EUR' ) or die( 'Exchange rate lookup failed' ) ;

5.  Use the created object to obtain a price for a given amount of the 'from' currency.
    Default value is 1.00 for the amount.

        $price = $quote->price( $amount ) ;

6.  [OPTIONAL] You can get a descriptive name for either of the currency symbols using
    the object's name() method; for example 'GBP' has the long name 'British Pound'.
    Valid names are 'from' and 'to'.

        $from_currency = $quote->name( 'from' ) ;


Example
=======
Example files are included in this distribution: example.php and example2.php


Notes
=====
No one data source is "best"; they each have advantages and disadvantages.

Google:    + Seems to most reliably return a valid result
           - Smaller range of currencies than the Yahoo! converters

Yahoo:     + Doesn't require cURL, and lower server overhead than the others
           + Wide range of currencies
           - Doesn't always return a result for all currencies; it's essential to check the
             success/failure result of the conversion

Yahoo2:    + Wide range of currencies
           + Historical rates
           - Doesn't always return a result for all currencies; it's essential to check the
             success/failure result of the conversion
           - Some conversions always fail; e.g. from USD to any other currency XXX. Changing
             the conversion direction often works, e.g. from XXX to USD! A conversion rate
             of exactly 1:1 should be regarded as suspect.



Change History
==============
1.0.1   Initial release
1.0.2   Added localised currency names array to allow display of non-English names
1.1.0   Parser updated to deal with changed Yahoo! page format
        Note: Bid and Ask prices no longer returned by Yahoo! (17-Dec-2008)
1.2.0   Added historical rate support
2.0.1   Added support for additional data sources and non-cURL methods
        Yahoo  - does not require cURL
        Google - requires cURL
        Yahoo2 - requires cURL
2.0.3	Updated for new Google converter URL
2.0.4	Updated for changed Google result page format

Return current item: CurrencyConvert