PHPackages iperamuna/laravel-hypercacheio - 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. [Database & ORM](/categories/database) 4. / 5. iperamuna/laravel-hypercacheio ActiveLibrary[Database & ORM](/categories/database) iperamuna/laravel-hypercacheio ============================== High-performance distributed Laravel cache driver using SQLite & HTTP. v1.7.0(1mo ago)024MITPHPPHP ^8.2CI passing Since Feb 16Pushed 1mo agoCompare [ Source](https://github.com/iperamuna/laravel-hypercacheio)[ Packagist](https://packagist.org/packages/iperamuna/laravel-hypercacheio)[ RSS](/packages/iperamuna-laravel-hypercacheio/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (16)Versions (31)Used By (0) Laravel Hyper-Cache-IO ====================== [](#laravel-hyper-cache-io) [![Latest Version on Packagist](https://camo.githubusercontent.com/bdadd237f302aca6f4012172bd81a199163fef15fe8a979f586af60e73e2aecb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f69706572616d756e612f6c61726176656c2d68797065726361636865696f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/iperamuna/laravel-hypercacheio)[![Total Downloads](https://camo.githubusercontent.com/c72dcebcf9132f031e8d0bbcd73d345a73344b3fc57eeaee26de9ebb55678070/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f69706572616d756e612f6c61726176656c2d68797065726361636865696f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/iperamuna/laravel-hypercacheio)[![License](https://camo.githubusercontent.com/4ca9af74e5c59b311ae8728c9908506961a178481803784f2a76b3ac242cc964/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f69706572616d756e612f6c61726176656c2d68797065726361636865696f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/iperamuna/laravel-hypercacheio) **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 ---------- [](#-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 -------------- [](#-installation) Install the package via Composer: ``` composer require iperamuna/laravel-hypercacheio ``` Run the installation command to configure the package: ``` php artisan hypercacheio:install ``` --- βš™οΈ Configuration ---------------- [](#️-configuration) ### 1. Set the Cache Driver [](#1-set-the-cache-driver) Update your `.env` file to use `hypercacheio`: ``` CACHE_DRIVER=hypercacheio ``` ### 2. Configure Server Roles [](#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) [](#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-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 [](#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 [](#4-environment-variables-reference) VariableDescriptionDefault`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) [](#1-high-performance-architecture-v170) 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) [](#-internal-benchmarks-m1-pro) MetricPerformance**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 [](#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) [](#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 [](#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 [](#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 -------------------- [](#-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 -------- [](#️-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 -------------- [](#-internal-api) The package exposes a lightweight internal API for node synchronization. Each endpoint is secured via `X-Hypercacheio-Token`. MethodEndpointDescription`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 --------- [](#-testing) You can run the full test suite (Unit & Integration) using Pest: ``` vendor/bin/pest laravel-hypercacheio/tests ``` --- πŸ“„ License --------- [](#-license) The MIT License (MIT). Please see [License File](LICENSE) for more information. --- ❀️ Credits ---------- [](#️-credits) - Developed with ❀️ by [Indunil Peramuna](https://iperamuna.online) ### Health Score 44 β€” FairBetter than 91% of packages Maintenance97 Actively maintained with recent releases Popularity7 Limited adoption so far Community6 Small or concentrated contributor base Maturity57 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Recently: every ~6 days Total 29 Last Release 46d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/e7f282b7449477d5baaf64bdb40fcb7d9c8c638fb96a431413c7293344e3182f?d=identicon)[iperamuna](/maintainers/iperamuna) --- Top Contributors [![iperamuna](https://avatars.githubusercontent.com/u/3013395?v=4)](https://github.com/iperamuna "iperamuna (63 commits)") --- Tags laravelperformancesqlitecachedistributed ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/iperamuna-laravel-hypercacheio/health.svg) ``` [![Health](https://phpackages.com/badges/iperamuna-laravel-hypercacheio/health.svg)](https://phpackages.com/packages/iperamuna-laravel-hypercacheio) ``` ### Alternatives [spatie/laravel-responsecache Speed up a Laravel application by caching the entire response 2.8k8.2M50](/packages/spatie-laravel-responsecache)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9682.1M97](/packages/roots-acorn)[laravel-zero/framework The Laravel Zero Framework. 3371.4M368](/packages/laravel-zero-framework)[ymigval/laravel-model-cache Laravel package for caching Eloquent model queries 7642.2k3](/packages/ymigval-laravel-model-cache)[dgtlss/warden A Laravel package that proactively monitors your dependencies for security vulnerabilities by running automated composer audits and sending notifications via webhooks and email 8745.6k](/packages/dgtlss-warden)[ytake/laravel-couchbase Couchbase providers for Laravel 3051.9k](/packages/ytake-laravel-couchbase) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)