Laravel Spool

Batch and defer expensive database writes in Laravel — no Redis, no queues, no background workers required.
Works on shared hosting. Drop 1,000 individual DB inserts down to a single batch operation.

The Problem

Every time a user visits a page, triggers an event, or hits your API, your Laravel app likely writes to the database. Once. Per event. Every time.

Under normal traffic that's fine. Under load it becomes a bottleneck: lock contention, slow response times, and a database that can't keep up.

The standard fix — Laravel queues, Redis, Horizon, Supervisor — adds real infrastructure complexity. And if you're on shared hosting, those options simply aren't available.

The Solution

Laravel Spool captures high-frequency writes to a fast local buffer first, then processes them as a single batch on a schedule you control.

• 1,000 individual inserts → 1 batch insert
• No Redis required — the filesystem driver works anywhere PHP runs
• No background workers — flush runs as a scheduled Laravel task
• No configuration overhead — one install command and you're buffering

It's a lightweight performance layer that fits between your application events and your database.

Key Features

Use Cases

• Page view / analytics tracking — buffer every hit, insert hourly in bulk
• Activity logs — accumulate user actions, write in batches instead of per-action
• API usage metering — count calls without a DB write on every request
• Bulk form submissions — queue submissions to a buffer, process on a schedule
• Shared hosting optimization — get performance gains without Redis or queue workers

Quick Start

1. Install

Laravel auto-discovers the service provider. No manual registration needed.

2. Set Up

This publishes config/spool.php and creates the buffer directories under storage/app/private/buffer/.

3. Buffer Data

4. Flush in Batches

In routes/console.php, schedule a flush:

That's it. Your app now buffers writes and processes them in batches.

How It Works

Filesystem Driver (Default)

Every call to Buffer::buffer() serializes the payload and appends it to a shard file. Writes are distributed across up to max_shards files using a hash, which reduces file-level lock contention when multiple requests write simultaneously.

When flush() runs:

1. Shard files in active/ are atomically renamed to processing/ — this is a single OS-level rename, so two concurrent flush jobs can never pick up the same shard.
2. Your callback receives each shard file path. You read the lines, process them however you need, and return true.
3. Processed shards move to completed/ and are held for shards_ttl_days days before clean() removes them.

Redis Streams Driver (Optional)

When Redis is available, set SPOOL_BUFFER_DRIVER=redis. The package writes to a Redis Stream via XADD. A long-running consumer process reads batches from the stream and fires a RedisBufferConsumeEvent that your application handles.

Why Not Just Use Laravel Queues?

Use Spool when you need to batch many similar writes (analytics, logs, counters) and want zero extra infrastructure.

Use Laravel queues when you need per-job async processing, retries, failed job handling, or complex background workflows.

They are not mutually exclusive — many apps use both.

Performance Impact

Without Spool — direct writes on every event:

With Spool — buffered and batched:

The write cost moves off your HTTP response cycle entirely.

Shared Hosting Advantage

Most Laravel performance packages assume you have Redis, a queue worker, and Supervisor. On shared hosting, you have none of those.

Laravel Spool's filesystem driver removes those requirements entirely:

• No Redis — buffers to local disk files
• No background workers — flushing runs via Laravel's scheduler (a single cron entry)
• No Supervisor — nothing to keep alive
• No extra dependencies — just PHP and a writable filesystem

The only thing required is the standard Laravel scheduler cron entry in your cPanel or server cron:

That's standard Laravel. If your app already runs on shared hosting, Spool works immediately.

Configuration

Published to config/spool.php after running spool:install.

Health Check

Before deploying, verify your setup:

This checks that buffer directories exist and are writable, and that all config values are valid.

The command exits with code 0 on success and 1 on failure — safe to use in deployment pipelines and Docker health checks.

Redis Driver Setup (Optional)

If your infrastructure supports Redis and you want lower write latency:

1. Install predis if not using the phpredis extension:

2. Set the driver:

3. Start the consumer (manage with Supervisor in production):

4. Listen for batched events in your application:

Requirements

• PHP 8.2+
• Laravel 12.x
• Redis driver: phpredis extension or predis/predis

Roadmap

• [ ] Dashboard UI for monitoring buffer state
• [ ] Artisan command to manually trigger a flush
• [ ] Laravel 11.x support
• [ ] Benchmarks and performance comparison guide

Contributing

Pull requests are welcome. For significant changes, open an issue first to discuss what you'd like to change.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes
4. Open a pull request

License

Laravel Spool is open-source software released under the MIT license.