Flourish PHP Unframework

fMoney

class, v1.0.0b3

Represents a monetary value - USD are supported by default and others can be added via defineCurrency()

Changes:
1.0.0b3Added the $remove_zero_fraction parameter to format() 6/9/10
1.0.0b2Fixed a bug with calling format() when a format callback is set, fixed NULL $element handling in getCurrencyInfo() 3/24/09
1.0.0bThe initial implementation 8/10/08

Static Methods

::defineCurrency() public

Allows adding a new currency, or modifying an existing one

Signature

void defineCurrency( string $iso_code, string $name, string $symbol, integer $precision, string $value )

Parameters

string $iso_code The ISO code (three letters, e.g. 'USD') for the currency
string $name The name of the currency
string $symbol The symbol for the currency
integer $precision The number of digits after the decimal separator to store
string $value The value of the currency relative to some common standard between all currencies

::getCurrencies() public

Lists all of the defined currencies

Signature

array getCurrencies( )

Returns

The 3 letter ISO codes for all of the defined currencies

::getCurrencyInfo() public

Allows retrieving information about a currency

Signature

mixed getCurrencyInfo( string $iso_code, string $element=NULL )

Parameters

string $iso_code The ISO code (three letters, e.g. 'USD') for the currency
string $element The element to retrieve: 'name', 'symbol', 'precision', 'value'

Returns

An associative array of the currency info, or the element specified

::getDefaultCurrency() public

Gets the default currency

Signature

string getDefaultCurrency( )

Returns

The ISO code of the default currency

::registerFormatCallback() public

Allows setting a callback to translate or modify any return values from format()

Signature

void registerFormatCallback( callback $callback )

Parameters

callback $callback The callback to pass all fNumber objects to. Should accept an fNumber object, a string currency abbreviation and a boolean indicating if a zero-fraction should be removed - it should return a formatted string.

::registerUnformatCallback() public

Allows setting a callback to clean any formatted values so they can be passed to fNumber

Signature

void registerUnformatCallback( callback $callback )

Parameters

callback $callback The callback to pass formatted strings to. Should accept a formatted string and a currency code and return a string suitable to passing to the fNumber constructor.

::reset() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Resets the configuration of the class

Signature

void reset( )

::setDefaultCurrency() public

Sets the default currency to use when creating fMoney objects

Signature

void setDefaultCurrency( string $iso_code )

Parameters

string $iso_code The ISO code (three letters, e.g. 'USD') for the new default currency

Methods

->__construct() public

Creates the monetary to represent, with an optional currency

Signature

fMoney __construct( fNumber|string $amount, string $currency=NULL )

Parameters

fNumber|string $amount The monetary value to represent, should never be a float since those are imprecise
string $currency The currency ISO code (three letters, e.g. 'USD') for this value

Throws

fValidationException
When $amount is not a valid number/monetary value

->__get() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

All requests that hit this method should be requests for callbacks

Signature

callback __get( string $method )

Parameters

string $method The method to create a callback for

Returns

The callback for the method requested

->__toString() public

Returns the monetary value without a currency symbol or thousand separator (e.g. 2000.12)

Signature

string __toString( )

Returns

The monetary value without currency symbol or thousands separator

->add() public

Adds the passed monetary value to the current one

Signature

fMoney add( fMoney|string|integer $addend )

Parameters

fMoney|string|integer $addend The money object to add - a string or integer will be converted to the default currency (if defined)

Returns

The sum of the monetary values in this currency

Throws

fValidationException
When $addend is not a valid number/monetary value

->allocate() public

Splits the current value into multiple parts ensuring that the sum of the results is exactly equal to this amount

This method takes two or more parameters. The parameters should each be fractions that when added together equal 1.

Signature

array allocate( fNumber|string $ratio1, fNumber|string $ratio2, fNumber|string ... )

Parameters

fNumber|string $ratio1 The ratio of the first amount to this amount
fNumber|string $ratio2 [, ... ] The ratio of the second amount to this amount

Returns

fMoney objects each with the appropriate ratio of the current amount

Throws

fValidationException
When one of the ratios is not a number

->convert() public

Converts this money amount to another currency

Signature

fMoney convert( string $new_currency )

Parameters

string $new_currency The ISO code (three letters, e.g. 'USD') for the new currency

Returns

A new fMoney object representing this amount in the new currency

->eq() public

Checks to see if two monetary values are equal

Signature

boolean eq( fMoney|string|integer $money )

Parameters

fMoney|string|integer $money The money object to compare to - a string or integer will be converted to the default currency (if defined)

Returns

If the monetary values are equal

Throws

fValidationException
When $money is not a valid number/monetary value

->format() public

Formats the amount by preceeding the amount with the currency symbol and adding thousands separators

Signature

string format( boolean $remove_zero_fraction=FALSE )

Parameters

boolean $remove_zero_fraction If TRUE and all digits after the decimal place are 0, the decimal place and all zeros are removed

Returns

The formatted (and possibly converted) value

->getAmount() public

Returns the fNumber object representing the amount

Signature

fNumber getAmount( )

Returns

The amount of this monetary value

->getCurrency() public

Returns the currency ISO code

Signature

string getCurrency( )

Returns

The currency ISO code (three letters, e.g. 'USD')

->gt() public

Checks to see if this value is greater than the one passed

Signature

boolean gt( fMoney|string|integer $money )

Parameters

fMoney|string|integer $money The money object to compare to - a string or integer will be converted to the default currency (if defined)

Returns

If this value is greater than the one passed

Throws

fValidationException
When $money is not a valid number/monetary value

->gte() public

Checks to see if this value is greater than or equal to the one passed

Signature

boolean gte( fMoney|string|integer $money )

Parameters

fMoney|string|integer $money The money object to compare to - a string or integer will be converted to the default currency (if defined)

Returns

If this value is greater than or equal to the one passed

Throws

fValidationException
When $money is not a valid number/monetary value

->lt() public

Checks to see if this value is less than the one passed

Signature

boolean lt( fMoney|string|integer $money )

Parameters

fMoney|string|integer $money The money object to compare to - a string or integer will be converted to the default currency (if defined)

Returns

If this value is less than the one passed

Throws

fValidationException
When $money is not a valid number/monetary value

->lte() public

Checks to see if this value is less than or equal to the one passed

Signature

boolean lte( fMoney|string|integer $money )

Parameters

fMoney|string|integer $money The money object to compare to - a string or integer will be converted to the default currency (if defined)

Returns

If this value is less than or equal to the one passed

Throws

fValidationException
When $money is not a valid number/monetary value

->mul() public

Mupltiplies this monetary value times the number passed

Signature

fMoney mul( fNumber|string|integer $multiplicand )

Parameters

fNumber|string|integer $multiplicand The number of times to multiply this ammount - don't use a float since they are imprecise

Returns

The product of the monetary value and the multiplicand passed

Throws

fValidationException
When $multiplicand is not a valid number

->sub() public

Subtracts the passed monetary value from the current one

Signature

fMoney sub( fMoney|string|integer $subtrahend )

Parameters

fMoney|string|integer $subtrahend The money object to subtract - a string or integer will be converted to the default currency (if defined)

Returns

The difference of the monetary values in this currency

Throws

fValidationException
When $subtrahend is not a valid number/monetary value