README

A Laravel package that fetches Central Bank of Kenya (CBK) foreign exchange rates daily and stores them in your database, with a clean API for querying rates by date, currency, or history.

Features

• ✅ Fetches live rates from the CBK official data endpoint
• ✅ Stores rates with ISO currency codes and human-readable names
• ✅ Daily auto-scheduling via Laravel's task scheduler — no cron setup needed
• ✅ Artisan command for manual fetches and CI pipelines
• ✅ upsert logic — re-running never creates duplicates
• ✅ Eloquent model with helpful query scopes
• ✅ Optional API endpoints (REST)
• ✅ Optional pruning of old records
• ✅ Configurable via .env or published config file

Requirements

Installation

composer require pk305/cbk-forex

Publish the config (optional)

php artisan vendor:publish --tag=cbk-forex-config

Run the migration

php artisan migrate

Scheduling (Daily Auto-Fetch)

The package automatically registers a daily scheduled command. All you need is a working Laravel scheduler. If you haven't set it up yet, add this single cron entry to your server:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

By default the fetch runs at 14:00 (2 PM) EAT — after CBK typically publishes rates. Change the time in your .env:

CBK_FOREX_FETCH_TIME=14:00

Manual Fetch (Artisan)

# Fetch and store latest rates
php artisan cbk-forex:fetch

# Fetch + prune old records
php artisan cbk-forex:fetch --prune

Environment Variables

# CBK data endpoint (rarely needs changing)
CBK_FOREX_URL=https://www.centralbank.go.ke/wp-admin/admin-ajax.php?action=get_wdtable&table_id=193

# HTTP timeouts (seconds)
CBK_FOREX_TIMEOUT=30
CBK_FOREX_CONNECT_TIMEOUT=10

# SSL verification (set to false only for local dev)
CBK_FOREX_VERIFY_SSL=true

# Daily fetch time (HH:MM, 24hr)
CBK_FOREX_FETCH_TIME=14:00

# Database table name
CBK_FOREX_TABLE=cbk_exchange_rates

# Pruning (optional)
CBK_FOREX_PRUNE=false
CBK_FOREX_KEEP_DAYS=365

Usage

Using the Facade

use Pk305\CbkForex\Facades\CbkForex;

// Manually trigger a fetch
$result = CbkForex::fetchAndStore();
// => ['fetched' => 21, 'saved' => 21, 'skipped' => 0, 'date' => '2026-04-23']

// Get the latest available rates (keyed by ISO code)
$rates = CbkForex::latestRates();
$usdRate = $rates['USD']->rate; // e.g. 129.21

// Get rates for a specific date
$rates = CbkForex::ratesForDate('2026-04-22');

// Get 30-day history for a currency
$history = CbkForex::historyForCurrency('USD', 30);

Using the Eloquent Model Directly

use Pk305\CbkForex\Models\ExchangeRate;

// Today's rates
ExchangeRate::forDate()->get();

// Specific date
ExchangeRate::forDate('2026-04-22')->get();

// A single currency
ExchangeRate::forCurrency('USD')->forDate()->first();

// Quick rate lookup
$rate = ExchangeRate::getRate('EUR'); // float or null

// Latest rates (most recent date in DB)
ExchangeRate::latest()->get();

// Date range
ExchangeRate::betweenDates('2026-04-01', '2026-04-23')
    ->forCurrency('GBP')
    ->orderBy('rate_date')
    ->get();

REST API (Optional)

If you want to expose rates over HTTP, register these routes in your routes/api.php:

use Pk305\CbkForex\Http\Controllers\ExchangeRateController;

Route::prefix('cbk-forex')->group(function () {
    Route::get('/rates',              [ExchangeRateController::class, 'latest']);
    Route::get('/rates/{date}',       [ExchangeRateController::class, 'forDate']);
    Route::get('/rates/currency/{code}', [ExchangeRateController::class, 'history']);
});

Example Responses

GET /api/cbk-forex/rates

{
  "data": [
    {
      "id": 1,
      "rate_date": "2026-04-23",
      "currency_label": "US DOLLAR",
      "currency_code": "USD",
      "currency_name": "US Dollar",
      "rate": 129.21
    }
  ],
  "meta": { "date": "2026-04-23", "count": 21 }
}

GET /api/cbk-forex/rates/currency/USD?days=7

{
  "data": [ ... ],
  "meta": { "currency_code": "USD", "days": 7, "count": 7 }
}

Supported Currencies

Testing

composer test

License

MIT