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.
🏘️ Sharded Architecture: Native 32-shard memory mapping to eliminate lock contention on multi-core systems.
⚡ Async Persistence: High-speed background persistence worker for non-blocking writes.
🧠 L1 In-Memory Cache: Ephemeral memory caching for instant access during the request lifecycle.
🐹 Go Server: High-performance Go-based binary for ultra-low latency and distributed synchronization.
🔄 Active-Active HA Mode: Fully synchronized multi-node clusters using binary TCP replication.
🛡️ Service Management: Built-in support for running as a systemd (Linux) or launchd (macOS) service.
🔒 Distributed Locking: Full support for atomic locks across multiple servers.
✅ Modern Compatibility: Fully supports Laravel 10.x, 11.x, and 12.0.

📦 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('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`
`HYPERCACHEIO_SERVER_TYPE`	`laravel` (default) or `go`	`laravel`
`HYPERCACHEIO_GO_DIRECT_SQLITE`	Execute SQLite queries directly in Go	`true`
`HYPERCACHEIO_GO_HOST`	External/advertised IP of the Go server (used by secondaries)	`127.0.0.1`
`HYPERCACHEIO_GO_LISTEN_HOST`	IP the Go daemon binds to. Use `0.0.0.0` to listen on all interfaces	`0.0.0.0`
`HYPERCACHEIO_GO_PORT`	Port the Go server listens on	`8080`
`HYPERCACHEIO_HA_ENABLED`	Enable Active-Active HA Mode	`true`
`HYPERCACHEIO_PEER_ADDRS`	Comma-separated replication peers (IP:Port)	(empty)
`HYPERCACHEIO_REPL_PORT`	Port for inter-node binary replication	`7400`

1. High Performance Architecture (v1.7.0)

The Go server is now architected for Redis-like performance using:

Sharded Mutexes: 32 cache shards to eliminate lock contention on modern multi-core CPUs.
Async Persistence: Writes to the SQLite database happen in the background, allowing the HTTP API to respond in sub-microsecond time.
WAL-Optimized SQLite: Built-in support for WAL mode and synchronous=NORMAL.

📊 Internal Benchmarks (M1 Pro)

Metric	Performance
Parallel GET	22,000,000+ ops/s
Parallel SET	7,500,000+ ops/s
P95 Latency	~250 nanoseconds
TCP Replication	95,000+ frames/s

2. Enable Go Server

Update your .env:

HYPERCACHEIO_SERVER_TYPE=go
HYPERCACHEIO_GO_DIRECT_SQLITE=true

# External IP that secondary servers use to reach this node
HYPERCACHEIO_GO_HOST=10.80.3.131
HYPERCACHEIO_GO_PORT=8185

# IP the daemon binds to — 0.0.0.0 (default) listens on all interfaces.
HYPERCACHEIO_GO_LISTEN_HOST=0.0.0.0

2. Active-Active HA Mode (TCP Replication)

As of version 1.6.0, Hyper-Cache-IO supports a robust Active-Active HA architecture. Multiple application servers can each run their own local Go cache node, with all nodes synchronizing state in real-time over a dedicated binary TCP protocol.

Full-Mesh Replication: Every write on one node is instantly broadcast to all configured peers.
Bootstrap Sync: When a new node joins the cluster, it automatically requests a full state dump from existing peers.
Zero-Wait Primary: No more bottlenecking on a single "Primary" URL. Your app talks to its local node, and replication happens in the background.

To enable HA Mode, configure your peers in .env:

HYPERCACHEIO_HA_ENABLED=true
HYPERCACHEIO_REPL_PORT=7400

# Comma-separated list of peer IP:REPL_PORT addresses
HYPERCACHEIO_PEER_ADDRS=10.0.0.2:7400,10.0.0.3:7400

The hypercacheio:go-server command will automatically configure the Go binary to use your application's absolute database path (config('hypercacheio.sqlite_path')) and cache prefix (config('cache.prefix')).

2. Compile & Start

The package includes a full management CLI for the Go daemon:

# 🛠️ Compile the binary for your system (detects macOS/Linux, all architectures)
php artisan hypercacheio:go-server compile

# 🚀 Start the server as a background process
php artisan hypercacheio:go-server start

# 📊 Check daemon status (PID / systemd / launchd / process scan)
php artisan hypercacheio:go-server status

# 🔄 Restart the daemon (Artisan managed)
php artisan hypercacheio:go-server restart

# 🛑 Stop the daemon
php artisan hypercacheio:go-server stop

3. Run as a System Service

Generate service configuration files for your OS, then install and manage them via Artisan:

# Step 1: Generate the service file (systemd for Linux, launchd for macOS)
php artisan hypercacheio:go-server make-service

# Step 2: Install the service (one-time manual step per OS):
# Linux:  sudo cp hypercacheio-server.service /etc/systemd/system/
# macOS:  cp iperamuna.hypercacheio.server.plist ~/Library/LaunchAgents/

# Step 3: Manage via Artisan
php artisan hypercacheio:go-server service:start   # Load and start the service
php artisan hypercacheio:go-server service:restart # Cycle the service
php artisan hypercacheio:go-server service:stop    # Stop the service
php artisan hypercacheio:go-server service:status  # View service status (systemd/launchd output)
php artisan hypercacheio:go-server service:remove  # Disable and remove the service

🔌 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:

Identifies server type (LARAVEL or GO) with host and port
Pings the local node first via 127.0.0.1 (falls back to configured host)
Tests Ping, Add, Get, Put, Delete, Lock against all configured endpoints
Reports OS-specific firewall advice (ufw, firewalld, socketfilterfw) when a connection fails

🛠️ 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

Package info

Statistics

Security