<<css mode="next" class="sidebar"></css>> (((
- '''<a href="/docs/fMoney">Class Documentation</a>''' - <a href="/api/fMoney">API Reference</a> - <a href="https://github.com/flourishlib/flourish-classes/blob/master/fMoney.php" target="_blank">Source Code</a>
<<toc></toc>>
- fDate - '''fMoney''' - fNumber - fTime - fTimestamp
)))
The fMoney class is a value object for representing a monetary value. There is support for precise calculation, multiple currencies and formatting.
By default the fMoney class comes with a single defined currency USD (United States Dollar). fMoney is built in such a way that multiple currencies can be used and converted between, however there is no built-in functionality to fetch exchange rate information. A few sources of free exchange rate information include:
- <a href="http://foxrate.org" target="_blank">FoxRate.org</a> - <a href="http://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml" target="_blank">European Central Bank</a> - <a href="http://www.federalreserve.gov/releases/H10/update/h10daily.txt" target="_blank">Federal Reserve Bank</a> - <a href="http://www.imf.org/external/np/fin/data/rms_rep.aspx?tsvflag=Y" target="_blank">International Monetary Fund</a>
The rest of the documentation will assume that if multiple currencies are being used that the work has been done to fetch the appropriate exchange rate information in a regular fashion.
Whenever a system must use a currency other than USD, the new currency must be defined by calling ::defineCurrency(). This method takes a total of five parameters that define all of the relevant information about a currency. The parameters are `$iso_code`, `$name`, `$symbol`, `$precision` and `$value`.
Here is an example of defining the currency Pound Sterling:
The `$value` of a currency should be defined relative to USD, that is USD has a value of `1.00000000`.
Once a currency has been defined, information about it can be retrieved by using the method ::getCurrencyInfo(). There is one required parameter, `$iso_code`, which indicates what currency should be returned. A second optional parameter, `$element`, allows selecting a single piece of information including:
- `'name'` - `'symbol'` - `'precision'` - `'value'`
It is also possible to get a list of all currencies by calling ::getCurrencies().
While not required, setting a default currency is often useful, especially if only a single currency is supported. By setting the default currency, it is no longer necessary to specify the currency code when creating new fMoney objects.
The method ::setDefaultCurrency() accepts a single parameter, the `$iso_code` for the desired default currency. Below is an example of setting the default to United States Dollar:
The default currency can be retrieved by calling ::getDefaultCurrency().
Create an fMoney object requires either one or two parameters depending on whether or not a [#DefaultCurrency] has been set. If a default has not been set, or a currency other than the default is desired, an `$amount` and a `$currency` must be specified:
When setting the amount of an fMoney object, a float value should never be used due to the inherit loss of precision when storing floating point values. Instead, always use an integer, or a floating point value in a string.
If a default currency has been set and the default currency is desired, only a single parameter, `$amount` is required:
Note that by default the currency symbol and all commas (,) will be removed from any monetary value before parsing it as a number. For details about how to customize this behaviour, please see the [#Localization].
There are two accessors for the fMoney class, ::getAmount() and ::getCurrency() which return the amount of the value and the currency respectively.
will output the following:
Comparison of fMoney objects is accomplished by the method ::eq(), ::gt(), ::gte(), ::lt() and ::lte(). Each method will convert any non USD values to USD before comparison to ensure that comparisons are done correctly. Below is a table of the comparison methods:
|| Method || Comparison || || ::eq() || If the two values are equal || || ::gt() || If the object being called is greater than the value or object passed || || ::gte() || If the object being called is greater than or equal to the value or object passed || || ::lt() || If the object being called is less than the value or object passed || || ::lte() || If the object being called is less than or equal to the value being passed ||
It is possible to pass values other than an fMoney object for comparison. These values will be converted to an fMoney object using the default currency if defined. If no default currency is defined, an exception will be thrown.
Here are a few examples:
fMoney objects can be added, subtracted, multiplied and allocated (non-lossy division). All math operations are performed using an extra digit of precision and then the results are rounded using the common method. All math operations also take into account different currencies, with the result being in the currency of the object being called.
Please be sure to avoid floating point numbers in PHP when working with monetary values. Their inherent lack of precision make them a poor choice for precise calculations. Instead, use strings containing floating decimal values.
Addition is accomplished using the method ::add(). A single parameter, `$addend`, is required. The addend may be an fMoney object, or a string or integer if a default currency is defined.
Subtraction is accomplished by the method ::sub(). A single parameter, `$subtrahend`, is required. The subtrahend may be an fMoney object, or a string or integer if a default currency is defined.
To multiply a monetary value, simply pass a string, integer, or fNumber multiplier to ::mul().
Instead of providing a division method, which can easily lead to missing pennies, the fMoney class provides the method ::allocate(). This method splits up a monetary value into chunks that total the original value.
`allocate()` accepts two or more parameters, each being a string or fNumber fraction that represents the portion of the total each result should hold. The result is an array of fMoney objects with as many elements as parameters specified.
The resulting monetary values will always add up to exactly the original value. This prevents money from being lost in calculations.
If you have defined at least one currency other than USD (such as we did with GBP in the [#Currencies]) you can convert monetary values between currencies on the fly. The method ::convert() requires a single parameter, the ISO code of the currency to convert to.
Normally when displaying a monetary value it is desired to display the currency symbol and the value in a standard format with separators at the thousands, millions, etc. The method ::format() will perform such formatting.
will output the following:
If the parameter `$remove_zero_fraction` is set to `TRUE` and the value has a fraction that is just zeros, the resulting output will not contain a decimal point or a fraction.
The method ::__toString() will return the value without the currency symbol or the thousands separators.
will output the following:
When formatting monetary values in different locales, it will often be the case that the thousands separator and decimal point are different than the one in the United States. The methods ::registerFormatCallback() and ::registerUnformatCallback() allow for both creating a different formatting and also removing such formatting when creating a new fMoney object.