CRM_Utils_Money
in package
Money utilties
Table of Contents
Properties
- $_currencySymbols : mixed
Methods
- equals() : bool
- Tests if two currency values are equal, taking into account the currency's precision, so that the two values are compared as integers after rounding.
- format() : string
- Format a monetary string.
- formatLocaleNumericRoundedByCurrency() : string
- Format money for display (just numeric part) according to the current locale with rounding.
- formatLocaleNumericRoundedByOptionalPrecision() : string
- Format money for display with rounding to the supplied precision but without padding.
- formatLocaleNumericRoundedByPrecision() : string
- Format money for display (just numeric part) according to the current locale with rounding to the supplied precision.
- formatLocaleNumericRoundedForDefaultCurrency() : mixed
- Format money for display (just numeric part) according to the current locale with rounding based on the default currency for the site.
- formatUSLocaleNumericRounded() : string
- Format money for display (just numeric part) according to the current locale with rounding.
- getCurrencyPrecision() : int
- This is a placeholder function for calculating the number of decimal places for a currency.
- missingIntlNotice() : mixed
- Emits a notice indicating we have fallen back to a less accurate way of formatting money due to missing intl extension
- subtractCurrencies() : float
- Subtract currencies using integers instead of floats, to preserve precision
- formatLocaleNumeric() : string
- Format money (or number) for display (just numeric part) according to the current or supplied locale.
- formatNumericByFormat() : string
- Format numeric part of currency by the passed in format.
- getDecimalPlacesForAmount() : int
- Get the number of characters after the decimal point.
- replaceCurrencySeparators() : string
- Replace currency separators.
Properties
$_currencySymbols
public
static mixed
$_currencySymbols
= \NULL
Methods
equals()
Tests if two currency values are equal, taking into account the currency's precision, so that the two values are compared as integers after rounding.
public
static equals(int|float $value1, int|float $value2, string $currency) : bool
Eg.
1.231 == 1.232 with a currency precision of 2 decimal points 1.234 != 1.236 with a currency precision of 2 decimal points 1.300 != 1.200 with a currency precision of 2 decimal points
Parameters
- $value1 : int|float
- $value2 : int|float
- $currency : string
Return values
boolformat()
Format a monetary string.
public
static format(float $amount[, string $currency = NULL ][, string $format = NULL ][, bool $onlyNumber = FALSE ]) : string
Format a monetary string basing on the amount provided, ISO currency code provided and a format string consisting of:
%a - the formatted amount %C - the currency ISO code (e.g., 'USD') if provided %c - the currency symbol (e.g., '$') if available
Parameters
- $amount : float
-
The monetary amount to display (1234.56).
- $currency : string = NULL
-
The three-letter ISO currency code ('USD').
- $format : string = NULL
-
The desired currency format.
- $onlyNumber : bool = FALSE
Return values
string —formatted monetary string
formatLocaleNumericRoundedByCurrency()
Format money for display (just numeric part) according to the current locale with rounding.
public
static formatLocaleNumericRoundedByCurrency(string $amount, string $currency) : string
This handles both rounding & replacement of the currency separators for the locale.
Parameters
- $amount : string
- $currency : string
Return values
string —Formatted amount.
formatLocaleNumericRoundedByOptionalPrecision()
Format money for display with rounding to the supplied precision but without padding.
public
static formatLocaleNumericRoundedByOptionalPrecision(string $amount, int $precision) : string
If the string is shorter than the precision trailing zeros are not added to reach the precision beyond the 2 required for normally currency formatting.
This handles both rounding & replacement of the currency separators for the locale.
Parameters
- $amount : string
- $precision : int
Return values
string —Formatted amount.
formatLocaleNumericRoundedByPrecision()
Format money for display (just numeric part) according to the current locale with rounding to the supplied precision.
public
static formatLocaleNumericRoundedByPrecision(string $amount, int $precision) : string
This handles both rounding & replacement of the currency separators for the locale.
Parameters
- $amount : string
- $precision : int
Return values
string —Formatted amount.
formatLocaleNumericRoundedForDefaultCurrency()
Format money for display (just numeric part) according to the current locale with rounding based on the default currency for the site.
public
static formatLocaleNumericRoundedForDefaultCurrency(mixed $amount) : mixed
Parameters
- $amount : mixed
formatUSLocaleNumericRounded()
Format money for display (just numeric part) according to the current locale with rounding.
public
static formatUSLocaleNumericRounded(string|float $amount, int $numberOfPlaces) : string
At this stage this is conceived as an internal function with the currency wrapper functions determining the number of places.
This calls the underlying system function but does not handle currency separators.
It's not totally clear when it changes the $amount value but has historical usage.
Parameters
- $amount : string|float
- $numberOfPlaces : int
Return values
stringgetCurrencyPrecision()
This is a placeholder function for calculating the number of decimal places for a currency.
public
static getCurrencyPrecision([string $currency = NULL ]) : int
Currently code assumes 2 decimal places but some currencies (bitcoin, middle eastern) have more. By using this function we can signpost the locations where the number of decimal places is currency specific for future enhancement.
Parameters
- $currency : string = NULL
Return values
int —Number of decimal places.
missingIntlNotice()
Emits a notice indicating we have fallen back to a less accurate way of formatting money due to missing intl extension
public
static missingIntlNotice() : mixed
subtractCurrencies()
Subtract currencies using integers instead of floats, to preserve precision
public
static subtractCurrencies(string|float $leftOp, string|float $rightOp, string $currency) : float
Parameters
- $leftOp : string|float
- $rightOp : string|float
- $currency : string
Return values
float —Result of subtracting $rightOp from $leftOp to the precision of $currency
formatLocaleNumeric()
Format money (or number) for display (just numeric part) according to the current or supplied locale.
protected
static formatLocaleNumeric(string $amount[, string $locale = NULL ][, string $currency = NULL ][, int $numberOfPlaces = 2 ]) : string
Note this should not be used in conjunction with any calls to replaceCurrencySeparators as this function already does that.
Parameters
- $amount : string
- $locale : string = NULL
- $currency : string = NULL
- $numberOfPlaces : int = 2
Tags
Return values
stringformatNumericByFormat()
Format numeric part of currency by the passed in format.
protected
static formatNumericByFormat(string $amount[, string $valueFormat = '%!i' ]) : string
This is envisaged as an internal function, with wrapper functions defining valueFormat into easily understood functions / variables and handling separator conversions and rounding.
Parameters
- $amount : string
- $valueFormat : string = '%!i'
Return values
stringgetDecimalPlacesForAmount()
Get the number of characters after the decimal point.
protected
static getDecimalPlacesForAmount(string $amount) : int
Parameters
- $amount : string
Return values
intreplaceCurrencySeparators()
Replace currency separators.
protected
static replaceCurrencySeparators(string $amount) : string
Parameters
- $amount : string