3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
15 * @copyright CiviCRM LLC https://civicrm.org/licensing
21 class CRM_Utils_Money
{
22 public static $_currencySymbols = NULL;
25 * Format a monetary string.
27 * Format a monetary string basing on the amount provided,
28 * ISO currency code provided and a format string consisting of:
30 * %a - the formatted amount
31 * %C - the currency ISO code (e.g., 'USD') if provided
32 * %c - the currency symbol (e.g., '$') if available
34 * @param float $amount
35 * The monetary amount to display (1234.56).
36 * @param string $currency
37 * The three-letter ISO currency code ('USD').
38 * @param string $format
39 * The desired currency format.
40 * @param bool $onlyNumber
41 * @param string $valueFormat
42 * The desired monetary value display format (e.g. '%!i').
45 * formatted monetary string
48 public static function format($amount, $currency = NULL, $format = NULL, $onlyNumber = FALSE, $valueFormat = NULL) {
50 if (CRM_Utils_System
::isNull($amount)) {
54 $config = CRM_Core_Config
::singleton();
57 $format = $config->moneyformat
;
61 $valueFormat = $config->moneyvalueformat
;
65 // money_format() exists only in certain PHP install (CRM-650)
66 if (is_numeric($amount) and function_exists('money_format')) {
67 $amount = money_format($valueFormat, $amount);
72 if (!self
::$_currencySymbols) {
73 self
::$_currencySymbols = CRM_Core_PseudoConstant
::get('CRM_Contribute_DAO_Contribution', 'currency', [
74 'keyColumn' => 'name',
75 'labelColumn' => 'symbol',
80 $currency = $config->defaultCurrency
;
83 // ensure $currency is a valid currency code
84 // for backwards-compatibility, also accept one space instead of a currency
85 if ($currency != ' ' && !array_key_exists($currency, self
::$_currencySymbols)) {
86 throw new CRM_Core_Exception("Invalid currency \"{$currency}\"");
89 $amount = self
::formatNumericByFormat($amount, $valueFormat);
90 // If it contains tags, means that HTML was passed and the
91 // amount is already converted properly,
92 // so don't mess with it again.
93 // @todo deprecate handling for the html tags because .... WTF
94 if (strpos($amount, '<') === FALSE) {
95 $amount = self
::replaceCurrencySeparators($amount);
101 '%c' => CRM_Utils_Array
::value($currency, self
::$_currencySymbols, $currency),
103 return strtr($format, $replacements);
107 * This is a placeholder function for calculating the number of decimal places for a currency.
109 * Currently code assumes 2 decimal places but some currencies (bitcoin, middle eastern) have
110 * more. By using this function we can signpost the locations where the number of decimal places is
111 * currency specific for future enhancement.
113 * @param string $currency
116 * Number of decimal places.
118 public static function getCurrencyPrecision($currency = NULL) {
123 * Subtract currencies using integers instead of floats, to preserve precision
125 * @param string|float $leftOp
126 * @param string|float $rightOp
127 * @param string $currency
130 * Result of subtracting $rightOp from $leftOp to the precision of $currency
132 public static function subtractCurrencies($leftOp, $rightOp, $currency) {
133 if (is_numeric($leftOp) && is_numeric($rightOp)) {
134 $precision = pow(10, self
::getCurrencyPrecision($currency));
135 return (($leftOp * $precision) - ($rightOp * $precision)) / $precision;
140 * Tests if two currency values are equal, taking into account the currency's
141 * precision, so that if the difference between the two values is less than
142 * one more order of magnitude for the precision, then the values are
143 * considered as equal. So, if the currency has precision of 2 decimal
144 * points, a difference of more than 0.001 will cause the values to be
145 * considered as different. Anything less than 0.001 will be considered as
150 * 1.2312 == 1.2319 with a currency precision of 2 decimal points
151 * 1.2310 != 1.2320 with a currency precision of 2 decimal points
152 * 1.3000 != 1.2000 with a currency precision of 2 decimal points
160 public static function equals($value1, $value2, $currency) {
161 $precision = 1 / pow(10, self
::getCurrencyPrecision($currency) +
1);
162 $difference = self
::subtractCurrencies($value1, $value2, $currency);
164 if (abs($difference) > $precision) {
172 * Format money for display (just numeric part) according to the current locale.
174 * This calls the underlying system function but does not handle currency separators.
176 * It's not totally clear when it changes the $amount value but has historical usage.
182 protected static function formatLocaleNumeric($amount) {
183 return self
::formatNumericByFormat($amount, CRM_Core_Config
::singleton()->moneyvalueformat
);
187 * Format money for display (just numeric part) according to the current locale with rounding.
189 * At this stage this is conceived as an internal function with the currency wrapper
190 * functions determining the number of places.
192 * This calls the underlying system function but does not handle currency separators.
194 * It's not totally clear when it changes the $amount value but has historical usage.
196 * @param string $amount
197 * @param int $numberOfPlaces
201 protected static function formatLocaleNumericRounded($amount, $numberOfPlaces) {
202 return self
::formatLocaleNumeric(round($amount, $numberOfPlaces));
206 * Format money for display (just numeric part) according to the current locale with rounding.
208 * This handles both rounding & replacement of the currency separators for the locale.
210 * @param string $amount
211 * @param string $currency
216 public static function formatLocaleNumericRoundedByCurrency($amount, $currency) {
217 $amount = self
::formatLocaleNumericRounded($amount, self
::getCurrencyPrecision($currency));
218 return self
::replaceCurrencySeparators($amount);
222 * Format money for display (just numeric part) according to the current locale with rounding based on the
223 * default currency for the site.
228 public static function formatLocaleNumericRoundedForDefaultCurrency($amount) {
229 return self
::formatLocaleNumericRoundedByCurrency($amount, self
::getCurrencyPrecision(CRM_Core_Config
::singleton()->defaultCurrency
));
233 * Replace currency separators.
235 * @param string $amount
239 protected static function replaceCurrencySeparators($amount) {
240 $config = CRM_Core_Config
::singleton();
242 ',' => $config->monetaryThousandSeparator
,
243 '.' => $config->monetaryDecimalPoint
,
245 return strtr($amount, $rep);
249 * Format numeric part of currency by the passed in format.
251 * This is envisaged as an internal function, with wrapper functions defining valueFormat
252 * into easily understood functions / variables and handling separator conversions and
255 * @param string $amount
256 * @param string $valueFormat
260 protected static function formatNumericByFormat($amount, $valueFormat) {
261 // money_format() exists only in certain PHP install (CRM-650)
262 // setlocale() affects native gettext (CRM-11054, CRM-9976)
263 if (is_numeric($amount) && function_exists('money_format')) {
264 $lc = setlocale(LC_MONETARY
, 0);
265 setlocale(LC_MONETARY
, 'en_US.utf8', 'en_US', 'en_US.utf8', 'en_US', 'C');
266 $amount = money_format($valueFormat, $amount);
267 setlocale(LC_MONETARY
, $lc);