CRM/Utils/Money.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   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  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  *
  14  * @package CRM
  15  * @copyright CiviCRM LLC https://civicrm.org/licensing
  16  */
  17
  18 use Brick\Money\Money;
  19 use Brick\Money\Context\DefaultContext;
  20 use Brick\Money\Context\CustomContext;
  21 use Brick\Math\RoundingMode;
  22
  23 /**
  24  * Money utilties
  25  */
  26 class CRM_Utils_Money {
  27   public static $_currencySymbols = NULL;
  28
  29   /**
  30    * Format a monetary string.
  31    *
  32    * Format a monetary string basing on the amount provided,
  33    * ISO currency code provided and a format string consisting of:
  34    *
  35    * %a - the formatted amount
  36    * %C - the currency ISO code (e.g., 'USD') if provided
  37    * %c - the currency symbol (e.g., '$') if available
  38    *
  39    * @param float $amount
  40    *   The monetary amount to display (1234.56).
  41    * @param string $currency
  42    *   The three-letter ISO currency code ('USD').
  43    * @param string $format
  44    *   The desired currency format.
  45    * @param bool $onlyNumber
  46    *
  47    * @return string
  48    *   formatted monetary string
  49    *
  50    */
  51   public static function format($amount, $currency = NULL, $format = NULL, $onlyNumber = FALSE) {
  52
  53     if (CRM_Utils_System::isNull($amount)) {
  54       return '';
  55     }
  56
  57     $config = CRM_Core_Config::singleton();
  58
  59     if (!$format) {
  60       $format = $config->moneyformat;
  61     }
  62
  63     if (!$currency) {
  64       $currency = $config->defaultCurrency;
  65     }
  66
  67     if ($onlyNumber) {
  68       $amount = self::formatLocaleNumericRoundedByCurrency($amount, $currency);
  69       return $amount;
  70     }
  71
  72     if (!self::$_currencySymbols) {
  73       self::$_currencySymbols = CRM_Core_PseudoConstant::get('CRM_Contribute_DAO_Contribution', 'currency', [
  74         'keyColumn' => 'name',
  75         'labelColumn' => 'symbol',
  76       ]);
  77     }
  78
  79     // ensure $currency is a valid currency code
  80     // for backwards-compatibility, also accept one space instead of a currency
  81     if ($currency != ' ' && !array_key_exists($currency, self::$_currencySymbols)) {
  82       throw new CRM_Core_Exception("Invalid currency \"{$currency}\"");
  83     }
  84
  85     if ($currency === ' ') {
  86       CRM_Core_Error::deprecatedWarning('Passing empty currency to CRM_Utils_Money::format is deprecated if you need it for display without currency call CRM_Utils_Money::formatLocaleNumericRounded');
  87     }
  88     $amount = self::formatUSLocaleNumericRounded($amount, 2);
  89     // If it contains tags, means that HTML was passed and the
  90     // amount is already converted properly,
  91     // so don't mess with it again.
  92     // @todo deprecate handling for the html tags because .... WTF
  93     if (strpos($amount, '<') === FALSE) {
  94       $amount = self::replaceCurrencySeparators($amount);
  95     }
  96
  97     $replacements = [
  98       '%a' => $amount,
  99       '%C' => $currency,
 100       '%c' => CRM_Utils_Array::value($currency, self::$_currencySymbols, $currency),
 101     ];
 102     return strtr($format, $replacements);
 103   }
 104
 105   /**
 106    * This is a placeholder function for calculating the number of decimal places for a currency.
 107    *
 108    * Currently code assumes 2 decimal places but some currencies (bitcoin, middle eastern) have
 109    * more. By using this function we can signpost the locations where the number of decimal places is
 110    * currency specific for future enhancement.
 111    *
 112    * @param string $currency
 113    *
 114    * @return int
 115    *   Number of decimal places.
 116    */
 117   public static function getCurrencyPrecision($currency = NULL) {
 118     return 2;
 119   }
 120
 121   /**
 122    * Subtract currencies using integers instead of floats, to preserve precision
 123    *
 124    * @param string|float $leftOp
 125    * @param string|float $rightOp
 126    * @param string $currency
 127    *
 128    * @return float
 129    *   Result of subtracting $rightOp from $leftOp to the precision of $currency
 130    */
 131   public static function subtractCurrencies($leftOp, $rightOp, $currency) {
 132     if (is_numeric($leftOp) && is_numeric($rightOp)) {
 133       $leftMoney = Money::of($leftOp, $currency, new DefaultContext(), RoundingMode::CEILING);
 134       $rightMoney = Money::of($rightOp, $currency, new DefaultContext(), RoundingMode::CEILING);
 135       return $leftMoney->minus($rightMoney)->getAmount()->toFloat();
 136     }
 137   }
 138
 139   /**
 140    * Tests if two currency values are equal, taking into account the currency's
 141    * precision, so that the two values are compared as integers after rounding.
 142    *
 143    * Eg.
 144    *
 145    * 1.231 == 1.232 with a currency precision of 2 decimal points
 146    * 1.234 != 1.236 with a currency precision of 2 decimal points
 147    * 1.300 != 1.200 with a currency precision of 2 decimal points
 148    *
 149    * @param $value1
 150    * @param $value2
 151    * @param $currency
 152    *
 153    * @return bool
 154    */
 155   public static function equals($value1, $value2, $currency) {
 156     $precision = pow(10, self::getCurrencyPrecision($currency));
 157
 158     return (int) round($value1 * $precision) == (int) round($value2 * $precision);
 159   }
 160
 161   /**
 162    * Format money for display (just numeric part) according to the current locale.
 163    *
 164    * This calls the underlying system function but does not handle currency separators.
 165    *
 166    * It's not totally clear when it changes the $amount value but has historical usage.
 167    *
 168    * @param $amount
 169    *
 170    * @return string
 171    */
 172   protected static function formatLocaleNumeric($amount) {
 173     return self::formatNumericByFormat($amount);
 174   }
 175
 176   /**
 177    * Format money for display (just numeric part) according to the current locale with rounding.
 178    *
 179    * At this stage this is conceived as an internal function with the currency wrapper
 180    * functions determining the number of places.
 181    *
 182    * This calls the underlying system function but does not handle currency separators.
 183    *
 184    * It's not totally clear when it changes the $amount value but has historical usage.
 185    *
 186    * @param string|float $amount
 187    * @param int $numberOfPlaces
 188    *
 189    * @return string
 190    */
 191   protected static function formatUSLocaleNumericRounded($amount, int $numberOfPlaces): string {
 192     if (!extension_loaded('intl') || !is_numeric($amount)) {
 193       // @todo - we should not attempt to format non-numeric strings. For now
 194       // these will not fail but will give notices on php 7.4
 195       self::missingIntlNotice();
 196       return self::formatNumericByFormat($amount, '%!.' . $numberOfPlaces . 'i');
 197     }
 198     $money = Money::of($amount, CRM_Core_Config::singleton()->defaultCurrency, new CustomContext($numberOfPlaces), RoundingMode::HALF_UP);
 199     // @todo - we specify en_US here because we don't want this function to do
 200     // currency replacement at the moment because
 201     // formatLocaleNumericRoundedByPrecision is doing it and if it
 202     // is done there then it is swapped back in there.. This is a short term
 203     // fix to allow us to resolve formatLocaleNumericRoundedByPrecision
 204     // and to make the function comments correct - but, we need to reconsider this
 205     // in master as it is probably better to use locale than our currency separator fields.
 206     $formatter = new \NumberFormatter('en_US', NumberFormatter::DECIMAL);
 207     $formatter->setAttribute(\NumberFormatter::MIN_FRACTION_DIGITS, $numberOfPlaces);
 208     return $money->formatWith($formatter);
 209   }
 210
 211   /**
 212    * Format money for display (just numeric part) according to the current locale with rounding.
 213    *
 214    * This handles both rounding & replacement of the currency separators for the locale.
 215    *
 216    * @param string $amount
 217    * @param string $currency
 218    *
 219    * @return string
 220    *   Formatted amount.
 221    */
 222   public static function formatLocaleNumericRoundedByCurrency($amount, $currency) {
 223     return self::formatLocaleNumericRoundedByPrecision($amount, self::getCurrencyPrecision($currency));
 224   }
 225
 226   /**
 227    * Format money for display (just numeric part) according to the current locale with rounding to the supplied precision.
 228    *
 229    * This handles both rounding & replacement of the currency separators for the locale.
 230    *
 231    * @param string $amount
 232    * @param int $precision
 233    *
 234    * @return string
 235    *   Formatted amount.
 236    */
 237   public static function formatLocaleNumericRoundedByPrecision($amount, $precision) {
 238     $amount = self::formatUSLocaleNumericRounded($amount, $precision);
 239     return self::replaceCurrencySeparators($amount);
 240   }
 241
 242   /**
 243    * Format money for display with rounding to the supplied precision but without padding.
 244    *
 245    * If the string is shorter than the precision trailing zeros are not added to reach the precision
 246    * beyond the 2 required for normally currency formatting.
 247    *
 248    * This handles both rounding & replacement of the currency separators for the locale.
 249    *
 250    * @param string $amount
 251    * @param int $precision
 252    *
 253    * @return string
 254    *   Formatted amount.
 255    */
 256   public static function formatLocaleNumericRoundedByOptionalPrecision($amount, $precision) {
 257     $decimalPlaces = self::getDecimalPlacesForAmount((string) $amount);
 258     $amount = self::formatUSLocaleNumericRounded($amount, $precision > $decimalPlaces ? $decimalPlaces : $precision);
 259     return self::replaceCurrencySeparators($amount);
 260   }
 261
 262   /**
 263    * Format money for display (just numeric part) according to the current locale with rounding based on the
 264    * default currency for the site.
 265    *
 266    * @param $amount
 267    * @return mixed
 268    */
 269   public static function formatLocaleNumericRoundedForDefaultCurrency($amount) {
 270     return self::formatLocaleNumericRoundedByCurrency($amount, self::getCurrencyPrecision(CRM_Core_Config::singleton()->defaultCurrency));
 271   }
 272
 273   /**
 274    * Replace currency separators.
 275    *
 276    * @param string $amount
 277    *
 278    * @return string
 279    */
 280   protected static function replaceCurrencySeparators($amount) {
 281     $config = CRM_Core_Config::singleton();
 282     $rep = [
 283       ',' => $config->monetaryThousandSeparator,
 284       '.' => $config->monetaryDecimalPoint,
 285     ];
 286     return strtr($amount, $rep);
 287   }
 288
 289   /**
 290    * Format numeric part of currency by the passed in format.
 291    *
 292    * This is envisaged as an internal function, with wrapper functions defining valueFormat
 293    * into easily understood functions / variables and handling separator conversions and
 294    * rounding.
 295    *
 296    * @param string $amount
 297    * @param string $valueFormat
 298    *
 299    * @return string
 300    */
 301   protected static function formatNumericByFormat($amount, $valueFormat = '%!i') {
 302     // money_format() exists only in certain PHP install (CRM-650)
 303     // setlocale() affects native gettext (CRM-11054, CRM-9976)
 304     if (is_numeric($amount) && function_exists('money_format')) {
 305       $lc = setlocale(LC_MONETARY, 0);
 306       setlocale(LC_MONETARY, 'en_US.utf8', 'en_US', 'en_US.utf8', 'en_US', 'C');
 307       $amount = money_format($valueFormat, $amount);
 308       setlocale(LC_MONETARY, $lc);
 309     }
 310     return $amount;
 311   }
 312
 313   /**
 314    * Emits a notice indicating we have fallen back to a less accurate way of formatting money due to missing intl extension
 315    */
 316   public static function missingIntlNotice() {
 317     CRM_Core_Session::singleton()->setStatus(ts('As this system does not include the PHP intl extension, CiviCRM has fallen back onto a slightly less accurate and deprecated method to format money'), ts('Missing PHP INTL extension'));
 318   }
 319
 320   /**
 321    * Get the number of characters after the decimal point.
 322    *
 323    * @param string $amount
 324    *
 325    * @return int
 326    */
 327   protected static function getDecimalPlacesForAmount(string $amount): int {
 328     $decimalPlaces = strlen(substr($amount, strpos($amount, '.') + 1));
 329     return $decimalPlaces;
 330   }
 331
 332 }