xdemonme/laravel-currency

基于exchangerate.host提供的免费API，为Laravel提供当前和历史货币汇率以及加密货币汇率的一个包

维护者

详细信息

github.com/xDemonME/laravel-currency

源代码

资助包维护！
Ko Fi

安装: 83

依赖: 0

建议者: 0

安全: 0

星标: 3

关注者: 0

分支: 44

1.1.0 2023-10-20 11:27 UTC

Requires

Requires (Dev)

MIT f92aff48d5ef267be51a1378752eeb6808f3002b

currencylaravelcurrency converterexchange rates

This package is auto-updated.

Last update: 2024-09-20 13:18:08 UTC

README

Tests Packagist License Packagist Version Packagist Downloads

本包支持exchangerate.host API密钥。

Laravel currency是一个简单的包，用于当前和历史货币汇率以及加密货币汇率，基于exchangerate.host提供的免费API！

注意：此包是Currency库的集成

要求

  • PHP >= 7.2
  • Laravel >= 6.0
  • guzzlehttp >= 6.0

安装

composer require xdemonme/laravel-currency

用法

1. 货币转换

要将一种货币转换为另一种货币，您可以将方法链接起来

use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::convert()
        ->setAccessKey($accessKey)
        ->from('USD')
        ->to('EUR')
        ->get();

这将返回转换后的金额或失败时返回 null。

要转换的金额默认为 1，您可以指定金额

use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::convert()
        ->setAccessKey($accessKey)
        ->from('USD')
        ->to('EUR')
        ->amount(50)
        ->get();

可用方法

  • 使用历史汇率 YYYY-MM-DD 转换货币
use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::convert()
        ->setAccessKey($accessKey)
        ->from('USD')
        ->to('EUR')
        ->date('2019-08-01')
        ->get();
  • 将转换后的金额四舍五入到小数位数
use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::convert()
        ->setAccessKey($accessKey)
        ->from('USD')
        ->to('EUR')
        ->round(2)
        ->get();
  • 您还可以在外汇 default、银行视图或加密货币之间切换数据源
use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::convert()
        ->setAccessKey($accessKey)
        ->from('BTC')
        ->to('ETH')
        ->source('crypto')
        ->get();

2. 实时（最新）汇率

注意：此方法已弃用

要获取最新汇率，您可以链接方法

use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::rates()
        ->setAccessKey($accessKey)
        ->live()
        ->get();

// ['USD' =>  1.215707, ...]

Currency::rates()
        ->setAccessKey($accessKey)
        ->live()
        ->source('crypto')
        ->get();

// ['ETH' => 3398.61, ...]

这将返回所有可用货币的数组或失败时返回 null。

可用方法

  • 就像货币转换一样，您可以使用任何可用的方法
use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::rates()
        ->setAccessKey($accessKey)
        ->live()
        ->symbols(['USD', 'EUR', 'EGP']) //An array of currency codes to limit output currencies
        ->base('GBP') //Changing base currency (default: EUR). Enter the three-letter currency code of your preferred base currency.
        ->amount(5.66) //Specify the amount to be converted
        ->round(2) //Round numbers to decimal places
        ->source('ecb') //Switch data source between forex `default`, bank view or crypto currencies.
        ->get();

3. 历史汇率

历史汇率适用于几乎所有货币，最远可追溯到1999年。

use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::rates()
        ->setAccessKey($accessKey)
        ->historical('2020-01-01') //`YYYY-MM-DD` Required date parameter to get the rates for
        ->get();

// ['USD' =>  1.1185, ...]

Currency::rates()
        ->setAccessKey($accessKey)
        ->historical('2021-03-30')
        ->source('crypto')
        ->get();
        
// ['BTC' =>  2.0E-5, ...]

与最新汇率一样，您可以使用任何可用的方法

use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::rates()
        ->setAccessKey($accessKey)
        ->historical('2020-01-01')
        ->symbols(['USD', 'EUR', 'CZK'])
        ->base('GBP')
        ->amount(5.66)
        ->round(2)
        ->source('ecb')
        ->get();

4. 时间范围（时间序列）汇率

时间范围（时间序列）是您选择的两日期之间的每日历史汇率，最大时间范围为365天。这将返回一个数组或失败时返回 null。

use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::rates()
        ->setAccessKey($accessKey)
        ->timeFrame('2021-05-01', '2021-05-02') //`YYYY-MM-DD` Required dates range parameters
        ->symbols(['USD']) //[optional] An array of currency codes to limit output currencies
        ->base('GBP') //[optional] Changing base currency (default: EUR). Enter the three-letter currency code of your preferred base currency.
        ->amount(5.66) //[optional] Specify the amount to be converted (default: 1)
        ->round(2) //[optional] Round numbers to decimal places
        ->source('ecb') //[optional] Switch data source between forex `default`, bank view or crypto currencies.
        ->get();
        
/**
[
    '2021-05-01' => [
        "USD" => 1.201995
    ],
    '2021-05-02' => [
        "USD" => 1.2027
    ]
]
 */

5. 变动（波动）

检索有关货币每天波动的信息，最大时间范围为365天。这将返回一个数组或失败时返回 null。

use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::rates()
        ->setAccessKey($accessKey)
        ->change('2021-03-29', '2021-04-15') //`YYYY-MM-DD` Required dates range parameters
        ->symbols(['USD']) //[optional] An array of currency codes to limit output currencies
        ->base('GBP') //[optional] Changing base currency (default: EUR). Enter the three-letter currency code of your preferred base currency.
        ->amount(5.66) //[optional] Specify the amount to be converted (default: 1)
        ->round(2) //[optional] Round numbers to decimal places
        ->source('ecb') //[optional] Switch data source between forex `default`, bank view or crypto currencies.
        ->get();
        
/**
 [
    'USD' => [
        "start_rate" => 1.376454, 
        "end_rate"   => 1.37816, 
        "change"     => -0.001706, 
        "change_pct" => -0.001239
        ]
 ]
 */

抛出异常

默认行为是在请求过程中发生错误时返回 null （连接超时、DNS错误、客户端或服务器错误状态代码、缺少API成功参数等）。

如果您想抛出异常，请使用 throw 方法。 throw 方法返回货币实例，允许您链接其他方法

use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::convert()
        ->setAccessKey($accessKey)
        ->from('USD')
        ->to('EUR')
        ->amount(20)
        ->throw()
        ->get();

如果您想在抛出异常之前执行一些额外的逻辑，请将闭包传递给 throw 方法

use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::convert()
        ->setAccessKey($accessKey)
        ->from('USD')
        ->to('EUR')
        ->amount(20)
        ->throw(function ($response, $e) {
            //
        })
        ->get();

其他方法

  • 您可以使用 withoutVerifying 方法指示在发送请求时不验证TLS证书
use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::convert()
        ->setAccessKey($accessKey)
        ->from('USD')
        ->to('EUR')
        ->withoutVerifying()
        ->get();
  • 您可以使用 withOptions 方法指定额外的Guzzle请求选项。 withOptions 方法接受一个键/值对的数组
use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::rates()
        ->setAccessKey($accessKey)
        ->historical('2021-04-30')
        ->withOptions([
            'debug'   => true,
            'timeout' => 3.0
        ])
        ->get();
  • 当方法给定的第一个参数评估为真时，when 方法将执行给定的回调
use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::rates()
        ->setAccessKey($accessKey)
        ->latest()
        ->when(true, function ($rates) {
            // will execute
            $rates->symbols(['USD', 'EUR', 'EGP'])
                  ->base('GBP');
        })
        ->when(false, function ($rates) {
            // won't execute
            $rates->symbols(['HKD']);
        })
        ->get();

测试

Currency使用Laravel facade，这使得它很容易模拟，因此在测试中实际上并没有执行

use AmrShawky\LaravelCurrency\Facade\Currency;

$accessKey = 'YOUR_API_ACCESS_KEY';

Currency::shouldReceive('convert')
        ->once()
        ->andReturn(1.50);


Currency::shouldReceive('rates')
         ->once()
         ->andReturn(['EUR' => 1,'USD' => 1.215707]);

有关银行来源列表的更多信息，请在此处。

支持的所有符号列表请点击这里，以及加密货币列表请点击这里

许可证

MIT许可证（MIT）。更多详细信息请参阅LICENSE