CRM/Utils/Money.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  *
  30  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2019
  32  */
  33
  34 /**
  35  * Money utilties
  36  */
  37 class CRM_Utils_Money {
  38   static $_currencySymbols = NULL;
  39
  40   /**
  41    * Format a monetary string.
  42    *
  43    * Format a monetary string basing on the amount provided,
  44    * ISO currency code provided and a format string consisting of:
  45    *
  46    * %a - the formatted amount
  47    * %C - the currency ISO code (e.g., 'USD') if provided
  48    * %c - the currency symbol (e.g., '$') if available
  49    *
  50    * @param float $amount
  51    *   The monetary amount to display (1234.56).
  52    * @param string $currency
  53    *   The three-letter ISO currency code ('USD').
  54    * @param string $format
  55    *   The desired currency format.
  56    * @param bool $onlyNumber
  57    * @param string $valueFormat
  58    *   The desired monetary value display format (e.g. '%!i').
  59    *
  60    * @return string
  61    *   formatted monetary string
  62    *
  63    */
  64   public static function format($amount, $currency = NULL, $format = NULL, $onlyNumber = FALSE, $valueFormat = NULL) {
  65
  66     if (CRM_Utils_System::isNull($amount)) {
  67       return '';
  68     }
  69
  70     $config = CRM_Core_Config::singleton();
  71
  72     if (!$format) {
  73       $format = $config->moneyformat;
  74     }
  75
  76     if (!$valueFormat) {
  77       $valueFormat = $config->moneyvalueformat;
  78     }
  79
  80     if ($onlyNumber) {
  81       // money_format() exists only in certain PHP install (CRM-650)
  82       if (is_numeric($amount) and function_exists('money_format')) {
  83         $amount = money_format($valueFormat, $amount);
  84       }
  85       return $amount;
  86     }
  87
  88     if (!self::$_currencySymbols) {
  89       self::$_currencySymbols = CRM_Core_PseudoConstant::get('CRM_Contribute_DAO_Contribution', 'currency', [
  90           'keyColumn' => 'name',
  91           'labelColumn' => 'symbol',
  92         ]);
  93     }
  94
  95     if (!$currency) {
  96       $currency = $config->defaultCurrency;
  97     }
  98
  99     // ensure $currency is a valid currency code
 100     // for backwards-compatibility, also accept one space instead of a currency
 101     if ($currency != ' ' && !array_key_exists($currency, self::$_currencySymbols)) {
 102       throw new CRM_Core_Exception("Invalid currency \"{$currency}\"");
 103     }
 104
 105     $amount = self::formatNumericByFormat($amount, $valueFormat);
 106     // If it contains tags, means that HTML was passed and the
 107     // amount is already converted properly,
 108     // so don't mess with it again.
 109     // @todo deprecate handling for the html tags because .... WTF
 110     if (strpos($amount, '<') === FALSE) {
 111       $amount = self::replaceCurrencySeparators($amount);
 112     }
 113
 114     $replacements = [
 115       '%a' => $amount,
 116       '%C' => $currency,
 117       '%c' => CRM_Utils_Array::value($currency, self::$_currencySymbols, $currency),
 118     ];
 119     return strtr($format, $replacements);
 120   }
 121
 122   /**
 123    * This is a placeholder function for calculating the number of decimal places for a currency.
 124    *
 125    * Currently code assumes 2 decimal places but some currencies (bitcoin, middle eastern) have
 126    * more. By using this function we can signpost the locations where the number of decimal places is
 127    * currency specific for future enhancement.
 128    *
 129    * @param string $currency
 130    *
 131    * @return int
 132    *   Number of decimal places.
 133    */
 134   public static function getCurrencyPrecision($currency = NULL) {
 135     return 2;
 136   }
 137
 138   /**
 139    * Subtract currencies using integers instead of floats, to preserve precision
 140    *
 141    * @return float
 142    *   Result of subtracting $rightOp from $leftOp to the precision of $currency
 143    */
 144   public static function subtractCurrencies($leftOp, $rightOp, $currency) {
 145     if (is_numeric($leftOp) && is_numeric($rightOp)) {
 146       $precision = pow(10, self::getCurrencyPrecision($currency));
 147       return (($leftOp * $precision) - ($rightOp * $precision)) / $precision;
 148     }
 149   }
 150
 151   /**
 152    * Tests if two currency values are equal, taking into account the currency's
 153    * precision, so that if the difference between the two values is less than
 154    * one more order of magnitude for the precision, then the values are
 155    * considered as equal. So, if the currency has  precision of 2 decimal
 156    * points, a difference of more than 0.001 will cause the values to be
 157    * considered as different. Anything less than 0.001 will be considered as
 158    * equal.
 159    *
 160    * Eg.
 161    *
 162    * 1.2312 == 1.2319 with a currency precision of 2 decimal points
 163    * 1.2310 != 1.2320 with a currency precision of 2 decimal points
 164    * 1.3000 != 1.2000 with a currency precision of 2 decimal points
 165    *
 166    * @param $value1
 167    * @param $value2
 168    * @param $currency
 169    *
 170    * @return bool
 171    */
 172   public static function equals($value1, $value2, $currency) {
 173     $precision = 1 / pow(10, self::getCurrencyPrecision($currency) + 1);
 174     $difference = self::subtractCurrencies($value1, $value2, $currency);
 175
 176     if (abs($difference) > $precision) {
 177       return FALSE;
 178     }
 179
 180     return TRUE;
 181   }
 182
 183   /**
 184    * Format money for display (just numeric part) according to the current locale.
 185    *
 186    * This calls the underlying system function but does not handle currency separators.
 187    *
 188    * It's not totally clear when it changes the $amount value but has historical usage.
 189    *
 190    * @param $amount
 191    *
 192    * @return string
 193    */
 194   protected static function formatLocaleNumeric($amount) {
 195     return self::formatNumericByFormat($amount, CRM_Core_Config::singleton()->moneyvalueformat);
 196   }
 197
 198   /**
 199    * Format money for display (just numeric part) according to the current locale with rounding.
 200    *
 201    * At this stage this is conceived as an internal function with the currency wrapper
 202    * functions determining the number of places.
 203    *
 204    * This calls the underlying system function but does not handle currency separators.
 205    *
 206    * It's not totally clear when it changes the $amount value but has historical usage.
 207    *
 208    * @param string $amount
 209    * @param int $numberOfPlaces
 210    *
 211    * @return string
 212    */
 213   protected static function formatLocaleNumericRounded($amount, $numberOfPlaces) {
 214     return self::formatLocaleNumeric(round($amount, $numberOfPlaces));
 215   }
 216
 217   /**
 218    * Format money for display (just numeric part) according to the current locale with rounding.
 219    *
 220    * This handles both rounding & replacement of the currency separators for the locale.
 221    *
 222    * @param string $amount
 223    * @param string $currency
 224    *
 225    * @return string
 226    *   Formatted amount.
 227    */
 228   public static function formatLocaleNumericRoundedByCurrency($amount, $currency) {
 229     $amount = self::formatLocaleNumericRounded($amount, self::getCurrencyPrecision($currency));
 230     return self::replaceCurrencySeparators($amount);
 231   }
 232
 233   /**
 234    * Format money for display (just numeric part) according to the current locale with rounding based on the
 235    * default currency for the site.
 236    *
 237    * @param $amount
 238    * @return mixed
 239    */
 240   public static function formatLocaleNumericRoundedForDefaultCurrency($amount) {
 241     return self::formatLocaleNumericRoundedByCurrency($amount, self::getCurrencyPrecision(CRM_Core_Config::singleton()->defaultCurrency));
 242   }
 243
 244   /**
 245    * Replace currency separators.
 246    *
 247    * @param string $amount
 248    *
 249    * @return string
 250    */
 251   protected static function replaceCurrencySeparators($amount) {
 252     $config = CRM_Core_Config::singleton();
 253     $rep = [
 254       ',' => $config->monetaryThousandSeparator,
 255       '.' => $config->monetaryDecimalPoint,
 256     ];
 257     return strtr($amount, $rep);
 258   }
 259
 260   /**
 261    * Format numeric part of currency by the passed in format.
 262    *
 263    * This is envisaged as an internal function, with wrapper functions defining valueFormat
 264    * into easily understood functions / variables and handling separator conversions and
 265    * rounding.
 266    *
 267    * @param string $amount
 268    * @param string $valueFormat
 269    *
 270    * @return string
 271    */
 272   protected static function formatNumericByFormat($amount, $valueFormat) {
 273     // money_format() exists only in certain PHP install (CRM-650)
 274     // setlocale() affects native gettext (CRM-11054, CRM-9976)
 275     if (is_numeric($amount) && function_exists('money_format')) {
 276       $lc = setlocale(LC_MONETARY, 0);
 277       setlocale(LC_MONETARY, 'en_US.utf8', 'en_US', 'en_US.utf8', 'en_US', 'C');
 278       $amount = money_format($valueFormat, $amount);
 279       setlocale(LC_MONETARY, $lc);
 280     }
 281     return $amount;
 282   }
 283
 284 }