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 /**
  19  * Money utilties
  20  */
  21 class CRM_Utils_Money {
  22   public static $_currencySymbols = NULL;
  23
  24   /**
  25    * Format a monetary string.
  26    *
  27    * Format a monetary string basing on the amount provided,
  28    * ISO currency code provided and a format string consisting of:
  29    *
  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
  33    *
  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').
  43    *
  44    * @return string
  45    *   formatted monetary string
  46    *
  47    */
  48   public static function format($amount, $currency = NULL, $format = NULL, $onlyNumber = FALSE, $valueFormat = NULL) {
  49
  50     if (CRM_Utils_System::isNull($amount)) {
  51       return '';
  52     }
  53
  54     $config = CRM_Core_Config::singleton();
  55
  56     if (!$format) {
  57       $format = $config->moneyformat;
  58     }
  59
  60     if (!$valueFormat) {
  61       $valueFormat = $config->moneyvalueformat;
  62     }
  63
  64     if ($onlyNumber) {
  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);
  68       }
  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     if (!$currency) {
  80       $currency = $config->defaultCurrency;
  81     }
  82
  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}\"");
  87     }
  88
  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);
  96     }
  97
  98     $replacements = [
  99       '%a' => $amount,
 100       '%C' => $currency,
 101       '%c' => CRM_Utils_Array::value($currency, self::$_currencySymbols, $currency),
 102     ];
 103     return strtr($format, $replacements);
 104   }
 105
 106   /**
 107    * This is a placeholder function for calculating the number of decimal places for a currency.
 108    *
 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.
 112    *
 113    * @param string $currency
 114    *
 115    * @return int
 116    *   Number of decimal places.
 117    */
 118   public static function getCurrencyPrecision($currency = NULL) {
 119     return 2;
 120   }
 121
 122   /**
 123    * Subtract currencies using integers instead of floats, to preserve precision
 124    *
 125    * @param string|float $leftOp
 126    * @param string|float $rightOp
 127    * @param string $currency
 128    *
 129    * @return float
 130    *   Result of subtracting $rightOp from $leftOp to the precision of $currency
 131    */
 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;
 136     }
 137   }
 138
 139   /**
 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
 146    * equal.
 147    *
 148    * Eg.
 149    *
 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
 153    *
 154    * @param $value1
 155    * @param $value2
 156    * @param $currency
 157    *
 158    * @return bool
 159    */
 160   public static function equals($value1, $value2, $currency) {
 161     $precision = 1 / pow(10, self::getCurrencyPrecision($currency) + 1);
 162     $difference = self::subtractCurrencies($value1, $value2, $currency);
 163
 164     if (abs($difference) > $precision) {
 165       return FALSE;
 166     }
 167
 168     return TRUE;
 169   }
 170
 171   /**
 172    * Format money for display (just numeric part) according to the current locale.
 173    *
 174    * This calls the underlying system function but does not handle currency separators.
 175    *
 176    * It's not totally clear when it changes the $amount value but has historical usage.
 177    *
 178    * @param $amount
 179    *
 180    * @return string
 181    */
 182   protected static function formatLocaleNumeric($amount) {
 183     return self::formatNumericByFormat($amount, CRM_Core_Config::singleton()->moneyvalueformat);
 184   }
 185
 186   /**
 187    * Format money for display (just numeric part) according to the current locale with rounding.
 188    *
 189    * At this stage this is conceived as an internal function with the currency wrapper
 190    * functions determining the number of places.
 191    *
 192    * This calls the underlying system function but does not handle currency separators.
 193    *
 194    * It's not totally clear when it changes the $amount value but has historical usage.
 195    *
 196    * @param string $amount
 197    * @param int $numberOfPlaces
 198    *
 199    * @return string
 200    */
 201   protected static function formatLocaleNumericRounded($amount, $numberOfPlaces) {
 202     return self::formatLocaleNumeric(round($amount, $numberOfPlaces));
 203   }
 204
 205   /**
 206    * Format money for display (just numeric part) according to the current locale with rounding.
 207    *
 208    * This handles both rounding & replacement of the currency separators for the locale.
 209    *
 210    * @param string $amount
 211    * @param string $currency
 212    *
 213    * @return string
 214    *   Formatted amount.
 215    */
 216   public static function formatLocaleNumericRoundedByCurrency($amount, $currency) {
 217     $amount = self::formatLocaleNumericRounded($amount, self::getCurrencyPrecision($currency));
 218     return self::replaceCurrencySeparators($amount);
 219   }
 220
 221   /**
 222    * Format money for display (just numeric part) according to the current locale with rounding based on the
 223    * default currency for the site.
 224    *
 225    * @param $amount
 226    * @return mixed
 227    */
 228   public static function formatLocaleNumericRoundedForDefaultCurrency($amount) {
 229     return self::formatLocaleNumericRoundedByCurrency($amount, self::getCurrencyPrecision(CRM_Core_Config::singleton()->defaultCurrency));
 230   }
 231
 232   /**
 233    * Replace currency separators.
 234    *
 235    * @param string $amount
 236    *
 237    * @return string
 238    */
 239   protected static function replaceCurrencySeparators($amount) {
 240     $config = CRM_Core_Config::singleton();
 241     $rep = [
 242       ',' => $config->monetaryThousandSeparator,
 243       '.' => $config->monetaryDecimalPoint,
 244     ];
 245     return strtr($amount, $rep);
 246   }
 247
 248   /**
 249    * Format numeric part of currency by the passed in format.
 250    *
 251    * This is envisaged as an internal function, with wrapper functions defining valueFormat
 252    * into easily understood functions / variables and handling separator conversions and
 253    * rounding.
 254    *
 255    * @param string $amount
 256    * @param string $valueFormat
 257    *
 258    * @return string
 259    */
 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);
 268     }
 269     return $amount;
 270   }
 271
 272 }