Download the PHP package nurbekjummayev/cbu-currency without Composer
On this page you can find all versions of the php package nurbekjummayev/cbu-currency. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download nurbekjummayev/cbu-currency
More information about nurbekjummayev/cbu-currency
Files in nurbekjummayev/cbu-currency
Package cbu-currency
Short Description Central Bank of Uzbekistan currency rates package for Laravel
License MIT
Homepage https://github.com/nurbekjummayev/cbu-currency
Informations about the package cbu-currency
CBU Currency - Central Bank of Uzbekistan Exchange Rates
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
๐ Table of Contents
- Features
- Requirements
- Installation
- Configuration
- Usage
- Currency Conversion
- Get Exchange Rates
- Get Currencies List
- Sync Currencies
- Artisan Commands
- Auto Synchronization
- Database Structure
- Testing
- API Endpoints
- License
โจ 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
- PHP 8.3 โ 8.5
- Laravel ^13.0
- BCMath PHP Extension
- GuzzleHTTP ^7.0
Note: This package targets Laravel 13 and above, which requires PHP >= 8.3.
๐ Installation
1. Install via Composer
2. Publish Configuration and Migrations
โ๏ธ Configuration
Configuration file: config/cbu-currency.php
Environment Variables
Add to your .env file:
Data Source
The CBU_SOURCE configuration determines where currency rates are fetched from:
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
This creates two tables:
currencies- stores currency information (USD, EUR, etc.)currency_rates- stores daily exchange rates
Step 2: Sync Currencies
Step 3: Fetch Exchange Rates
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
Currency Conversion
The convert() method provides a fluent interface for currency conversion with high precision using BCMath.
Convert to UZS
Convert from UZS
Cross Currency Conversion
Using Numeric Codes
Specify Date
Change Data Source
With Caching
Get Exchange Rates
The rate() method retrieves exchange rates for specific currencies and dates.
Get Rate for Specific Date
Get All Rates
Get All Rates for Specific Date
Get Currencies List
The currencies() method retrieves available currency information.
Get Specific Currency
Get Currency Codes Only
Sync Currencies
The sync() method synchronizes currencies and rates from CBU API to your database.
Sync Both Currencies and Rates
๐ง Artisan Commands
The package provides two Artisan commands for managing currency data.
1. Sync Currencies
Fetch and store all available currencies from CBU API to database.
What it does:
- Fetches all currencies from CBU API
- Adds new currencies to
currenciestable - Updates existing currency information
Example output:
When to use:
- After initial installation
- When CBU adds new currencies
- Weekly maintenance (recommended)
2. Fetch Exchange Rates
Fetch and store exchange rates for a specific date.
What it does:
- Fetches exchange rates from CBU API for specified date
- Stores rates in
currency_ratestable - Updates existing rates if already present
Example output:
When to use:
- Daily to keep rates up-to-date
- To fetch historical rates
- After syncing currencies
โฐ Auto Synchronization
For production environments, automate currency updates using Laravel's Task Scheduler.
Laravel Scheduler
Add to app/Console/Kernel.php:
Activate Scheduler
Ensure the Laravel scheduler is running by adding this to your cron:
Alternative: Direct Cron Jobs
If not using Laravel Scheduler, add cron jobs directly:
Docker/Kubernetes
For containerized environments, use supervisor or similar:
๐๏ธ Database Structure
Currencies Table
| Column | Type | Description |
|---|---|---|
| id | bigint | Primary key |
| ccy | string | Currency code (unique) - USD, EUR, RUB |
| name_uz | string | Name in Uzbek - AQSH dollari |
| name_oz | string | Name in Uzbek (Cyrillic) - ะาะจ ะดะพะปะปะฐัะธ |
| name_ru | string | Name in Russian - ะะพะปะปะฐั ะกะจะ |
| name_en | string | Name in English - US Dollar |
| code | string | Numeric code - 840 |
| cbu_id | string | CBU identifier |
| created_at | timestamp | Creation time |
| updated_at | timestamp | Update time |
Currency Rates Table
| Column | Type | Description |
|---|---|---|
| id | bigint | Primary key |
| currency_id | bigint | Foreign key to currencies |
| date | date | Rate date (indexed) |
| currency_date | date | Original CBU date |
| rate | decimal(15,4) | Exchange rate - 12705.0000 |
| diff | decimal(15,4) | Difference from previous - 15.2500 |
| nominal | integer | Nominal value - 1 |
| created_at | timestamp | Creation time |
| updated_at | timestamp | Update time |
Indexes:
date- For fast lookups['currency_id', 'date']- Composite index
Unique constraint: ['currency_id', 'date'] - Only one rate per currency per day
๐งช Testing
The package provides full test coverage using Pest PHP framework.
Running Tests
For detailed testing documentation, see TESTING.md
๐ API Endpoints
The package automatically registers RESTful API endpoints for accessing currency data.
Base URL: {your-domain}/api/cbu
1. Get All Currencies
Response:
2. Get Currency Codes
Response:
3. Get Specific Currency
Example:
Response:
4. Get Today's Rates
Response:
5. Get Rates by Date
Query Parameters:
date(optional): Date inY-m-dformat (e.g.,2025-01-25)
Example:
6. Get Specific Currency Rate
Example:
Response:
7. Convert Currency
Request Body:
Response:
Validation Rules:
amount- required, numeric, minimum 0.01from- required, valid 3-letter currency codeto- required, valid 3-letter currency codedate- optional, Y-m-d format, cannot be future datescale- optional, integer 0โ20; when sent, the final result is rounded to that many decimals, otherwise full precision is returned
8. Get Conversion Rate
Returns the conversion rate for 1 unit of source currency. The optional scale query parameter (0โ20) rounds the final result; without it the full-precision value is returned.
Example:
Response:
Error Responses
All endpoints return a consistent error format:
Common HTTP Status Codes:
200- Success400- Bad Request (validation failed)404- Not Found (currency or rate not found)500- Internal Server Error
Customizing API Routes
You can enable/disable package routes and customize the route prefix in config/cbu-currency.php:
Or in .env:
If you only use the package via the CbuCurrency facade and don't need the built-in HTTP endpoints, disable them entirely:
๐ค AI / Laravel Boost Integration
This package ships with Laravel Boost AI guidelines and an agent skill (cbu-currency-development). If your project uses Boost, run:
Boost will automatically detect this package and offer to install its guidelines and skill, so AI agents (Claude Code, Cursor, Codex, etc.) know how to use the CbuCurrency facade, builders, sync commands, and API endpoints correctly. To pick up the skill after adding this package to an existing Boost setup, run php artisan boost:update --discover.
MCP Server (AI Agent Tools)
The package ships an MCP (Model Context Protocol) server that lets AI agents call currency tools directly. It activates automatically when the optional laravel/mcp package is installed:
Available tools:
| Tool | Description |
|---|---|
get-rates |
All CBU rates for a date |
get-rate |
Single currency rate by code and date |
convert-currency |
Convert between currencies (optional scale for rounding) |
list-currencies |
Currency metadata with multilingual names |
sync-rates |
Sync rates from the CBU API into the database |
The local (stdio) server is registered as cbu-currency. Connect it to your AI agent, e.g. for Claude Code:
Test it with the MCP Inspector:
Configuration (config/cbu-currency.php):
๐ License
MIT License. See LICENSE file for details.
๐จโ๐ป Author
Nurbek Jummayev
- GitHub: @nurbekjummayev
- Email: [email protected]
๐ Useful Links
All versions of cbu-currency with dependencies
ext-bcmath Version *
illuminate/support Version ^10.0|^11.0|^12.0|^13.0
guzzlehttp/guzzle Version ^7.0
nurbekjummayev/laravel-api-response-helpers Version ^1.2