README

PHP中格鲁吉亚国家银行（NBG）货币服务API包装器

安装

使用 Composer 安装此包。

composer require stichoza/nbg-currency

注意需要 PHP 8.1 或更高版本。对于旧版本的 PHP，使用以下版本的此包

快速示例

NbgCurrency::rate('usd'); // 2.7177
NbgCurrency::rate('usd', '2022-12-02'); // 2.7112

NbgCurrency::get('usd')->rate; // 2.7177
NbgCurrency::get('usd', '2022-12-02')->rate; // 2.7112
NbgCurrency::get('usd', '2022-12-02', 'en')->name; // US Dollar

NbgCurrency::date(Carbon::yesterday())->get('usd')->diff; // 0.0012
NbgCurrency::date('2022-12-02', 'en')->get('usd')->increased(); // true

继续阅读以获取有关附加功能的更多详细信息。

基本用法

该类命名空间为 Stichoza\NbgCurrency\NbgCurrency

use Stichoza\NbgCurrency\NbgCurrency;

此包有三个主要静态方法，您可以通过这些方法访问货币汇率。

获取货币汇率

NbgCurrency::rate() 方法返回一个 float 类型的汇率。

NbgCurrency::rate(string $code, DateTimeInterface|string|null $date = null): float

重要汇率总是针对 单个单位。原始 NBG JSON API 返回每种货币的不同金额的汇率。例如，日元（JPY）的汇率为 1.9865，数量设置为 100（100 JPY 为 1.9865 GEL）。这在计算中相当令人困惑，因此 此包始终返回单个单位的单价。因此，在这种情况下，JPY 将为 0.019865（1 JPY 为 0.019865 GEL）。

示例

NbgCurrency::rate('usd'); // Returns current rate of USD. Example: 2.7177
NbgCurrency::rate('usd', '2022-12-02'); // USD rate on 2022-12-02
NbgCurrency::rate('eur', 'yesterday'); // EUR rate from yesterday. Strings are parsed via Carbon::parse()
NbgCurrency::rate('eur', Carbon::yesterday()); // EUR rate from yesterday
NbgCurrency::rate('gbp', Carbon::today()->subDays(5)); // GBP rate 5 days ago
NbgCurrency::rate('gbp', new DateTime()); // GBP rate today

if (NbgCurrency::rate('usd') > 3) {
    echo 'Oh no!';
}

当传递日期作为 Carbon 或 DateTime 对象时，建议将其时区设置为 Asia/Tbilisi 以避免意外行为。为了方便，时区字符串可用作 NbgCurrency::TIMEZONE 类常量。

获取货币对象

NbgCurrency::get() 方法返回一个包含指定日期的货币数据的 Currency 对象。

此方法接受与 ::rate() 方法相同的参数，以及一个额外的语言参数（用于货币名称）。

NbgCurrency::get(string $code, DateTimeInterface|string|null $date = null, string $language = 'ka'): Currency

示例

$usd = NbgCurrency::get('usd'); // Currency object (Stichoza\NbgCurrency\Data\Currency)

$usd->code; // USD
$usd->rate; // 2.7112
$usd->name; // აშშ დოლარი
$usd->diff; // -0.0065
$usd->date; // Carbon object of date: 2022-12-01 17:45:12
$usd->validFrom; // Carbon object since when the rate is valid: 2022-12-02 00:00:00
$usd->change; // Currency rate change. -1 if decreased, 0 if unchanged and 1 if increased.

// Using methods available on Carbon objects
$usd->date->format('j F Y'); // 1 December 2022
$usd->date->diffForHumans(); // 3 days ago
$usd->validFrom->isPast(); // true

// Additional methods
$usd->increased(); // Returns true if rate has increased, false otherwise.
$usd->decreased(); // Returns true if rate has decreased, false otherwise.
$usd->unchanged(); // Returns true if rate hasn't changed, false otherwise.

// The changeString() method returns first parameter if rate was increased, second string if there was
// no change and third string if the rate went up. Useful for CSS classes, font icons, etc.
$class = $usd->changeString('text-red', 'text-gray', 'text-green');
$icon  = $usd->changeString('fa-arrow-down', 'fa-circle', 'fa-arrow-down');

注意 Currency 类的所有属性都声明为 readonly。更新它们将导致致命错误。

高级用法

获取所有货币

NbgCurrency::date() 方法将返回一个 Currencies 对象。这是一个类似集合的对象，包含指定日期可用的所有 Currency 对象列表。

NbgCurrency::date(DateTimeInterface|string|null $date = null, string $language = 'ka'): Currencies

示例

$currencies = NbgCurrency::date('3 days ago');
$currencies = NbgCurrency::date(Carbon::now()->startOfMonth(), 'en');

Currencies 类具有日期属性和您可以使用的一些方法。

$currencies->date; // Carbon object of date

$currencies->get('usd'); // Returns Currency object for USD
$currencies->has('eur'); // True if EUR currency is contained in $currencies collection
$currencies->count(); // Count of Currency objects in collection

$currencies->get('usd')->rate; // Currency rate of USD
$currencies->get('eur')->date->diffForHumans(); // 10 days ago

请注意，Currencies 对象的 ->get() 方法只有一个参数 string $code，而具有相同名称的静态方法（NbgCurrency::get()）有两个额外的参数，如上所述的基本用法示例中所述。

Currencies 对象还实现了 Countable 和 IteratorAggregate 接口，因此您可以在 foreach 循环和 count() 函数中使用该对象。

示例

$currencies = NbgCurrency::date('2022-12-02', 'en'); // Currencies object (Stichoza\NbgCurrency\Data\Currencies) 

echo 'Total ' . count($currencies) . ' currencies for ' . $currencies->date->toFormattedDateString();
// Total 43 currencies for Dec 2, 2022

foreach ($currencies as $code => $currency) {
    echo $currency->code . ' costs ' . $currency->rate;
}
// AED costs 7.3662
// AMD costs 6.8453
// ...

错误处理

Stichoza\NbgCurrency\Exceptions 命名空间中有 5 个异常可能在方法中抛出

CurrencyNotFoundException - 如果货币不可用。
DateNotFoundException - 如果指定的日期不可用。
LanguageNotFoundException - 如果指定的语言不可用。
InvalidDateException - 如果指定的日期格式无效或无法解析。
RequestFailedException - 如果API请求过程中发生错误。

以上所有异常都继承自Exception类，因此您可以通过捕获Exception或Throwable来处理所有异常。

try {
    $usdRate = NbgCurrency::date('10 days ago', 'en')->get('usd')->rate;
} catch (Exception) {
    // Whoops...
}

附加信息

HTTP请求次数

当您访问任何货币时，所选语言当天所有货币将一次性通过API请求并存储在NbgCurrency类的属性中。当您请求其他货币时，对于相同日期和语言将不会发出额外的HTTP请求。

// Next 3 method calls will result in 1 HTTP request in total.
NbgCurrency::rate('usd');
NbgCurrency::rate('eur');
NbgCurrency::rate('gbp');

// Next 3 method calls will result in 3 HTTP requests in total.
NbgGurrency::rate('usd', '2022-10-10');
NbgGurrency::rate('eur', '2022-11-11', 'en');
NbgGurrency::rate('gbp', '2022-11-11');

// Next 3 method calls will result in 2 HTTP request in total.
NbgGurrency::rate('usd', '2022-11-11');
NbgGurrency::rate('eur', '2022-11-11');
NbgGurrency::rate('gbp', '2022-11-11', 'en');

内存使用与缓存

默认情况下，所有检索到的货币都存储在NbgCurrency类的静态属性中。如果您打算获取多个不同日期的货币，可能会使用过多的内存。在这种情况下，建议关闭缓存功能。

NbgCurrency::disableCaching(); // Disable caching, also removes data stored in the property.
NbgCurrency::enableCaching(); // Enables caching in class property.

另一方面，禁用缓存可能会增加发出的HTTP请求数量。例如

$codes = ['USD', 'EUR', 'GBP', 'UAH', 'JPY'];

foreach ($codes as $code) {
    echo NbgCurrency::rate($code);
}

在启用缓存的情况下，上述代码将对API发出单个HTTP请求。但是如果您禁用缓存，它将发送5个独立的HTTP请求。要使用单个HTTP请求和禁用缓存加载同一日期的多币种，可以使用::date()方法获取Currencies对象，然后访问其中的所有对象。

$codes = ['USD', 'EUR', 'GBP', 'UAH', 'JPY'];

$currencies = NbgCurrency::date();

foreach ($codes as $code) {
    echo $currencies->get($code)->rate;
}

在这种情况下，即使禁用缓存也会发出单个HTTP请求。

关键词

第纳尔汇率，国家银行的汇率，货币，第纳尔货币汇率，laris kursi，laris valuta，第纳尔货币，格鲁吉亚国家银行，nbg

stichoza / nbg-currency

维护者

详细信息