README

PHP的货币和货币库的分支。

简介

处理财务数据是一件严肃的事情，应用程序中微小的舍入错误可能会导致现实生活中严重的后果。这就是为什么浮点运算不适合货币计算。

这个库基于brick/math，可以处理任何规模的货币的精确计算。

安装

这个库可以通过Composer安装

composer require katzebue/money

要求

此库需要PHP 8.2或更高版本。

为了与PHP 8.1及以下版本兼容，您可以使用原始仓库。

虽然不是必需的，但建议您安装GMP或BCMath扩展来加速计算。

创建货币

要创建货币，调用of()工厂方法

use Katzebue\Money\Money;

$money = Money::of(50, 'USD'); // USD 50.00
$money = Money::of('19.9', 'USD'); // USD 19.90

或者，您可以使用ofMinor()方法从一个“小单位”（分）的数量创建货币

use Katzebue\Money\Money;

$money = Money::ofMinor(1234, 'USD'); // USD 12.34

基本操作

货币是一个不可变类：其值永远不会改变，因此可以安全地传递。因此，对货币的所有操作都返回一个新的实例

use Katzebue\Money\Money;

$money = Money::of(50, 'USD');

echo $money->plus('4.99'); // USD 54.99
echo $money->minus(1); // USD 49.00
echo $money->multipliedBy('1.999'); // USD 99.95
echo $money->dividedBy(4); // USD 12.50

您还可以添加和减去货币实例

use Katzebue\Money\Money;

$cost = Money::of(25, 'USD');
$shipping = Money::of('4.99', 'USD');
$discount = Money::of('2.50', 'USD');

echo $cost->plus($shipping)->minus($discount); // USD 27.49

如果两个货币实例不是同一货币，将抛出异常

use Katzebue\Money\Money;

$a = Money::of(1, 'USD');
$b = Money::of(1, 'EUR');

$a->plus($b); // MoneyMismatchException

如果结果需要舍入，必须作为第二个参数传递舍入模式，否则将抛出异常

use Katzebue\Money\Money;
use Brick\Math\RoundingMode;

$money = Money::of(50, 'USD');

$money->plus('0.999'); // RoundingNecessaryException
$money->plus('0.999', RoundingMode::DOWN); // USD 50.99

$money->minus('0.999'); // RoundingNecessaryException
$money->minus('0.999', RoundingMode::UP); // USD 49.01

$money->multipliedBy('1.2345'); // RoundingNecessaryException
$money->multipliedBy('1.2345', RoundingMode::DOWN); // USD 61.72

$money->dividedBy(3); // RoundingNecessaryException
$money->dividedBy(3, RoundingMode::UP); // USD 16.67

货币上下文

默认情况下，货币具有官方的货币规模，如由ISO 4217标准定义的（例如，EUR和USD有2位小数，而JPY有0位），以1个小单位（分）的增量增加；它们内部使用所谓的DefaultContext。您可以通过提供Context实例来更改这种行为。每个上下文都针对特定的用例

现金舍入

某些货币不允许现金和现金支付有相同的增量。例如，CHF（瑞士法郎）有2位小数，允许0.01 CHF的增量，但瑞士没有面值小于5分或0.05 CHF的硬币。

您可以使用CashContext处理此类货币

use Katzebue\Money\Money;
use Katzebue\Money\Context\CashContext;
use Brick\Math\RoundingMode;

$money = Money::of(10, 'CHF', new CashContext(5)); // CHF 10.00
$money->dividedBy(3, RoundingMode::DOWN); // CHF 3.30
$money->dividedBy(3, RoundingMode::UP); // CHF 3.35

自定义规模

您可以使用自定义规模的货币，通过提供CustomContext

use Katzebue\Money\Money;
use Katzebue\Money\Context\CustomContext;
use Brick\Math\RoundingMode;

$money = Money::of(10, 'USD', new CustomContext(4)); // USD 10.0000
$money->dividedBy(7, RoundingMode::UP); // USD 1.4286

自动规模

如果您需要调整其规模以适应操作结果的货币，那么AutoContext就是您的选择

use Katzebue\Money\Money;
use Katzebue\Money\Context\AutoContext;

$money = Money::of('1.10', 'USD', new AutoContext()); // USD 1.1
$money->multipliedBy('2.5'); // USD 2.75
$money->dividedBy(8); // USD 0.1375

请注意，不建议使用AutoContext来表示中间计算结果：特别是，它不能表示所有除法的结果，因为其中一些可能导致无限循环小数，这将抛出异常。对于这些用例，您需要使用RationalMoney。请继续查看下一部分！

高级计算

您可能偶尔需要对Money进行多个操作链，并且只在最后一步应用舍入模式；如果对每个操作都应用舍入模式，您可能会得到不同的结果。这就是RationalMoney发挥作用的地方。此类内部将金额存储为有理数（分数）。您可以从Money创建RationalMoney，反之亦然。

use Katzebue\Money\Money;
use Brick\Math\RoundingMode;

$money = Money::of('9.5', 'EUR') // EUR 9.50
  ->toRational() // EUR 950/100
  ->dividedBy(3) // EUR 950/300
  ->plus('17.795') // EUR 6288500/300000
  ->multipliedBy('1.196') // EUR 7521046000/300000000
  ->to($money->getContext(), RoundingMode::DOWN) // EUR 25.07

如您所见，中间结果以分数形式表示，且永远不会进行舍入。最后的to()方法将其转换为Money，如果需要，应用上下文和舍入模式。大多数情况下，您希望结果与原始Money的上下文相同，这正是上面示例所做的那样。但您真的可以应用任何上下文。

...
  ->to(new CustomContext(8), RoundingMode::UP); // EUR 25.07015334

注意：如您在上述示例中看到的那样，分数中的数字可能会迅速变得非常大。这通常不是问题——参与计算的数字没有位数上的硬限制——但如有必要，您可以在任何时间简化分数，而不会影响实际货币价值。

...
  ->multipliedBy('1.196') // EUR 7521046000/300000000
  ->simplified() // EUR 3760523/150000

货币分配

您可以将Money轻松分成几个部分。

use Katzebue\Money\Money;

$money = Money::of(100, 'USD');
[$a, $b, $c] = $money->split(3); // USD 33.34, USD 33.33, USD 33.33

您还可以根据一系列比例分配Money。比如说，您想要将987.65瑞士法郎的利润分配给3位股东，他们分别持有公司48%、41%和11%的股份。

use Katzebue\Money\Money;

$profit = Money::of('987.65', 'CHF');
[$a, $b, $c] = $profit->allocate(48, 41, 11); // CHF 474.08, CHF 404.93, CHF 108.64

这也很好地与现金舍入模式配合。

use Katzebue\Money\Money;
use Katzebue\Money\Context\CashContext;

$profit = Money::of('987.65', 'CHF', new CashContext(5));
[$a, $b, $c] = $profit->allocate(48, 41, 11); // CHF 474.10, CHF 404.95, CHF 108.60

请注意，比例可以是任何（非负）整数值，而且不需要加起来等于100。

当分配产生余数时，split()和allocate()都会将余数分配到列表中的第一个货币，直到总额加起来等于原始Money。这是马丁·福勒在其书籍《企业应用架构模式》中提出的算法。您可以在第一个示例中看到这一点，其中第一个货币得到33.34美元，而其他货币得到33.33美元。

钱袋（混合货币）

有时您可能需要将不同货币的Money加在一起。MoneyBag对此很有用。

use Katzebue\Money\Money;
use Katzebue\Money\MoneyBag;

$eur = Money::of('12.34', 'EUR');
$jpy = Money::of(123, 'JPY');

$moneyBag = new MoneyBag();
$moneyBag->add($eur);
$moneyBag->add($jpy);

您可以将任何类型的Money添加到MoneyBag中：一个Money，一个RationalMoney，甚至是另一个MoneyBag。

请注意，与其他类不同，MoneyBag是可变的：当您调用add()或subtract()时，其值会改变。

MoneyBag能做什么？嗯，您可以使用CurrencyConverter将其转换为任何货币的Money。继续阅读！

货币转换

此库附带一个CurrencyConverter，可以将任何类型的Money（Money、RationalMoney或MoneyBag）转换为另一种货币的Money。

use Katzebue\Money\CurrencyConverter;

$exchangeRateProvider = ...;
$converter = new CurrencyConverter($exchangeRateProvider); // optionally provide a Context here

$money = Money::of('50', 'USD');
$converter->convert($money, 'EUR', null, RoundingMode::DOWN);

转换器执行尽可能精确的计算，在最后一步之前，内部将结果表示为有理数。

要使用货币转换器，您需要一个ExchangeRateProvider。提供了几种实现，其中

ConfigurableProvider

此提供程序从空白状态开始，并允许您手动添加汇率。

use Katzebue\Money\ExchangeRateProvider\ConfigurableProvider;

$provider = new ConfigurableProvider();
$provider->setExchangeRate('EUR', 'USD', '1.0987');
$provider->setExchangeRate('USD', 'EUR', '0.9123');

PDOProvider

此提供程序从数据库表读取汇率。

use Katzebue\Money\ExchangeRateProvider\PDOProvider;
use Katzebue\Money\ExchangeRateProvider\PDOProviderConfiguration;

$pdo = new \PDO(...);

$configuration = new PDOProviderConfiguration(
    tableName: 'exchange_rates',
    exchangeRateColumnName: 'exchange_rate',
    sourceCurrencyColumnName: 'source_currency_code',
    targetCurrencyColumnName: 'target_currency_code',
);

$provider = new PDOProvider($pdo, $configuration);

PDOProvider还支持固定源或目标货币，以及动态WHERE条件。有关更多信息，请参阅PDOProviderConfiguration类。

BaseCurrencyProvider

此提供程序基于另一个汇率提供程序，对于所有可用的汇率都相对于单一货币的情况非常常见。例如，欧洲中央银行提供的汇率都相对于EUR。您可以直接使用它们将EUR转换为USD，但不能将USD转换为EUR，更不用说USD转换为GBP了。

此提供商将合并汇率以获得预期结果

use Katzebue\Money\ExchangeRateProvider\ConfigurableProvider;
use Katzebue\Money\ExchangeRateProvider\BaseCurrencyProvider;

$provider = new ConfigurableProvider();
$provider->setExchangeRate('EUR', 'USD', '1.1');
$provider->setExchangeRate('EUR', 'GBP', '0.9');

$provider = new BaseCurrencyProvider($provider, 'EUR');
$provider->getExchangeRate('EUR', 'USD'); // 1.1
$provider->getExchangeRate('USD', 'EUR'); // 10/11
$provider->getExchangeRate('GBP', 'USD'); // 11/9

注意，汇率提供商可以返回有理数！

编写自己的提供商

编写自己的提供商很简单：ExchangeRateProvider 接口只有一个方法，即 getExchangeRate()，该方法接受货币代码并返回一个数字。

自定义货币

Money 默认支持 ISO 4217 货币。您还可以通过创建 Currency 实例来使用自定义货币。让我们创建一个比特币货币

use Katzebue\Money\Currency;
use Katzebue\Money\Money;

$bitcoin = new Currency(
    'XBT',     // currency code
    0,         // numeric currency code, useful when storing monies in a database; set to 0 if unused
    'Bitcoin', // currency name
    8          // default scale
);

现在您可以使用这个货币代替货币代码

$money = Money::of('0.123', $bitcoin); // XBT 0.12300000

格式化

格式化需要 intl 扩展。

Money 对象可以根据给定的区域设置进行格式化

$money = Money::of(5000, 'USD');
echo $money->formatTo('en_US'); // $5,000.00
echo $money->formatTo('fr_FR'); // 5 000,00 $US

或者，您可以使用自己的 NumberFormatter 实例来格式化 Money 对象，这为您提供了定制的空间

$formatter = new \NumberFormatter('en_US', \NumberFormatter::CURRENCY);
$formatter->setSymbol(\NumberFormatter::CURRENCY_SYMBOL, 'US$');
$formatter->setSymbol(\NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL, '·');
$formatter->setAttribute(\NumberFormatter::MIN_FRACTION_DIGITS, 2);

$money = Money::of(5000, 'USD');
echo $money->formatWith($formatter); // US$5·000.00

重要提示：因为格式化是通过 NumberFormatter 执行的，所以金额在过程中转换为浮点数；因此在格式化非常大的货币值时可能会出现差异。

在数据库中存储货币

持久化金额

• 作为整数：在许多应用程序中，货币仅使用其默认刻度（例如，对于 USD，2 位小数，对于 JPY，0 位小数）。在这种情况下，最佳实践是将小单位（分）存储为整数字段

  $integerAmount = $money->getMinorAmount()->toInt();

  然后检索它

  Money::ofMinor($integerAmount, $currencyCode);

  这种方法对所有货币都适用，无需担心刻度。您只需担心整数溢出（这将抛出异常），但这种情况很少发生，除非您正在处理大量的金钱。

• 作为小数：对于大多数其他情况，建议将金额字符串作为小数类型存储

  $decimalAmount = (string) $money->getAmount();

  然后检索它

  Money::of($decimalAmount, $currencyCode);

持久化货币

• 作为字符串：如果您仅处理 ISO 货币，或具有 3 个字母货币代码的自定义货币，则可以将货币存储为 CHAR(3)。否则，您很可能需要一个 VARCHAR。如果您的应用程序使用固定货币列表，您还可以使用 ENUM。

  $currencyCode = $money->getCurrency()->getCurrencyCode();

  当检索货币时：您可以直接在 Money::of() 和 Money::ofMinor() 中使用 ISO 货币代码。对于自定义货币，您需要先将它们转换为 Currency 实例。

• 作为整数：如果您仅处理 ISO 货币，或具有数值代码的自定义货币，您可以将货币代码存储为整数

  $numericCode = $money->getCurrency()->getNumericCode();

  当检索货币时：您可以直接在 Money::of() 和 Money::ofMinor() 中使用 ISO 货币的数值代码。对于自定义货币，您需要先将它们转换为 Currency 实例。

• 硬编码：如果您的应用程序仅处理一种货币，您完全可以硬编码货币代码而不将其存储在数据库中。

使用 ORM

如果您正在使用 Doctrine 等ORM，建议单独存储金额和货币，并在getter/setter中执行转换

class Entity
{
    private int $price;
    private string $currencyCode;

    public function getPrice() : Money
    {
        return Money::ofMinor($this->price, $this->currencyCode);
    }

    public function setPrice(Money $price) : void
    {
        $this->price = $price->getMinorAmount()->toInt();
        $this->currencyCode = $price->getCurrency()->getCurrencyCode();
    }
}