README

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

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

服务

当前可用

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

安装

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

composer require ultraleet/currency-rates

Laravel <5.5

Laravel 5.5引入了包发现功能，Currency Rates完全利用了该功能。但是，如果您正在使用Laravel的早期版本，您需要在您的config/app.php文件中注册服务提供者

'providers' => [
    // Other service providers...

    Ultraleet\CurrencyRates\CurrencyRatesServiceProvider::class,
],

此外，在同一个文件中，将CurrencyRates外观添加到aliases数组中

'CurrencyRates' => Ultraleet\CurrencyRates\Facades\CurrencyRates::class,

入门指南

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();

关于流畅设置器的说明

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

货币转换

Currency Rates 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

异常

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

自定义提供者

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

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

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

Laravel

最后，您需要注册您的新驱动程序。为此，您可以在 boot() 方法中创建一个新的Laravel服务提供程序，或使用您的应用程序服务提供程序 app/Providers/AppServiceProvider.php。将以下内容添加到 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') 方法时，驱动名称字符串（在 snake_case 中）而在上述 create[Name]Driver 方法名称中期望为 PascalCase（也称为 StudlyCaps 案）。因此，名为 'my_provider' 的驱动程序将在名为 createMyProvider() 的方法中构建。）

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