PHPackages                             nurbekjummayev/cbu-currency - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. nurbekjummayev/cbu-currency

ActiveLibrary[Utility & Helpers](/categories/utility)

nurbekjummayev/cbu-currency
===========================

Central Bank of Uzbekistan currency rates package for Laravel

1.1.0(4mo ago)00MITPHPPHP ^8.1|^8.2|^8.3|^8.4

Since Nov 8Pushed 4mo agoCompare

[ Source](https://github.com/nurbekjummayev/cbu-currency)[ Packagist](https://packagist.org/packages/nurbekjummayev/cbu-currency)[ RSS](/packages/nurbekjummayev-cbu-currency/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (7)Versions (3)Used By (0)

CBU Currency - Central Bank of Uzbekistan Exchange Rates
========================================================

[](#cbu-currency---central-bank-of-uzbekistan-exchange-rates)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/79d9dc18eceee2935954a4a0ecafdf8453f907f36884bda881f6b64a95c3d01e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253545382e31253743253545382e32253743253545382e33253743253545382e342d626c7565)](https://www.php.net/)[![Laravel Version](https://camo.githubusercontent.com/d83651fe9184ee6fccd363c40a62fc3c74e9b7eaa5c668cea2b36ea37165e1f3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d2535453130253743253545313125374325354531322d726564)](https://laravel.com/)[![Tests](https://camo.githubusercontent.com/f37e4fbb235fd4d3453e419f25930a35b46c6ac141890a1c1fcb9ee41d2d75bb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d34332532307061737365642d627269676874677265656e)](https://pestphp.com/)

A Laravel package for working with Central Bank of Uzbekistan (CBU) currency exchange rates. This package provides easy-to-use methods for fetching, storing, and converting currencies with high precision using BCMath.

**English version** | [O'zbek versiyasi](README_UZ.md)

📋 Table of Contents
-------------------

[](#-table-of-contents)

- [Features](#-features)
- [Requirements](#-requirements)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Usage](#-usage)
    - [Currency Conversion](#currency-conversion)
    - [Get Exchange Rates](#get-exchange-rates)
    - [Get Currencies List](#get-currencies-list)
    - [Sync Currencies](#sync-currencies)
- [Artisan Commands](#-artisan-commands)
- [Auto Synchronization](#-auto-synchronization)
- [Database Structure](#-database-structure)
- [Testing](#-testing)
- [API Endpoints](#-api-endpoints)
- [License](#-license)

✨ Features
----------

[](#-features)

- 📊 **CBU API Integration** - Fetch currency rates from Central Bank API
- 💱 **High-Precision Conversion** - Accurate calculations using BCMath
- 🗄️ **Database Storage** - Store historical rates for fast access
- 🎯 **Simple API** - Intuitive and convenient interface
- ⚙️ **Configurable** - Full configuration capabilities
- 🔄 **Auto Synchronization** - Automatic currency updates
- 📅 **Historical Data** - Rates for any date
- 🚀 **RESTful API** - Complete REST API endpoints
- ✅ **Full Test Coverage** - 43 tests included
- 🎨 **Fluent Interface** - Beautiful and readable code

📦 Requirements
--------------

[](#-requirements)

- PHP ^8.1|^8.2|^8.3|^8.4
- Laravel ^10.0|^11.0|^12.0
- BCMath PHP Extension
- GuzzleHTTP ^7.0

🚀 Installation
--------------

[](#-installation)

### 1. Install via Composer

[](#1-install-via-composer)

```
composer require nurbekjummayev/cbu-currency
```

### 2. Publish Configuration and Migrations

[](#2-publish-configuration-and-migrations)

```
# Publish config file
php artisan vendor:publish --tag=cbu-currency-config

# Publish migrations (optional, auto-loaded by default)
php artisan vendor:publish --tag=cbu-currency-migrations
```

⚙️ Configuration
----------------

[](#️-configuration)

Configuration file: `config/cbu-currency.php`

```
return [
    // CBU API Base URL
    'base_url' => env('CBU_BASE_URL', 'https://cbu.uz/ru/arkhiv-kursov-valyut/json'),

    // Cache duration in minutes
    'cache_duration' => env('CBU_CACHE_DURATION', 60),

    // Default currency code
    'default_currency' => env('CBU_DEFAULT_CURRENCY', 'USD'),

    // BCMath calculation scale (decimal places)
    'scale' => env('CBU_SCALE', 2),

    // Data source: 'database' or 'api'
    'source' => env('CBU_SOURCE', 'database'),

    // Enable/disable logging
    'log_enabled' => env('CBU_LOG_ENABLED', true),

    // API routes configuration
    'routes' => [
        'prefix' => env('CBU_ROUTES_PREFIX', 'api/cbu'),
        'middleware' => ['api'],
    ],
];
```

### Environment Variables

[](#environment-variables)

Add to your `.env` file:

```
CBU_BASE_URL=https://cbu.uz/ru/arkhiv-kursov-valyut/json
CBU_CACHE_DURATION=60
CBU_DEFAULT_CURRENCY=USD
CBU_SCALE=2
CBU_SOURCE=database
CBU_LOG_ENABLED=true
CBU_ROUTES_PREFIX=api/cbu
```

### Data Source

[](#data-source)

The `CBU_SOURCE` configuration determines where currency rates are fetched from:

#### Option 1: Database (Recommended)

[](#option-1-database-recommended)

- **Value:** `database`
- **Pros:** Faster response, works offline, reduced API calls
- **Cons:** Requires periodic synchronization
- **Best for:** Production environments

When using `database` source, you need to:

**Step 1: Run Migrations**

```
php artisan migrate
```

This creates two tables:

- `currencies` - stores currency information (USD, EUR, etc.)
- `currency_rates` - stores daily exchange rates

**Step 2: Sync Currencies**

```
# Fetch and store all available currencies from CBU
php artisan cbu:sync-currencies
```

**Step 3: Fetch Exchange Rates**

```
# Fetch today's rates
php artisan cbu:fetch-rates

# Fetch rates for specific date
php artisan cbu:fetch-rates 2025-01-25

# Fetch yesterday's rates
php artisan cbu:fetch-rates yesterday
```

#### Option 2: API (Direct)

[](#option-2-api-direct)

- **Value:** `api`
- **Pros:** Always fresh data, no database needed
- **Cons:** Slower response, requires internet connection
- **Best for:** Development or when real-time data is critical

When using `api` source:

- No migrations needed
- No synchronization required
- Data fetched directly from CBU API on each request

📖 Usage
-------

[](#-usage)

### Currency Conversion

[](#currency-conversion)

The `convert()` method provides a fluent interface for currency conversion with high precision using BCMath.

```
use Cbu\Currency\Facades\CbuCurrency;

// Basic conversion
$result = CbuCurrency::convert()
    ->from('USD')
    ->to('EUR')
    ->amount(100)
    ->get();

echo $result->result;        // 94.11
echo $result->fromRate;      // 12705.00
echo $result->toRate;        // 13500.00
echo $result->amountInUzs;   // 1270500.00
```

#### Convert to UZS

[](#convert-to-uzs)

```
$result = CbuCurrency::convert()
    ->from('USD')
    ->to('UZS')
    ->amount(100)
    ->get();

echo $result->result;  // 1270500.00
```

#### Convert from UZS

[](#convert-from-uzs)

```
$result = CbuCurrency::convert()
    ->from('UZS')
    ->to('USD')
    ->amount(1000000)
    ->get();

echo $result->result;  // 78.70
```

#### Cross Currency Conversion

[](#cross-currency-conversion)

```
// USD to EUR through UZS
$result = CbuCurrency::convert()
    ->from('USD')
    ->to('EUR')
    ->amount(100)
    ->get();

// Calculation: 100 USD * 12705 = 1270500 UZS
//              1270500 UZS / 13500 = 94.11 EUR
echo $result->result;        // 94.11
echo $result->amountInUzs;   // 1270500.00
```

#### Using Numeric Codes

[](#using-numeric-codes)

```
$result = CbuCurrency::convert()
    ->fromCode(840)  // USD
    ->toCode(978)    // EUR
    ->amount(100)
    ->get();
```

#### Specify Date

[](#specify-date)

```
// Specific date
$result = CbuCurrency::convert()
    ->from('USD')
    ->to('EUR')
    ->amount(100)
    ->date('2025-01-25')
    ->get();

// Today's date
$result = CbuCurrency::convert()
    ->from('USD')
    ->to('EUR')
    ->amount(100)
    ->today()
    ->get();
```

#### Change Data Source

[](#change-data-source)

```
use Cbu\Currency\Enums\CurrencySource;

// Force API source
$result = CbuCurrency::convert()
    ->source(CurrencySource::API)
    ->from('USD')
    ->to('EUR')
    ->amount(100)
    ->get();

// Force database source
$result = CbuCurrency::convert()
    ->source(CurrencySource::DATABASE)
    ->from('USD')
    ->to('EUR')
    ->amount(100)
    ->get();
```

#### With Caching

[](#with-caching)

```
// Cache result for 60 minutes
$result = CbuCurrency::convert()
    ->from('USD')
    ->to('EUR')
    ->amount(100)
    ->cache(60)
    ->get();
```

### Get Exchange Rates

[](#get-exchange-rates)

The `rate()` method retrieves exchange rates for specific currencies and dates.

```
use Cbu\Currency\Facades\CbuCurrency;

// Get single currency rate for today
$rate = CbuCurrency::rate('USD');

echo $rate->ccy;      // "USD"
echo $rate->rate;     // 12705.00
echo $rate->diff;     // 15.25
echo $rate->date;     // "2025-11-09"
```

#### Get Rate for Specific Date

[](#get-rate-for-specific-date)

```
// Get USD rate for specific date
$rate = CbuCurrency::rate('USD', '2025-01-25');

echo $rate->rate;  // 12705.00
echo $rate->date;  // "2025-01-25"
```

#### Get All Rates

[](#get-all-rates)

```
// Get all currencies rates for today
$rates = CbuCurrency::rate();

foreach ($rates as $rate) {
    echo "{$rate->ccy}: {$rate->rate}\n";
}
// USD: 12705.00
// EUR: 13500.00
// RUB: 130.00
```

#### Get All Rates for Specific Date

[](#get-all-rates-for-specific-date)

```
// Get all rates for specific date
$rates = CbuCurrency::rate(null, '2025-01-25');

foreach ($rates as $rate) {
    echo "{$rate->ccy}: {$rate->rate} ({$rate->date})\n";
}
```

### Get Currencies List

[](#get-currencies-list)

The `currencies()` method retrieves available currency information.

```
use Cbu\Currency\Facades\CbuCurrency;

// Get all currencies
$currencies = CbuCurrency::currencies();

foreach ($currencies as $currency) {
    echo "{$currency->ccy} - {$currency->name_en}\n";
}
// USD - US Dollar
// EUR - Euro
// RUB - Russian Ruble
```

#### Get Specific Currency

[](#get-specific-currency)

```
// Get single currency info
$currency = CbuCurrency::currencies('USD');

echo $currency->ccy;       // "USD"
echo $currency->name_en;   // "US Dollar"
echo $currency->name_uz;   // "AQSH dollari"
echo $currency->name_ru;   // "Доллар США"
echo $currency->code;      // 840
```

#### Get Currency Codes Only

[](#get-currency-codes-only)

```
// Get array of currency codes
$codes = CbuCurrency::currencies()->pluck('ccy')->toArray();

// ['USD', 'EUR', 'RUB', 'GBP', 'JPY', ...]
```

### Sync Currencies

[](#sync-currencies)

The `sync()` method synchronizes currencies and rates from CBU API to your database.

```
use Cbu\Currency\Facades\CbuCurrency;

// Sync currencies list
CbuCurrency::sync('currencies');

// Sync today's rates
CbuCurrency::sync('rates');

// Sync rates for specific date
CbuCurrency::sync('rates', '2025-01-25');
```

#### Sync Both Currencies and Rates

[](#sync-both-currencies-and-rates)

```
// Sync both currencies and rates
CbuCurrency::sync('currencies');
CbuCurrency::sync('rates');
```

🔧 Artisan Commands
------------------

[](#-artisan-commands)

The package provides two Artisan commands for managing currency data.

### 1. Sync Currencies

[](#1-sync-currencies)

Fetch and store all available currencies from CBU API to database.

```
php artisan cbu:sync-currencies
```

**What it does:**

- Fetches all currencies from CBU API
- Adds new currencies to `currencies` table
- Updates existing currency information

**Example output:**

```
Fetching currencies from CBU API...
Found 30 currencies
Synced: USD, EUR, RUB, GBP, JPY, CHF...
Currency synchronization completed successfully.

```

**When to use:**

- After initial installation
- When CBU adds new currencies
- Weekly maintenance (recommended)

### 2. Fetch Exchange Rates

[](#2-fetch-exchange-rates)

Fetch and store exchange rates for a specific date.

```
# Fetch today's rates
php artisan cbu:fetch-rates

# Fetch for specific date
php artisan cbu:fetch-rates 2025-01-25

# Fetch yesterday's rates
php artisan cbu:fetch-rates yesterday

# Fetch for relative date
php artisan cbu:fetch-rates "1 week ago"
php artisan cbu:fetch-rates "2025-01-01"
```

**What it does:**

- Fetches exchange rates from CBU API for specified date
- Stores rates in `currency_rates` table
- Updates existing rates if already present

**Example output:**

```
Fetching rates for date: 2025-01-25
Found 30 rates
Saved: USD (12705.00), EUR (13500.00), RUB (130.00), GBP (16200.00)...
Currency rates fetched successfully.

```

**When to use:**

- Daily to keep rates up-to-date
- To fetch historical rates
- After syncing currencies

⏰ Auto Synchronization
----------------------

[](#-auto-synchronization)

For production environments, automate currency updates using Laravel's Task Scheduler.

### Laravel Scheduler

[](#laravel-scheduler)

Add to `app/Console/Kernel.php`:

```