Currency Conversion WordPress Plugin

The plugin provides a number of methods that can be accessed by other plugins.

• GetCurrencyBy
• convertCurrency
• convertCurrencyStatic
• format
• getCurrencyList
• setOptions

The plugin is available as an object referenced by the $Xoogu_CurrencyConversion variable.
To access this variable from within a function you’ll need make sure you declare it as global scope.

//put the global $Xoogu_CurrencyConversion variable in scope
global $Xoogu_CurrencyConversion;
//use a smaller variable name as a shortcut
$cc = $Xoogu_CurrencyConversion;

Or:

$cc = $GLOBALS['Xoogu_CurrencyConversion'];

Alternatively, you can create a new Xoogu_CurrencyConversion object:

$cc = new Xoogu_CurrencyConversion();

General example:

function fetchItemDetails($itemID){
    //some code to get our item, set up an example
    $item = new stdClass();
    $item->ID=$itemID
    $item->price=50;
    $item->name='example item';
    
    //convert the item's price from USD to the user's local currency
    global $Xoogu_CurrencyConversion;
    //use a smaller variable name as a shortcut
    $cc = $Xoogu_CurrencyConversion;
    //get the user's currency from their IP address
    //price is already in USD for our example, so no need to convert the amount if the user's currency is USD
    if( ($to = $cc->getCurrencyByIP()) && $to->code != 'USD' ){
        //store the user's currency
        $item->convertedCurrency = $to->code;
        //convert the amount to the user's currency
        $item->convertedPrice = $cc->convertCurrency('USD', $to->code, $item->price);
    }
    return $item;
}

GetCurrencyBy

There are a number of methods you can use to get details of a currency to convert to:

$to = $cc->getCurrencyByCountry('AU'); //returns an object with currency details for the currency of Australia
$to = $cc->getCurrencyByIP(); //returns an object with currency details for the visitor's country based on their IP address
$to = $cc->getCurrencyBySymbol('$'); //returns an object with currency details for USD
$to = $cc->getCurrencyByCode('AUD'); //returns an object with currency details for AUD

An object (stdClass) will be returned containing the following properties:

• code – 3 digit ISO 4217 currency code e.g. AUD
• symbol – symbol for the currency, e.g. $
• name – short name of the currency e.g. Dollars
• symbol_entity_num – HTML / XML numeric entity for the currency symbol e.g. $
• symbol_entity_hex – HTML / XML hex entity for the currency symbol e.g. $
• full_name – full name of the currency in English e.g. Australian Dollar
• dec_places – number of decimal places the currency uses e.g. 2
• symbol_pref – whether this currency is the default for its symbol e.g. 0 (false)
• rate – the conversion rate with USD e.g. 0.913603

If getCurrencyByCountry or getCurrencyByIP are called, the returned object also includes the following properties:

• thousands_sep – The thousands separator used in that country e.g. ,
• dec_point – The decimal point character used in that country e.g. .
• symbol_pos – Whether the currency symbol should be positioned before the amount (0) or after (1)
• country – The 2 digit ISO 3166 country code that the data was retrieved for e.g. AU

convertCurrency

convertCurrency($from, $to, $amount=1)

The convertCurrency method can be used to convert from one currency to another and takes 3 parameters:

• $from The ISO 4217 currency code to convert from e.g. USD
• $to The ISO 4217 currency code to convert to e.g. AUD
• $a (optional) The amount to be converted e.g. 50. Will default to 1 if not provided, effectively giving you the exchange rate between the two currencies.

Example usage:

$from='USD';
$amount=50;
$convertedAmount = $cc->convertCurrency($from, $to->code, $amount);

convertCurrencyStatic

convertCurrencyStatic($from, $to, $amount=1, $postID)

The same as the convertCurrency method, but uses static conversion rates saved when a post/page was saved. (Assuming static rates is set in the plugin settings or the post contained a currencyConversion shortcode with the static attribute set to 1).

Note that $postID is optional, if supplied it should be the id of the post that the static conversion rates were saved for. If $postID is not supplied, then the method will use the current post, i.e. it should be called within the loop, and the global $post object must be available.

format

format($to, $a, $format, $content='', $dec_places)

The format method can be used to format an amount. It takes 5 parameters:

• $to Object containing the details for the country we are formatting the amount for (object returned by one of the getCurrencyBy methods)
• $a Amount of money
• $format The amount will be formatted based on this string, see function details for list
• $content (optional) Any content to pass into the format, replaces %o in $format. Defaults to an empty string
• $dec_places (optional) The number of decimal places to format the amount to. Defaults to the standard number of decimal places for the currency provided.

It will return the amount formatted as per the provided $format string

Example usage:

$format = '%asy %c';
$formattedAmount = $cc->format($to, $convertedAmount, $format);

Note that the currency will only be formatted according to the locale if $to contains country, thousands_sep, and from properties, i.e. if $to is the return value from getCurrencyByCountry or getCurrencyByIp.

getCurrencyList

This method can be used to retrieve an array of all supported currencies

Example usage: $currencyList = $cc->getCurrencyList();

setOptions

setOptions($options)

Can be used to set the options (settings) for the plugin to something other than the settings retrieved from the database. Setting a value to null will have the same effect as if no value is saved for that option (so can be used to nullify options the user has chosen). The options are only kept for the life of the object, and are not saved to the database.

Generally if you want to use an object with different options to what the user has set, you will be best instantiating a new instance of the class and then set options on that, rather than modifying the options on the instance created by the plugin.

Returns the object so you can use chaining with this method.

Example usage: $cc->setOptions(array('format' => '%asy %c', 'from' => 'CAD', 'dec_places' => null));

Possible options are:

• from – currency to convert from
• dec_places – number of decimal places to use
• static – whether to use static rates (bool)
• updateFreq – update rates frequency, though it would be pretty pointless to set this since it won’t be saved
• format – format string for formatting the converted amount
• geoFunc – function type used for looking up the user’s location from their IP address. Note you can only choose from the list supported by the plugin.