README

A PHP API Wrapper提供对流行货币汇率API的统一编程接口。

不用担心您喜欢的货币转换服务突然关闭或更改计划。轻松切换，无需更改代码。

灵感 💅

我需要一个货币转换API来为我的旅行网站，但找不到一个好的PHP包。来自Rackbeat/php-currency-api包的想法最接近，但遗憾的是它只是一个占位符并且没有实现。

功能 🌈

通过使用驱动程序支持多个不同的API
使用流畅的接口方便快速检索汇率
一致的返回接口，与使用的驱动程序无关
基于返回数据可以进行计算

支持的API 🌐

如果您想看到更多服务被添加，请随时提交问题！

先决条件 📚

PHP 8.x或PHP 7.3+或更高版本（已在7.3和7.4上进行测试）
PHP的依赖管理器composer
一个或多个上述API提供商的账户

安装 🚀

只需使用composer引入包即可！

$ composer require otherguy/php-currency-api

用法 🛠

货币符号助手

Otherguy\Currency\Symbol类为每个支持的货币提供常量。

！注意：您不需要使用Otherguy\Currency\Symbol来指定符号。它仅是一个方便的助手，不需要使用。您可以直接传递字符串如'USD', 'EUR', ...到所有方法。

// 'USD'
$symbol = Otherguy\Currency\Symbol::USD;

使用all()方法检索所有货币符号的数组

// [ 'AED', 'AFN', ... 'ZWL' ]
$symbols = Otherguy\Currency\Symbol::all();

names()方法返回一个包含货币名称的关联数组

// [ 'AED' => 'United Arab Emirates Dirham', 'AFN' => 'Afghan Afghani', ... ]
$symbols = Otherguy\Currency\Symbol::names();

要获取单个货币的名称，请使用name()方法

// 'United States Dollar'
$symbols = Otherguy\Currency\Symbol::name(Otherguy\Currency\Symbol::USD);

初始化API实例

$currency = Otherguy\Currency\DriverFactory::make('fixerio'); // driver identifier from supported drivers.

要获取支持的驱动程序列表，请使用getDrivers()方法

// [ 'mock', 'fixerio', 'currencylayer', ... ]
$drivers = Otherguy\Currency\DriverFactory::getDrivers()

设置访问密钥

大多数API提供商要求您注册并使用颁发的访问密钥来对其API进行认证。您可以如此指定您的访问密钥

$currency->accessKey('your-access-token-goes-here');

设置配置选项

要设置进一步的配置选项，您可以使用config()方法。例如，CurrencyLayer的JSON格式化选项。

$currency->config('format', '1');

设置基准货币

您可以使用from()或source()来设置基准货币。这两个方法相同。

！注意：每个驱动程序都设置了其自己的默认基准货币。FixerIO使用EUR作为基准货币，而CurrencyLayer使用USD。

大多数服务只允许您在付费计划中更改基础货币。如果您的当前计划不允许更改基础货币，驱动程序将抛出 Otherguy\Currency\Exceptions\ApiException。

$currency->source(Otherguy\Currency\Symbol::USD);
$currency->from(Otherguy\Currency\Symbol::USD);

设置返回货币

您可以使用 to() 或 symbols() 来设置返回货币。这两种方法相同。将单个货币或货币符号数组传递给这些方法中的任何一个。

！注意：传递一个空数组以返回此驱动程序支持的所有货币符号。如果您根本不调用该方法，这将是默认值。

$currency->to(Otherguy\Currency\Symbol::BTC);
$currency->symbols([Otherguy\Currency\Symbol::BTC, Otherguy\Currency\Symbol::EUR, Otherguy\Currency\Symbol::USD]);

历史汇率

要检索历史汇率，请使用 historical() 方法。请注意，您需要通过方法参数或使用 date() 方法指定日期。有关更多信息，请参阅流畅接口。

$currency->date('2010-01-01')->historical();
$currency->historical('2018-07-01');

转换金额

使用 convert() 方法在货币之间进行转换。

！注意：大多数API提供商不允许使用免费账户访问此方法。您仍然可以使用最新汇率或历史汇率端点，并在 ConversionResult 对象上执行计算或转换。

$currency->convert(10.00, 'USD', 'THB'); // Convert 10 USD to THB
$currency->convert(122.50, 'NPR', 'EUR', '2019-01-01'); // Convert 122.50 NPR to EUR using the rates from January 1st, 2019

流畅接口

大多数方法都可以与 流畅接口 一起使用，允许您将方法调用链式化以提高代码的可读性。

// Namespaces are omitted for readability!
DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::EUR)->get();
DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::NPR)->date('2013-03-02')->historical();
DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::NPR)->amount(12.10)->convert();

转换结果

get() 和 historical() 端点返回一个 ConversionResult 对象。此对象允许您轻松执行计算和转换。

！注意：尽管大多数提供者的免费账户不允许您更改基础货币，但您仍然可以使用 ConversionResult 对象稍后更改基础货币。但这可能不如直接更改基础货币准确。

！注意：要在两种货币之间进行转换，您需要在初始的 get() 或 historical() 请求中请求这两种货币。您不能在未检索的货币之间进行转换！

以下代码是一些使用 ConversionResult 对象的示例。

$result = DriverFactory::make('driver')->from(Symbol::USD)->to([Symbol::EUR, Symbol::GBP])->get();

// [ 'USD' => 1.00, 'EUR' => 0.89, 'GBP' => 0.79 ]
$result->all();

// 'USD'
$result->getBaseCurrency();

// '2019-06-11'
$result->getDate();

// 0.89
$result->rate(Symbol::EUR);

// CurrencyException("No conversion result for BTC!");
$result->rate(Symbol::BTC);

// 5.618
$result->convert(5.0, Symbol::EUR, Symbol::USD);

// [ 'USD' => 1.13, 'EUR' => 1.00, 'GBP' => 0.89 ]
$result->setBaseCurrency(Symbol::EUR)->all();

// 1.12
$result->setBaseCurrency(Symbol::GBP)->rate(Symbol::EUR);

贡献 🚧

拉取请求非常受欢迎！我正在努力使此存储库的测试覆盖率达到100%，因此请确保为您的代码添加测试。

otherguy / php-currency-api

维护者

详情