README

A PHP库，用于与各种货币汇率API交互。它提供了一个简单的工厂接口，用于构建所选服务的包装器，该包装器公开一个简单的统一API，用于查询货币汇率。

Currency Rates最初是一个Laravel包，但您几乎可以在任何类型的PHP项目中使用它。

服务

目前可用

我们正在努力添加其他服务的驱动程序。我们的API易于扩展，因此您可以添加自己的驱动程序（请参阅下面的说明）。当您这样做时，请随时联系我们并发送您的实现，以便我们可以将其集成到官方包中。

安装

要开始使用，请通过以下命令将包添加到您的项目中

composer require flamix/currency-rates

入门指南

Laravel

Currency Rates包含一个服务提供者，它方便地将组件注册到Laravel的服务容器中，并公开了一个用于全局访问的门面。因此，无需进一步设置。

Symfony

您需要配置您的服务容器，以便在需要时加载Currency Rates。为此，只需将以下内容附加到您的services.yml配置文件

    currency_rates:
        class: Ultraleet\CurrencyRates\CurrencyRates
        public: true    # Symfony 3.3+

最后一行是可选的，仅当您希望直接从服务容器中获取服务时（例如，在您的控制器中使用$this->get('currency_rates')）才需要。然而，建议您使用依赖注入。

现在您可以将它注入到您的服务构造函数或控制器操作中

use Ultraleet\CurrencyRates\CurrencyRates;

class YourService
{
    private $currencyRates;

    public function __construct(CurrencyRates $currencyRates)
    {
        $this->currencyRates = $currencyRates;
    }
}

其他

大多数现代框架都是使用控制反转原则设计的，并实现了一些类型的服务容器，可以用来定位服务或注入依赖。因此，您应该将Currency Rates注册到该服务容器中。具体细节取决于框架；如果您不知道如何操作，请在文档中查找。您可以参考上面的Symfony说明以获取一般指南。

如果您没有使用框架，仍然建议将这些原则应用到您的项目中。但是，如果这对您的简单项目来说太过分了，或者您出于某些原因不想/不能这样做，您可以直接构造CurrencyRates，在需要时使用它。

use Ultraleet\CurrencyRates\CurrencyRates;

$currencyRates = new CurrencyRates;

用法

在初始版本中，Currency Rates API为每个服务驱动程序公开了两种方法。一种是用于查询最新的汇率，另一种是用于检索历史数据。然而，在1.1.0版本中，我们引入了一个流畅的接口，用于与API交互，自1.2.0版本以来，原始方法已被弃用。如果您仍在使用这些方法，请考虑更新您的代码以使用以下所示的流畅接口。原始方法将在Currency Rates 2.0中删除。

注意，以下代码示例假设您以某种方式实例化了服务对象（例如，通过依赖注入或从服务容器中获取）并将其存储在名为$currencyRates的变量中。如果您正在使用Laravel，您可以直接用CurrencyRates::...替换$currencyRates->...以使用门面。

配置

某些驱动程序需要配置才能连接到API，例如应用ID或API密钥。要提供配置，您只需在实例化驱动程序后立即调用configure()方法即可。

$config = config('services.foo'); // Laravel example for fetching the config array
$result = $currencyRates->driver('foo')->configure($config)->...

请注意，您只需在每次请求周期中为驱动程序提供一次配置。后续的API调用将记住配置。

最新/当前汇率

要从fixer.io API获取默认基础货币（EUR）的最新汇率，您只需这样做：

$result = $currencyRates->driver('fixer')->get();

获取不同基础货币的汇率

$result = $currencyRates->driver('fixer')->base('USD')->get();

这些调用返回服务驱动程序提供的所有货币的汇率。您可以可选地指定目标货币。

$result = $currencyRates->driver('fixer')->target(['USD', 'GBP'])->get();
$result = $currencyRates->driver('fixer')->base('USD')->target(['EUR', 'GBP'])->get();

// you can provide a single target currency as a string
$result = $currencyRates->driver('fixer')->target('USD')->get();

历史汇率

对于历史汇率，您需要通过date()方法指定日期。此方法支持日期字符串以及DateTime对象。

$result = $currencyRates->driver('fixer')->date('2001-01-03')->get();
$result = $currencyRates->driver('fixer')->date('2001-01-03')->base('USD')->get();
$result = $currencyRates->driver('fixer')->date('2001-01-03')->base('USD')->target('EUR')->get();

关于Fluent Setters的说明

base、target和date方法设置了由get方法执行的API查询中使用的参数值。这意味着，任何之前未明确重置的先前值将在对API的后续调用中重用。

您只需在需要时将这些参数设置为不同的值。但是，如果您在执行历史查询后想查询最新汇率怎么办？没问题 - 您只需不带参数调用date()即可。

$historical = $currencyRates->driver('fixer')->date('2001-01-03')->get();
$latest = $currencyRates->driver('fixer')->date()->get();

响应

汇率以Response类的对象返回。它提供了3种方法来获取API调用提供的数据。

$result = $currencyRates->driver('fixer')->latest('USD', ['EUR', 'GBP']);

$date = $result->getDate();     // Contains the date as a DateTime object
$rates = $result->getRates();   // Array of exchange rates
$gbp = $result->getRate('GBP'); // Rate for the specific currency, or null if none was provided/requested

它还实现了魔法获取器，以便方便地以属性的形式检索结果。因此，您可以简单地编写以下内容：

$date = $result->date;          // Contains the date as a DateTime object
$rates = $result->rates;        // Array of exchange rates
$gbp = $result->rates['GBP'];   // Rate for the specific currency

货币转换

货币汇率1.2.0版本引入了货币转换功能。这是一个简单的便利功能，基于给定的基础金额将API返回的汇率转换为值，并将其添加到结果对象中。

// Set the amount by chaining in an amount() call
$result = $currencyRates->driver('fixer')->amount(100)->target('USD')->get();

// Get the converted values
$values = $result->getConverted();   // returns an array of values

// You can also access the results as a property:
$value = $result->converted['USD']; // returns 120.07

异常

货币汇率在遇到错误时提供了两种异常。当连接到API端点有问题时，会抛出ConnectionException。对于无效请求和意外的响应，它会抛出ResponseException。

自定义提供者

创建自己的驱动程序很容易。要开始，将src/Providers/FixerProvider.php文件复制到您的项目中，并根据您要支持的服务命名它。让我们称它为FooProvider并将其保存为app/Currency/FooProvider.php（根据需要调整路径 - 此示例基于Laravel应用程序目录结构）。

现在，编辑文件内容以重命名类并提供您的实现。您会注意到，那里只实现了latest和historical方法 - 您永远不需要覆盖任何流畅接口方法，因为这些方法只是对AbstractProvider中的get方法发出的底层latest/historical调用进行代理。

如果您连接到的API需要任何配置（例如应用ID或API密钥），您可以通过AbstractProvider::configure()方法访问存储在$this->config中的数据。

Laravel

最后，您需要注册您的新驱动程序。为此，您可以在app/Providers/AppServiceProvider.php中创建一个新的Laravel服务提供程序或使用您的应用程序服务提供程序。在boot()方法中添加以下内容：

use Ultraleet\CurrencyRates\CurrencyRatesManager;
use GuzzleHttp\Client as GuzzleClient;
use App\Currency\FooProvider;

public function boot(CurrencyRatesManager $manager)
{
    $manager->extend('foo', function ($app) {
        return new FooProvider(new GuzzleClient);
    });
}

就这样！您现在可以使用\CurrencyRates::driver('foo')构造您自定义的驱动程序。

非Laravel项目

虽然您可以使用CurrencyRates::extend()方法来注册您的自定义驱动程序，这与上述Laravel应用程序中的CurrencyRatesManager::extend()方法的工作方式相同（除了一个区别 - 您提供的闭包不接受$app参数），但直接扩展基类本身可能更容易，并为构建提供程序实例实现create[Name]Driver()方法。

use Ultraleet\CurrencyRates\CurrencyRates;
use GuzzleHttp\Client as GuzzleClient;
use Namespace\Path\To\FooProvider;      // replace with your actual class path

class ExtendedCurrencyRates extends CurrencyRates
{
    protected function createFooDriver()
    {
        return new FooProvider(new GuzzleClient);
    }

} 

(注意：当调用driver('name')方法时，驱动名称字符串（在上述create[Name]Driver方法名称中预期为PascalCase（又称StudlyCaps）格式）采用snake_case格式。因此，名为'my_provider'的驱动将在名为createMyProvider()的方法中构建。）

然后，您只需注册或实例化扩展服务而不是原始服务即可。