wartw89/money

货币和货币库

维护者

详细信息

github.com/wartw/money

来源

资助包维护！
BenMorel

安装: 1

依赖: 1

建议者: 0

安全: 0

星星: 0

关注者: 0

分支: 103

v1 2023-04-22 10:43 UTC

Requires

Requires (Dev)

Suggests

  • ext-intl: Required to format Money objects

MIT 2f876dc4d793f8430710ba56ded0eebdc097debf

moneycurrencybrick

This package is auto-updated.

Last update: 2024-09-22 13:42:01 UTC

README

PHP的货币和货币库。

Build Status Coverage Status Latest Stable Version Total Downloads License

简介

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

这个库基于brick/math，并处理任意大小的货币的精确计算。

安装

可以通过Composer安装此库

composer require brick/money

要求

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

对于PHP 7.4兼容性，可以使用版本0.7。对于PHP 7.1、7.2和7.3，可以使用版本0.5。请注意，这些PHP版本已结束生命周期，不再受支持。如果您仍在使用这些PHP版本之一，您应尽快考虑升级。

尽管不是必需的，但建议您安装GMP或BCMath扩展来加快计算速度。

项目状态和发布流程

虽然此库仍在开发中，但它经过了良好的测试，应该足够稳定，可以在生产环境中使用。

当前版本号格式为0.x.y。当引入非破坏性更改（添加新方法、优化现有代码等）时，将递增y。

当引入破坏性更改时，始终开始新的0.x版本周期。

因此，您可以将项目锁定到给定的发布周期，例如0.8.*。

如果您需要升级到较新的发布周期，请查看发布历史，了解每个后续0.x.0版本引入的更改列表。

创建货币

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

use Brick\Money\Money;

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

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

use Brick\Money\Money;

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

基本操作

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

use Brick\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 Brick\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 Brick\Money\Money;

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

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

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

use Brick\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有两位小数，而JPY为零），以1个次要单位（分）的步长递增；它们在内部使用称为DefaultContext的东西。您可以通过提供Context实例来更改此行为。每个上下文针对特定的用例

现金舍入

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

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

use Brick\Money\Money;
use Brick\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 Brick\Money\Money;
use Brick\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 Brick\Money\Money;
use Brick\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。请查看下一节！

高级计算

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

use Brick\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，如果必要，则应用上下文和舍入模式。大多数情况下，您希望结果与原始货币具有相同的上下文，这就是上面示例所做的那样。但您可以应用任何上下文。

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

注意：如您在上面的示例中看到的，分数中的数字可以迅速变得非常大。这通常不是问题——计算中涉及的数字位数没有硬性限制——但如果需要，您可以在任何时候简化分数，而不会影响实际货币价值。

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

货币分配

您可以将货币轻松分成多个部分。

use Brick\Money\Money;

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

您还可以根据一系列比例来分配货币。例如，您想要将987.65 CHF的利润分配给3个股东，他们分别拥有公司48%、41%和11%的股份。

use Brick\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 Brick\Money\Money;
use Brick\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()都会将余数分摊到列表中的第一个货币上，直到总数加起来等于原始货币。这是Martin Fowler在他的书中提出的算法，该书为企业应用架构模式。您可以在第一个示例中看到这一点，其中第一个货币获得33.34美元，而其他货币获得33.33美元。

货币袋（混合货币）

您可能有时需要将不同货币的货币相加。MoneyBag在此处很有用。

use Brick\Money\Money;
use Brick\Money\MoneyBag;

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

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

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

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

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

货币转换

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

use Brick\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 Brick\Money\ExchangeRateProvider\ConfigurableProvider;

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

PDOProvider

此提供者从数据库表中读取汇率

use Brick\Money\ExchangeRateProvider\PDOProvider;
use Brick\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 Brick\Money\ExchangeRateProvider\ConfigurableProvider;
use Brick\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 Brick\Money\Currency;
use Brick\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();
    }
}

常见问题解答

本项目与 moneyphp/money 有何不同？

请参阅这次讨论。