README

Laravel Hyper-Cache-IO is an ultra-fast, distributed cache driver for Laravel applications. By combining L1 in-memory caching with a persistent SQLite WAL backend, it delivers exceptional performance and reliability without the overhead of Redis or Memcached.

Designed for modern PHP environments like FrankenPHP, Swoole, and traditional Nginx/FPM, it features a lightweight internal HTTP API for seamless multi-server synchronization.

⚡ Features

🚀 High Performance: Built on SQLite WAL (Write-Ahead Logging) for lightning-fast reads and writes.
🧠 L1 In-Memory Cache: Ephemeral memory caching for instant access during the request lifecycle.
🔒 Distributed Locking: Full support for atomic locks across multiple servers.
⚡ Atomic Operations: Native support for Cache::add() and atomic increment/decrement.
🌐 HTTP Synchronization: Robust Primary/Secondary architecture for multi-node setups.
🛡️ Secure: Token-based authentication protects your internal cache API.
✅ Modern Compatibility: Fully supports Laravel 10.x, 11.x, and 12.x.

📦 Installation

Install the package via Composer:

composer require iperamuna/laravel-hypercacheio

Run the installation command to configure the package:

php artisan hypercacheio:install

⚙️ Configuration

1. Set the Cache Driver

Update your .env file to use hypercacheio:

CACHE_DRIVER=hypercacheio

2. Configure Server Roles

Hyper-Cache-IO uses a simple Primary/Secondary architecture. You can also run it in standalone mode (Primary only).

Primary Server (Writer)

A single "Primary" node handles all write operations to the database. You can optionally list secondary server URLs so the primary replicates writes to them.

HYPERCACHEIO_SERVER_ROLE=primary
HYPERCACHEIO_API_TOKEN=your-secr3t-t0ken-here

# Optional: comma-separated list of secondary server URLs for replication.
# Invalid URLs are silently ignored. Whitespace around URLs is trimmed.
HYPERCACHEIO_SECONDARY_URLS="https://s2.example.com,https://s3.example.com"

# Optional: fire-and-forget async replication (default: true)
HYPERCACHEIO_ASYNC=true

Secondary Server (Reader)

"Secondary" nodes read from their local copy (synced via shared volume or future replication features) and forward writes to the Primary via HTTP.

HYPERCACHEIO_SERVER_ROLE=secondary
HYPERCACHEIO_PRIMARY_URL=https://primary.example.com/api/hypercacheio
HYPERCACHEIO_API_TOKEN=your-secr3t-t0ken-here

3. Advanced Configuration

Publish and fine-tune the config file at config/hypercacheio.php:

return [
    // Server role: 'primary' or 'secondary'
    'role' => env('HYPERCACHEIO_SERVER_ROLE', 'primary'),

    // Primary server API URL (used by secondary nodes)
    'primary_url' => env('HYPERCACHEIO_PRIMARY_URL', 'http://127.0.0.1/api/hypercacheio'),

    // Comma-separated secondary server URLs for write replication
    // Invalid URLs are silently discarded to prevent misconfiguration
    'secondaries' => HypercacheioSecondaryUrls(env('HYPERCACHEIO_SECONDARY_URLS', ''), ','),

    // Shared secret for inter-server authentication (X-HyperCacheio-Token header)
    'api_token' => env('HYPERCACHEIO_API_TOKEN', 'changeme'),

    // HTTP timeout in seconds for peer-server requests (recommended: 1–3)
    'timeout' => 1,

    // Fire-and-forget async replication (lower latency, silent failures)
    'async_requests' => env('HYPERCACHEIO_ASYNC', true),

    // SQLite database directory (auto-created by the install command)
    'sqlite_path' => storage_path('cache/hypercacheio'),
];

4. Environment Variables Reference

Variable	Description	Default
`CACHE_DRIVER`	Set to `hypercacheio` to use this driver	—
`HYPERCACHEIO_SERVER_ROLE`	`primary` or `secondary`	`primary`
`HYPERCACHEIO_PRIMARY_URL`	Full URL of the primary server's API	`http://127.0.0.1/api/hypercacheio`
`HYPERCACHEIO_SECONDARY_URLS`	Comma-separated secondary server URLs	(empty)
`HYPERCACHEIO_API_TOKEN`	Shared secret for inter-server auth	`changeme`
`HYPERCACHEIO_ASYNC`	Enable fire-and-forget replication	`true`

🔌 Connectivity Check

To verify that your server can communicate with the configured Primary/Secondary nodes, run the built-in connectivity check command:

php artisan hypercacheio:connectivity-check

This command performs a full suite of tests (Ping, Add, Get, Put, Delete, Lock) against the configured endpoints and reports the status of each operation.

🛠️ Usage

Use the standard Laravel Cache Facade. No new syntax to learn!

use Illuminate\Support\Facades\Cache;

// ✅ Store Data
// Automatically handles L1 memory + SQLite persistence + Primary sync
Cache::put('user_preference:1', ['theme' => 'dark'], 600);

// ✅ Retrieve Data
// Checks L1 memory first, then SQLite
$prefs = Cache::get('user_preference:1');

// ✅ Atomic Addition
// Only adds if key doesn't exist (concurrency safe)
Cache::add('job_lock:123', 'processing', 60);

// ✅ Atomic Locking
// Distributed locks work across all servers
$lock = Cache::lock('processing-job', 10);

if ($lock->get()) {
    // Critical section...
    
    $lock->release();
}

🔌 Internal API

The package exposes a lightweight internal API for node synchronization. Each endpoint is secured via X-Hypercacheio-Token.

Method	Endpoint	Description
`GET`	`/api/hypercacheio/cache/{key}`	Fetch a cached item
`POST`	`/api/hypercacheio/cache/{key}`	Upsert (Create/Update) an item
`POST`	`/api/hypercacheio/add/{key}`	Atomic "Add" operation
`DELETE`	`/api/hypercacheio/cache/{key}`	Remove an item
`POST`	`/api/hypercacheio/lock/{key}`	Acquire an atomic lock
`DELETE`	`/api/hypercacheio/lock/{key}`	Release an atomic lock

✅ Testing

You can run the full test suite (Unit & Integration) using Pest:

vendor/bin/pest laravel-hypercacheio/tests

📄 License

The MIT License (MIT). Please see License File for more information.

❤️ Credits

Developed with ❤️ by Indunil Peramuna

iperamuna / laravel-hypercacheio

Maintainers

Details