Money

About 3 min

Money

Money class

This class is used to extend a normal integer value by adding currency related features such as the currency type (AUD, USD, JPY, etc) and realtime currency conversion using Yahoo Quotes.

Example

$aud = new Money(500, 'AUD');
$usd = new Money(200, 'USD');
$total = $aud->add($usd);

The default money format is '%.2n' which will format the value to whole dollar with 2 decimal places. ie: $123.45. You can specify the format when retrieving the amount (see self::format()) or you can set the default format at any time.

You can also set the default currency code to use when none is specified.

It is recommended that these be set in your bootstrap file so that they are consistent across the whole application.

Example bootstrap.php

Hazaar\self::$money_format = '%.0n';
Hazaar\self::$default_currency = 'AUD';

Properties

default_currency

public string $default_currency

value

private float $value

localCurrency

private array $localCurrency

db

public BTree $db

exchangeRates

private array $exchangeRates

cache

public Cache $cache

Methods

__construct

public  __construct({Array})

The money class constructors takes two parameters. The value of the currency and the type of currency the value is representative of.

Currency info is loaded from a built-in support file named countryInfo.txt. This file contains country information including country codes, currency names, etc. The first time a currency is used this information is loaded into memory only once and is shared between all currency objects.

A cache object is also set up for use by the exchange conversion methods. It will attempt to use the APC cache backend but if that is not available it will fall back to the file backend.

Parameters

Parameter	Type	Description
`$value`	`float`	The currency value amount
`$currency`	`string`	The name of the currency or country of origin. Ie: 'USD' and 'US' will both resolve

                    to US dollars. |

__toString

public  __toString({Array})

This magic function is called when PHP tries to automatically convert the currency to a string. Simply calls the self::toString() method.

getCurrencyInfo

Retrieves information about a currency.

public  getCurrencyInfo({Array})

Parameters

Parameter	Type	Description
`$currency`	`string`	The currency code. If null, returns information about all currencies.

getCurrencyCode

public  getCurrencyCode({Array})

Get either the default currency code, or get a currency code for a country. Use this instead of accessing self::default_currency directly because if self::$default_currency is not set, this will try and determine the default currency and set it automatically which will occur when a new Money object is created.

Parameters

Parameter	Type	Description
`$code`	`string`

getCode

public  getCode({Array})

Get the currency code for the current currency object or look up the currency code for a country. This value is normalised during object instantiation. This means that if you specify a country upon instantiation, this will still return the correct currency code.

Optionally, if a country parameter is specified, this method can be used to look up the currency code for that country.

Example

echo $currency->getCode('au');  //This will echo the string 'AUD'.

Parameters

Parameter	Type	Description
`$country`	`string`	optional country code to look up a currency code for

getCurrencySymbol

public  getCurrencySymbol({Array})

Get the symbol for the current currency. The currency symbol is usually prefixed to the currency amount. This method doesn't actually return the currency symbol as such, but will return the HTML entity name of the currency symbol, for example 'dollar', 'pound', 'yen', etc.

getExchangeRate

public  getExchangeRate({Array})

Get the current exchange rate for the currency value against a foreign currency. This method uses the Yahoo Quotes service to get the current exchange rate. For this method to work your host needs to have web access (ie: port 80). This should 'just work' for all but a small number of cases.

Because this method contacts another web service the response can be a little slow. Because of this results are cached so that subsequent requests for the same conversion will be faster.

Parameters

Parameter	Type	Description
`$foreignCurrency`	`string`	the foreign currency to get an exchange rate for

convertTo

public  convertTo({Array})

Convert the currency object to another currency and return a new Money object.

Parameters

Parameter	Type	Description
`$foreignCurrency`	`string`	The currency to convert to. Can be country or currency code.

format

public  format({Array})

The format method will format the currency value amount to an international standard format of {symbol}{amount}{code}. For example, US dollars will be expressed as $100USD. Australian dollar as $105AUD and so on.

Parameters

Parameter	Type	Description
`$format`	`string`	An optional format passed to the money_format function. If not specified the global

                  default format will be used. |

toString

public  toString({Array})

Convert currency to a string. Outputs the same as the self::format() method using the default format.

toFloat

public  toFloat({Array})

Get the currency as a float value formatted using the money_format PHP function with optional precision to specify the number of decimal places.

Parameters

Parameter	Type	Description
`$precision`	`int`	The number of decimal places to round to. Defaults to 2.

toCents

public  toCents({Array})

Get the currency value represented as an integer in cents. 1 dollar = 100 cents.

add

public  add({Array})

Add one or more amounts or Money objects to the current currency. Parameters here can be either a numeric value or another Money object. If the parameter is a Money object then the value will be automatically converted using the current exchange rate before it is added.

Parameters

Any number of numeric or Money objects parameters.

subtract

public  subtract({Array})

Subtract one or more values or Money objects from the current object. Parameters can be either a numeric value or another Money object. If the parameter is a Money object then the value will be automatically converted using the current exchange rate before it is subtracted.

set

Sets the value of the Money object.

public  set({Array})

Parameters

Parameter	Type	Description
`$value`	`string`	the value to set
`$currency`	`string`

getCurrencyName

Get the name of the currency.

public  getCurrencyName({Array})

Generated by Hazaar API Doc Generator