README

目录

• 概述
• 安装
• 获取API密钥
• 配置
• 用法
  • 方法
    • 支持的货币
    • 汇率
      • 获取两种货币之间的汇率
      • 获取多于两种货币之间的汇率
    • 日期范围内的汇率
      • 获取两种货币之间的汇率
      • 获取多于两种货币之间的汇率
    • 货币转换
      • 两种货币之间的转换
      • 多于两种货币之间的转换
    • 日期范围内的货币转换
      • 日期范围内两种货币之间的转换
      • 日期范围内多于两种货币之间的转换
  • 门面
  • 验证规则
  • 示例
  • 缓存
    • 清除缓存的汇率
    • 防止汇率被缓存
  • 支持的货币
• 测试
• 安全
• 贡献
• 鸣谢
• 变更日志
• 升级
• 许可证

概述

一个用于与exchangeratesapi.io API交互的简单Laravel包。'Laravel Exchange Rates' 允许您获取最新或历史汇率，并在不同货币之间转换货币价值。

安装

您可以通过Composer安装此包

composer require ashallendesign/laravel-exchange-rates

此包已开发并测试，以符合以下最低要求

• PHP 7.2
• Laravel 6

获取API密钥

截至2021年4月1日，exchangeratesapi.io现在使用此服务需要API密钥。要获取API密钥，请访问https://exchangeratesapi.io/pricing。您可以免费注册或使用付费层。

请注意，在撰写本文时，您至少需要'基本'计划才能通过HTTPS进行请求。您还需要至少'专业'计划才能使用此包提供的 convertBetweenDateRange() 和 exchangeRateBetweenDateRange()。

由于免费计划不允许在转换时设置基础货币，因此您还需要至少'基本'付费计划才能使用此包提供的 exchangeRate() 和 convert() 方法。

配置

发布配置和迁移

您可以使用以下命令发布包的配置文件和数据库迁移（以便您可以更改它们）

php artisan vendor:publish --provider="AshAllenDesign\LaravelExchangeRates\Providers\ExchangeRatesProvider"

在您的 .env 中添加必要的配置键

EXCHANGE_RATES_API_URL=https://api.exchangeratesapi.io/v1/
EXCHANGE_RATES_API_KEY={Your-API-Key-Here}

用法

方法

支持的货币

$exchangeRates = new ExchangeRate();
$exchangeRates->currencies();

汇率

获取两种货币之间的汇率

要获取一种货币与另一种货币的汇率，您可以使用 ->exchangeRate() 方法。在这种情况下，您可以将货币代码作为字符串作为第二个参数传递。然后，->exchangeRates() 方法将返回包含汇率的字符串。

以下示例展示了如何获取今天的'GBP'到'EUR'的汇率。

$exchangeRates = new ExchangeRate();
$result = $exchangeRates->exchangeRate('GBP', 'EUR');

// $result: '1.10086'

注意：如果传递了Carbon日期作为第三个参数，将返回该天的汇率（如果有效）。如果没有传递日期，则将使用今天的汇率。

获取多于两种货币之间的汇率

您可以在一次调用中获取多种货币的汇率。如果您需要一次获取许多汇率，并且不想进行多次API调用，这特别有用。

要完成此操作，您可以使用->exchangeRate()方法，并将货币代码字符串数组作为第二个参数传递。这将返回包含汇率的字符串数组。

以下示例展示了如何获取今天从'GBP'到'EUR'和'USD'的汇率。

$exchangeRates = new ExchangeRate();
$result = $exchangeRates->exchangeRate('GBP', ['EUR', 'USD']);

// $result: [
//     'EUR' => '1.10086',
//     'USD' => '1.25622'
// ];

日期范围内的汇率

获取两种货币之间的汇率

要获取给定日期范围内的两种货币之间的汇率，您可以使用->exchangeRateBetweenDateRange()方法。执行此操作时，您可以将货币代码作为字符串作为第二个参数传递。然后，该方法将返回包含汇率的数组。

以下示例展示了如何获取过去3天从'GBP'到'EUR'的汇率。

$exchangeRates = new ExchangeRate();
$result = $exchangeRates->exchangeRateBetweenDateRange('GBP', 'EUR', Carbon::now()->subWeek(), Carbon::now());

// $result: [
//     '2020-07-07' => 1.1092623405
//     '2020-07-08' => 1.1120625424
//     '2020-07-09' => 1.1153867604
// ];

获取多于两种货币之间的汇率

要在一项调用中获取多种货币的汇率，您可以将货币代码字符串数组作为第二个参数传递给->exchangeRateBetweenDateRange()方法。

以下示例展示了如何获取过去3天从'GBP'到'EUR'和'USD'的汇率。

$exchangeRates = new ExchangeRate();
$result = $exchangeRates->exchangeRateBetweenDateRange('GBP', ['EUR', 'USD'], Carbon::now()->subDays(3), Carbon::now());

// $result: [
//     '2020-07-07' => [
//         'EUR' => 1.1092623405,
//         'USD' => 1.2523571825,
//      ],
//     '2020-07-08' => [
//         'EUR' => 1.1120625424,
//         'USD' => 1.2550737853,
//      ],
//     '2020-07-09' => [
//         'EUR' => 1.1153867604,
//         'USD' => 1.2650716636,
//      ],
// ];

货币转换

当传递要转换的货币价值（第一个参数）时，您必须以该货币的最小面额传递它。例如，1英镑'GBP'将作为100（因为1英镑=100便士）传递。

两种货币之间的转换

与获取一种货币到另一种货币的汇率类似，您还可以将货币价值从一种货币转换成另一种货币。为此，您可以使用->convert()方法。

以下示例展示了如何以今天的汇率将1英镑'GBP'转换为'EUR'。

$exchangeRates = new ExchangeRate();
$result = $exchangeRates->convert(100, 'GBP', 'EUR', Carbon::now());

// $result: 110.15884906

注意：如果传递了Carbon日期作为第三个参数，将返回该天的汇率（如果有效）。如果没有传递日期，则将使用今天的汇率。

多于两种货币之间的转换

您还可以使用->convert()方法将货币价值从一种货币转换成多种货币。为此，您可以将货币代码字符串数组作为第三个参数传递。

以下示例展示了如何以今天的汇率将1英镑'GBP'转换为'EUR'和'USD'。

$exchangeRates = new ExchangeRate();
$result = $exchangeRates->convert(100, 'GBP', ['EUR', 'USD'], Carbon::now());

// $result: [
//     'EUR' => 110.15884906,
//     'USD' => 125.30569081
// ];

日期范围内的货币转换

当传递要转换的货币价值（第一个参数）时，您必须以该货币的最小面额传递它。例如，1英镑'GBP'将作为100（因为1英镑=100便士）传递。

日期范围内两种货币之间的转换

与获取日期范围内的汇率类似，您还可以使用汇率将货币价值从一种货币转换成另一种货币。为此，您可以使用->convertBetweenDateRange()方法。

以下示例展示了如何使用过去3天的汇率将1英镑'GBP'转换为'EUR'。

$exchangeRates = new ExchangeRate();
$exchangeRates->convertBetweenDateRange(100, 'GBP', 'EUR', Carbon::now()->subDays(3), Carbon::now());

// $result: [
//     '2020-07-07' => 110.92623405,
//     '2020-07-08' => 111.20625424,
//     '2020-07-09' => 111.53867604,
// ];

日期范围内多于两种货币之间的转换

您还可以使用->convertBetweenDateRange()方法使用日期范围内的汇率将货币价值从一种货币转换成多种货币。为此，您可以将货币代码字符串数组作为第三个参数传递。

以下示例展示了如何使用过去三天的汇率将1英镑'GBP'转换为'EUR'和'USD'。

$exchangeRates = new ExchangeRate();
$result = $exchangeRates->exchangeRateBetweenDateRange('GBP', ['EUR', 'USD'], Carbon::now()->subDays(3), Carbon::now());

// $result: [
//     '2020-07-07' => [
//         'EUR' => 110.92623405,
//         'USD' => 125.23571825,
//      ],
//     '2020-07-08' => [
//         'EUR' => 111.20625424,
//         'USD' => 125.50737853,
//      ],
//     '2020-07-09' => [
//         'EUR' => 111.53867604,
//         'USD' => 126.50716636,
//      ],
// ];

门面

如果您更喜欢使用Laravel中的外观，您可以选择使用提供的ExchangeRate外观而不是手动实例化AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate类。

以下示例展示了如何使用外观获取可用货币。

<?php
    
    namespace App\Http\Controllers;
    
    use ExchangeRate;
    
    class TestController extends Controller
    {
        public function index()
        {
            return ExchangeRate::currencies();
        }
    }

验证规则

Laravel Exchange Rates自带了用于验证货币的ValidCurrency规则。如果您需要确保（可能是用户提供的）货币受到库的支持，这可能很有用。以下示例展示了如何使用该规则验证货币。

<?php
    
    namespace App\Http\Controllers;
    
    use AshAllenDesign\LaravelExchangeRates\Rules\ValidCurrency;
    use Illuminate\Support\Facades\Validator;

    class TestController extends Controller
    {
        public function index()
        {
            $formData = [
                'currency' => 'GBP',
            ];
    
            $rules = [
                'currency' => new ValidCurrency,
            ];
    
            $validator = Validator::make($formData, $rules);
        }
    }

示例

此示例展示了如何将100便士（1英镑）从英镑转换为欧元。将使用当前汇率（除非存在该日期的缓存汇率）。

<?php
    
    namespace App\Http\Controllers;
    
    use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;
    
    class TestController extends Controller
    {
        public function index()
        {
            $exchangeRates = new ExchangeRate();
            return $exchangeRates->convert(100, 'GBP', 'EUR', Carbon::now());
        }
    }

缓存

清除缓存的汇率

默认情况下，所有对exchangeratesapi.io API的请求都会被缓存。这允许显著提高性能并减少来自服务器的带宽。

但是，如果出于任何原因您需要API的新结果而不是缓存结果，则可以使用->shouldBustCache()方法。以下示例展示了如何忽略（如果存在）缓存值并发出新的API请求。

<?php
    
    namespace App\Http\Controllers;
    
    use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;
    
    class TestController extends Controller
    {
        public function index()
        {
            $exchangeRates = new ExchangeRate();
            return $exchangeRates->shouldBustCache()->convert(100, 'GBP', 'EUR', Carbon::now());
        }
    }

防止汇率被缓存

还可以防止汇率被完全缓存。为此，您可以使用->shouldCache(false)方法。以下示例展示了如何获取汇率而不进行缓存

<?php
    
    namespace App\Http\Controllers;
    
    use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;
    
    class TestController extends Controller
    {
        public function index()
        {
            $exchangeRates = new ExchangeRate();
            return $exchangeRates->shouldCache(false)->convert(100, 'GBP', 'EUR', Carbon::now());
        }
    }

注意：缓存是通过在从API获取汇率后存储汇率来实现的。例如，如果您要获取2019年11月20日至2019年11月27日的“GBP”到“EUR”汇率，这些日期之间的汇率将作为一个缓存项进行缓存。只有在您尝试以相同的货币和日期范围获取相同的汇率时，才会检索此缓存项。

因此，如果您尝试获取2019年11月20日至2019年11月26日的“GBP”到“EUR”汇率，由于日期范围不同，将发起一个新的API请求。

支持的货币

Laravel Exchange Rates支持以下货币（按字母顺序排序）

注意：请注意，货币可用是因为它们在exchangeratesapi.io API中被公开。

测试

vendor/bin/phpunit

安全

如果您发现任何与安全相关的问题，请直接通过mail@ashallendesign.co.uk与我联系以报告。

贡献

如果您想对包进行任何更改或改进，请随意发起拉取请求。

在提交您的拉取请求之前，请使用以下指南为该库做出贡献

• 为任何新添加的功能编写测试。如果您正在更新现有代码，请确保现有测试通过，并在需要时编写更多测试。
• 遵循PSR-2编码标准。
• 将所有拉取请求提交到master分支。

鸣谢

• Ash Allen
• Zak
• Jess Pickup（标志）
• 所有贡献者

变更日志

查看变更日志以获取有关最新更改的更多信息。

升级

查看升级指南以获取有关如何将此库更新到新版本的更多信息。

许可证

MIT许可（MIT）。请参阅许可文件以获取更多信息。