README

跨货币货币比较和兑换工具。 非框架依赖。

💿 composer require viaaurea/currency

📖 捷克/斯洛伐克版说明文档.

使用此包可以在不同货币的值上进行比较算术或聚合，或将一种货币中的货币兑换成另一种货币。

// resolve the service / get an instance
$cs = $container->get(VA\Currency\CurrencyService::class);

// create a money value object (3 equivalent ways)
$cs->create(100, 'USD');
new Money(100, 'USD');
Money::USD(100);

// exchange / conversion
$valueInUsd = Money::USD(100);
$valueInEur = $cs->exchange($valueInUsd, 'EUR');
$valueInEur->amount();

// comparison arithmetic
// < <= > >= == !=
$cs->greaterThan($valueInUsd, $valueInForeignCurrency); // or $cs->gt( ... )

// diff mixed currencies
$diff = $cs->diff($valueInEur, $valueInForeignCurrency);

// aggregate an array of Money objects with unknown or mixed currencies:
// sum, average, max or min value
$money = [ $valueInEur, $valueInUsd, $valueInForeignCurrency, ... ];
$sum = $cs->sum($money);
$max = $cs->max($money);
$min = $cs->min($money);
$avg = $cs->avg($money);

💡
此包旨在作为一个 轻量级工具 来交换、比较和汇总货币值对象。
对于完整的强大解决方案，请考虑使用 Money for PHP。

货币服务

CurrencyService 是用于转换和算术的主要服务类。它的主要依赖项是一个 汇率提供者 的实现。
在比较不同货币的货币对象或在聚合中，必须将货币转换为其中之一。
提供者提供这些转换的汇率，以及使用 CurrencyService::exchange 方法的显式转换。

目前，此包只提供了一种实现 - StaticExchange，但是根据您的需求（数据库、第三方API抓取等），提供自己的实现非常简单。

配置

汇率由定义并传递给 StaticExchange 类，然后由 CurrencyService 使用。您也可以通过实现 ExchangeRateProviderInterface 接口来提供自己的汇率提供者。

这些汇率是以参考/基准/本地货币为基准定义的。

对于 直接 报价的参考货币（USD、CAD、JPY、CZK、...）

$container->register(CurrencyService::class, function(){
    $rates = [
        'EUR' => 0.9,
        'JPY' => 100,
        'AUD' => 1.5,
    ];
    $provider = new StaticExchange('USD', $rates, StaticExchange::RATE_DIRECT);
    return new CurrencyService($provider);
});

对于 间接 报价的参考货币（EUR、GBP、AUD、...）

$container->register(CurrencyService::class, function(){
    $rates = [
        'USD' => 1.1,
        'JPY' => 120,
        'AUD' => 1.6,
    ];
    $provider = new StaticExchange('EUR', $rates, StaticExchange::RATE_INDIRECT);
    return new CurrencyService($provider);
});

💡 您不需要使用服务容器，在这种情况下，只需将实例分配给变量...

可以指定与比率相对应的单位数量。这可以用于与基准货币差异非常高的货币（某些非洲货币、比特币等）。要这样做，请传递一个包含比率和数量的数组

$rates = [
    // rate for Bitcoin may be specified in micro-Bitcoins:
    'XBT' => [0.5, 0.001],
];

用法

请参阅文件开头的示例，并查看 CurrencyService 类的源代码 以获取可用方法的完整列表。

细粒度交换

exchange 方法以及 CurrencyService 的每个比较或聚合方法都接受一个 可变数量的参数，这些参数被传递到对底层汇率提供者的调用。这可以用来实现计算历史货币价值、买卖/中间汇率等。

示例

$cs->exchange(
    $cs->create(100, 'EUR'), 
    'USD', 
    Carbon::parse('last saturday')
);

$cs->diff(
    $cs->create(100, 'EUR'),
    $cs->create(100, 'USD'),
    Carbon::parse('2017-11-23'),
    'buy'
);

要使用此功能，需要实现自定义提供者，示例

class DatabaseRateProvider implements ExchangeRateProviderInterface {

    function getExchangeRate(
        Currency $target, 
        Currency $from, 
        DateTimeInterface $at, 
        string $direction = 'middle'
    ){
        // your logic here
        // return exchange rate at a given point in time and for the specified direction
    }

}

提示：使用 ExchangeHelper 类可以轻松实现自定义提供者。

Nette DI 扩展

包含 Nette 框架的扩展。请参阅 捷克/斯洛伐克版说明文档。

贡献

... 欢迎贡献。