Money

Money class.

class Money

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\Util\Money::setDefaultCurrency('AUD');

Properties

defaultCurrency

public string $defaultCurrency

Type: string

value

private float $value

Type: float

localCurrency

private array $localCurrency

Type: array

db

public BTree $db

Type: Hazaar\Util\BTree

exchangeRates

private array $exchangeRates

Type: array

cache

public Adapter $cache

Type: Hazaar\Cache\Adapter

Methods

__construct

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

public __construct(float $value, ?string $currency): void

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

This magic function is called when PHP tries to automatically convert the currency to a string.

public __toString(): string

Returns: string

Simply calls the self::toString() method.

getDefaultCurrency

Get the currently configured default currency code, if any.

public getDefaultCurrency(): ?string

Returns: string

setDefaultCurrency

Set the default currency (or country) code used when none is specified explicitly.

public setDefaultCurrency(string $currency): void

Returns: void

The given code is validated and normalised against the built-in currency database, so an unrecognised code is rejected immediately rather than surfacing later as a failed lookup or conversion. This is typically called once in your application's bootstrap file, or per-context (eg: when switching between workspaces that each have their own base currency).

Example

Money::setDefaultCurrency('AUD');

Parameters

Parameter	Type	Description
$currency	string	the currency (eg: 'USD') or country (eg: 'US') code to use as the default

ensureDb

Ensures the internal currency information database is loaded.

private ensureDb(): void

Returns: void

getCurrencyInfo

Retrieves information about a currency.

public getCurrencyInfo(?string $currency): mixed

Returns: mixed

Parameters

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

getCurrencyCode

Get either the default currency code, or get a currency code for a country. Use this instead of

public getCurrencyCode(?string $code): string

Returns: string

accessing self$defaultCurrency 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

Get the currency code for the current currency object or look up the currency code for a country.

public getCode(?string $country): string

Returns: string

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

Get the symbol for the current currency. The currency symbol is usually prefixed to the currency

public getCurrencySymbol(): string

Returns: string

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

Get the current exchange rate for the currency value against a foreign currency. This method uses

public getExchangeRate(string $foreignCurrency): float

Returns: float

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

setExchangeRates

Seed exchange rates for a base currency, bypassing the upstream conversion API.

public setExchangeRates(string $base, array $rates): void

Returns: void

This is useful for offline operation, supplying application-provided rates, or for testing without relying on the live currency conversion service.

Parameters

Parameter	Type	Description
$base	string	the base currency code the rates are relative to (eg: 'AUD')
$rates	array	a map of foreign currency code to exchange rate

fetchExchangeRates

Fetch the latest exchange rates for a base currency from the upstream conversion service.

private fetchExchangeRates(string $base): ?array

Returns: array

Returns null on any failure (network error, non-2xx response, or an unexpected response body) so callers can decide how to handle an unavailable service rather than receiving a raw error from a failed request.

Parameters

Parameter	Type	Description
$base	string	the base currency code to fetch rates for

convertTo

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

public convertTo(string $foreignCurrency): Money

Returns: Hazaar\Util\Money

Parameters

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

format

The format method will format the currency value amount to an international standard format of

public format(?string $format): string

Returns: string

{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

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

public toString(): string

Returns: string

format.

toFloat

Get the currency value as a float, with an optional precision to round it to.

public toFloat(?int $precision): float

Returns: float

By default no rounding is applied - the raw value is returned at full precision. Rounding to whole cents by default would silently lose resolution below a cent (eg: an exchange-rate conversion that doesn't land on an exact cent amount), including for internal callers such as add() and subtract() that use this method to sum values before rounding is wanted.

Parameters

Parameter	Type	Description
$precision	int	The number of decimal places to round to. Defaults to null, meaning no rounding is performed.

toCents

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

public toCents(): int

Returns: int

add

Add one or more amounts or Money objects to the current currency. Parameters here can be either

public add(mixed $args): Money

Returns: Hazaar\Util\Money

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

Parameter	Type	Description
$args	mixed

subtract

Subtract one or more values or Money objects from the current object. Parameters can be either

public subtract(mixed $args): Money

Returns: Hazaar\Util\Money

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.

Parameters

Parameter	Type	Description
$args	mixed

set

Sets the value of the Money object.

public set(float|string $value, ?string $currency): float

Returns: float

Parameters

Parameter	Type	Description
$value	float	string
$currency	string

getCurrencyName

Get the name of the currency.

public getCurrencyName(): string

Returns: string

---

Generated by Hazaar API Doc Generator on Fri, 04 Sep 2026 23:32:17 +0000