Currency & Exchange Helper

Currency Helper

The currency helper simply converts a cent amount into a formatted string of the users local currency (if available). Currently there are only a few local currencies we work with, these can be found in config/currency.php and are:

  • Australian

  • European

  • United States

  • Britain

  • New Zealand

  • Canadian

The currency helper will determine the correct currency to display based upon the users location.

Finding the Users Location

Vernon looks up a users location a number of ways, first starting with any address the user may have supplied. Perhaps they are registered and have provided a delivery/billing address, or perhaps they have provided an address along with an order they have placed.

If an address still can't be found then Vernon will do a Geo lookup on the users IP address, in fact most of the time Cloudflare provides the Geo location with the users headers, but if the site doesn't use Cloudflare it will do it manually for us.

If a location still can't be determined, then finally the system will just default to what has been set in the CMS under Settings > Site Settings

Using the Currency Helper

It's as simple as:

currency(12000)
// Returns something like $120.00AUD

Where 12000 is the currency denomination in cents. Running the helper actually creates an object with which we can access different parts of the currency makeup or provide extra methods to adjust the way the currency gets displayed.

Accessing the currency object

Pioneer\Vernon\Utility\Currency Object
(
    [string:protected] => %1$s%2$s%3$.2F%4$s
    [sign:protected] => 
    [symbol] => $
    [amount] => 120
    [tax] => 
    [tax_rate] => 
    [total] => 120
    [currency:protected] => AUD
    [country_code:protected] => AU
    [division_code:protected] => NSW
)

You are able to access any of the values (that are not marked 'protected') by appending the key to the helper itself.

currency(12000)->symbol // returns '$'
currency(12000)->amount // returns '120'
currency(12000)->total // returns '120'


Adjusting the Currency Object

Additional methods can be passed to further control the currency object, or the way it is displayed.

currency(12000)->noCurrency() // Returns '$120.00' A string without the country currency code
currency(12000)->withTax() // Returns '$132.00AUD' The amount with the country/state tax added
currency(12000)->withTax(15) // Force a specific tax percentage, Returns '$138.00AUD'
currency(12000)->justTax() // Returns '$12.00AUD'

The withTax method can be chained, for example:

currency(12000)->withTax()->noCurrency() // Returns '$132.00'

Exchange Helper

The exchange helper and currency helper can work hand in hand if you wish, where you can perform an exchange and pass it directly through to the currency helper. The exchange rate is refreshed once a day and will convert between any of these currencies:

  • Australian Dollar

  • United States Dollar

  • British Pound

  • Canadian Dollar

  • Euro

  • New Zealand Dollar

Using the Exchange Helper

The helper accepts three values, the amount (in cents), the source currency and the target currency. Both the source and target values are optional, and if not provided the exchange helper will determine them automatically. For the source currency it uses the default currency that has been set in config/currency.php and for the target currency it uses the users location.

This means that in most cases you only need to provide the amount you wish to convert to the exchange helper and it will make sure the correct currency value is displayed to the visitor.

For our purposes let's assume the user is visiting from the United States and the current exchange rate is 70 cents to the dollar.

exchange(12000) // Returns 8400

Like the currency helper, the exchange helper also creates an object where you can access specific parts of it.

Pioneer\Exchange\Utility\Exchange Object
(
    [amount] => 8400
    [symbol] => $
    [currency] => USD
    [country_code] => US
)

The object contains data of the currency we converted into, and each of those can be access by chaining the key to the helper, for example:

exchange(12000)->amount // Returns 8400
exchange(12000)->currency // Returns USD

As noted above we can also specifically set the source and target currencies, let's convert back to Australian Dollar

exchange(8400, 'USD', 'AUD') // Returns 12000

Coupling Exchange Helper with the Currency Helper

Of course, it's unlikely that we would ever want to just display that converted amount by itself. This is where using the exchange helper together with the currency helper becomes particularly useful and easy to use.

We can just pass the exchange helper right into the currency helper, like so:

currency(exchange(12000)) // Returns $84.00USD

There is no issue with using the exchange helper in most cases, as it will determine the users country of origin and if it matches the currency used by the site it won't bother calculating an exchange rate resulting in no overheads.