README

← Back to NixPHP

nixphp/queue

Minimalistic queueing for NixPHP – file-based, simple, and extendable.

This plugin provides a lightweight job queue system with CLI worker support and no external dependencies by default.

🧩 Part of the official NixPHP plugin collection. Use it when you want to delay tasks, run background jobs, or decouple logic – without setting up Redis or RabbitMQ.

📦 Features

• ✅ File-based queue driver (no DB or Redis required)
• ✅ CLI worker for background processing
• ✅ One-off async execution (pushAndRun())
• ✅ Deadletter handling and retry support
• ✅ Fully PSR-4 and event-loop friendly
• ✅ Extendable: write your own driver for SQLite, Redis, etc.

📥 Installation

composer require nixphp/queue

That’s it. The plugin will be autoloaded automatically.

🚀 Usage

➕ Queue a job

Create a job class that implements the QueueJobInterface:

use NixPHP\Queue\QueueJobInterface;

class SendWelcomeEmail implements QueueJobInterface
{
    public function __construct(protected array $payload) {}

    public function handle(): void
    {
        // Send your email here
    }
}

Push it to the queue:

queue()->push(SendWelcomeEmail::class, ['email' => 'user@example.com']);

⚡ Fire-and-forget (async)

For one-off asynchronous execution, use:

queue()->pushAndRun(SendWelcomeEmail::class, ['email' => 'user@example.com']);

This queues the job and immediately runs it in the background via a short-lived CLI process.

Great for use cases like emails, logging, or notifications - without blocking the current request.

🧵 Start the worker

Run the CLI worker to process jobs continuously:

./bin/nix queue:worker

Run a single job only:

./bin/nix queue:worker --once

🔹 --once is also used internally by pushAndRun() for async dispatching.

💥 Deadletter & Retry

Failed jobs are automatically written to the deadletter folder (only for FileDriver).

You can retry failed jobs via:

./bin/nix queue:retry-failed

By default, retried jobs are removed from the deadletter queue. Use --keep to retain them:

./bin/nix queue:retry-failed --keep

🧠 Drivers

The queue system is driver-based. Included drivers:

To change the driver, register it manually:

use NixPHP\Queue\Queue;
use NixPHP\Queue\Drivers\FileQueue;

app()->set('queue', fn() => new Queue(
    new FileQueue(__DIR__ . '/storage/queue', __DIR__ . '/storage/queue/deadletter')
));

📁 The file path is only relevant for FileDriver.

🛠️ Supervisor example (optional)

To run the worker persistently in production, use Supervisor:

[program:nixphp-worker]
command=php bin/nix queue:worker
directory=/path/to/your/app
autostart=true
autorestart=true
stderr_logfile=/var/log/nixphp/worker.err.log
stdout_logfile=/var/log/nixphp/worker.out.log

✅ Requirements

• nixphp/framework >= 1.0
• nixphp/cli (required for worker commands)

📄 License

MIT License.