README

目录

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

概述

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

安装

您可以通过Composer安装此包

composer require ashallendesign/laravel-exchange-rates

此包已开发并测试，以支持以下最低要求

• PHP 7.2
• Laravel 6

用法

方法

支持的货币

$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日-11月27日的'GBP'到'EUR'汇率，这些日期之间的汇率将作为单个缓存项缓存。此缓存项仅在您尝试以完全相同的货币和日期范围获取相同汇率时检索。

因此，如果您尝试获取2019年11月20日-11月26日的'GBP'到'EUR'汇率，将发出新的API请求，因为日期范围不同。

支持的货币

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

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

测试

vendor/bin/phpunit

安全

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

贡献

如果您想对包进行任何修改或改进，请随时提交一个pull request。

在提交pull request之前，请遵循以下指南以贡献此库

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

致谢

• Ash Allen
• Jess Pickup (Logo)
• 所有贡献者

变更日志

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

升级

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

许可

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