ashallendesign/laravel-exchange-rates

一个用于与exchangeratesapi.io API交互的包装包。

维护者

详情

github.com/ash-jc-allen/laravel-exchange-rates

主页

源代码

问题

资助包维护！
ash-jc-allen

安装次数: 307,500

依赖项: 0

建议者: 0

安全性: 0

星标: 430

关注者: 8

分支: 46

公开问题: 0

v7.6.0 2024-09-11 08:25 UTC

Requires

Requires (Dev)

MIT 07872e1742c7a61304aa283c5e5b96706321c267

  • Ash Allen <mail.woop@ashallendesign.co.uk>

exchange-rateashallendesignexchangeratesapi.iolaravel-exchange-rates

This package is auto-updated.

Last update: 2024-09-11 08:58:06 UTC

README

Laravel Exchange Rates

Latest Version on Packagist Total Downloads PHP from Packagist GitHub license

目录

概述

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

安装

您可以通过Composer安装此包

composer require ashallendesign/laravel-exchange-rates

该包已开发和测试，以满足以下最低要求

  • PHP 8.0
  • Laravel 8

支持的API

Laravel Exchange Rates目前支持以下API

配置

发布配置文件

您可以使用以下命令发布包的配置文件

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

如果您使用的是需要API密钥的API，您可以在.env文件中放置它

EXCHANGE_RATES_API_KEY={Your-API-Key-Here}

如果您使用的是https://exchangeratesapi.io或https://exchangerate.host的免费层，您应该在config/laravel-exchange-rates.php中将https配置选项设置为false，因为这些API的免费层不允许HTTPS请求。

用法

方法

支持的货币

要获取API支持的可用货币，您可以使用以下方式使用currencies方法

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

$exchangeRates->currencies();

汇率

获取两种货币之间的汇率

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

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

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

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

// $result: 1.10086

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

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

可以一次获取多个货币的汇率。如果您需要一次性获取多个汇率，而无需进行多次API调用，这尤其有用。

要实现这一点，您可以使用exchangeRate方法，并将货币代码字符串数组作为第二个参数传递。这将返回一个包含浮点数的汇率数组。

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

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

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

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

日期范围内的汇率

获取两种货币之间的汇率

要获取两个货币在指定日期范围内的汇率，可以使用exchangeRateBetweenDateRange方法。在进行此操作时，可以将货币代码作为字符串传递为第二个参数。该方法将返回包含汇率的数组。

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

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

$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'的汇率。

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

$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'。

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

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

// $result: 110.15884906

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

多于两种货币之间的转换

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

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

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

$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'。

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

$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'。

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

$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中使用外观（facades），可以选择使用提供的AshAllenDesign\LaravelExchangeRates\Facades\ExchangeRate外观，而不是手动实例化AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate类。

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

use AshAllenDesign\LaravelExchangeRates\Facades\ExchangeRate;

ExchangeRate::currencies();

驱动程序

Laravel Exchange Rates提供了多个驱动程序，以便您可以与不同的汇率API交互。

您可以通过设置config/laravel-exchange-rates.php配置文件中的driver配置字段来选择默认驱动程序。例如，要使用exchange-rates-api-io驱动程序，您可以设置以下内容

'driver' => 'exchange-rates-api-io',

当运行类似的方法时，将自动使用此驱动程序

// Using the "ExchangeRate" class:
$exchangeRates = app(ExchangeRate::class);
$result = $exchangeRates->exchangeRate('GBP', ['EUR', 'USD']);

// Using the "ExchangeRate" facade:
ExchangeRate::exchangeRate('GBP', ['EUR', 'USD']);

但是，如果您希望使用不同的驱动程序，可以使用driver方法指定要使用的驱动程序。例如，要使用exchange-rates-data-api驱动程序，您可以使用以下方法

// Using the "ExchangeRate" class:
$exchangeRates = app(ExchangeRate::class);

$result = $exchangeRates
    ->driver('exchange-rates-data-api')
    ->exchangeRate('GBP', ['EUR', 'USD']);

// Using the "ExchangeRate" facade:
ExchangeRate::driver('exchange-rates-data-api')
    ->exchangeRate('GBP', ['EUR', 'USD']);

支持的驱动程序

该包提供以下驱动程序

验证规则

Laravel Exchange Rates包含自己的ValidCurrency规则，用于验证货币。这有助于确保至少有一个驱动程序支持货币（可能是用户提供的）。以下示例显示了如何使用此规则验证货币。

use AshAllenDesign\LaravelExchangeRates\Rules\ValidCurrency;
use Illuminate\Support\Facades\Validator;

$formData = [
    'currency' => 'GBP',
];

$rules = [
    'currency' => new ValidCurrency(),
];

$validator = Validator::make($formData, $rules);

此规则不会调用任何API，而是检查一个数组（由包提供），该数组包含至少一个驱动程序支持的货币。这意味着规则将更快，不会引起配额限制问题。然而，可能存在规则会“通过”那些不使用您使用的驱动程序支持的货币的情况。

如果您希望验证更加严格，并且只返回所选驱动程序支持的货币，您可以编写自己的验证规则，通过调用API获取支持的货币列表。

缓存

清除缓存的汇率

默认情况下，所有来自汇率API的响应都会被缓存。这可以显著提高性能并减少服务器带宽的使用。

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

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

$exchangeRates->shouldBustCache()
    ->convert(
        100,
        'GBP',
        'EUR',
        Carbon::now()
);

防止汇率被缓存

还可以防止汇率被完全缓存。要这样做，可以使用shouldCache(false)方法。下面的示例展示了如何获取汇率而不缓存它

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

$exchangeRates->shouldCache(false)
    ->convert(
        100,
        'GBP',
        'EUR',
        Carbon::now()
    );

注意：缓存是通过在从API获取汇率后存储汇率来工作的。例如，如果您要获取2019年11月20日至27日的'GBP'到'EUR'汇率，这些日期之间的汇率将被缓存为一个单独的缓存项。这个缓存项只有在您尝试获取相同的汇率、使用完全相同的货币和日期范围时才会被检索。

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

支持的货币

Laravel汇率支持以下货币（按字母顺序排序）

测试

如果您要向此包贡献新的更改，您可以从包的根目录运行以下命令来运行测试

composer test

安全性

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

贡献

如果您想对包进行任何更改或改进，请随时提出pull request。

在提交pull request之前，请按照以下指南为此库做出贡献

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

致谢

变更日志

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

升级

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

许可证

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

支持我

如果您觉得这个包很有用，请考虑购买Battle Ready Laravel以支持我及其工作。

每一笔销售都对我有很大帮助，并使我能够有更多时间致力于开源项目和教程。

为了表示极大的感谢，您可以使用代码BATTLE20在书中获得20%的折扣。

👉 购买您的副本！

Battle Ready Laravel