Download the PHP package alveby/laravel-queue-manager without Composer

Laravel Queue Manager

Cancel, delete, pause, reschedule and inspect Laravel queue jobs from code.

Laravel gives you no way to reach a job once it has been queued. This package does, for the Redis queue driver, through a small API and a set of Artisan commands. There is no UI — the assumption is that you are wiring cancellation into your own application flow.

Requirements

• PHP 8.2+ (8.3+ on Laravel 13)
• Laravel 12 or 13
• A queue connection using the redis driver

Laravel 10 and 11 are out of security support and Composer now refuses to install them, so they are not supported here.

Installation

The provider is auto-discovered. Publish the config if you want to change anything:

Cancelling jobs

cancel() does two things: it records the uuid as cancelled, and — if the job is still pending or delayed — removes it from Redis outright.

What happens depends on where the job was when you called it:

A running job cannot be interrupted from outside the process. Give long jobs a place to check in:

Each cancelled() call is one Redis round-trip, so poll per chunk, not per row. abortIfCancelled() is available too — it deletes the job and throws JobWasCancelled so you can unwind out of nested code.

How the worker drops a job

By default a JobProcessing listener deletes cancelled jobs before they run. Worker::process() checks $job->isDeleted() immediately after dispatching that event and returns without calling fire(), so this works for every kind of job — command bus jobs, queued listeners, queued closures and raw Queue::push('Class@method') payloads alike.

The tradeoff is that CallQueuedHandler never runs, so the bookkeeping it normally does is skipped:

• Batches are handled. The batch is told the job is accounted for, so the batch can still finish. Turn this off with cancellation.record_batch_progress if you would rather cancel the whole batch yourself with Bus::findBatch($id)->cancel().
• Chains are deliberately not handled. Cancelling a chained job cancels the rest of its chain.

If you want the framework's own skip path instead — where chains continue — set cancellation.strategy to middleware and add the middleware to the jobs you want cancellable:

The cancellation flag expires

Cancellation is a flag in Redis with a TTL (cancellation.ttl, 24h by default). A job delayed for longer than that will no longer see it. Raise the TTL if you schedule jobs far into the future.

Pausing queues

Pausing stops workers consuming a queue. Nothing is moved and nothing is lost — jobs keep piling up and start flowing again the moment you resume.

queue:work keeps running throughout; it just sees an empty queue. Pausing is per queue, so --queue=high,low with low paused keeps draining high.

Laravel pauses queues natively too (queue:pause, backed by the cache, read by the worker before it pops). Both flags are written and cleared together, so this package and the framework's own commands never disagree.

On top of that the package swaps the redis connector for a RedisQueue subclass whose pop() returns null while paused. That is the belt to the framework's braces: it keeps working when the cache store is unavailable, and when Queue::disablePolling() has switched the native check off. Set pause.enabled to false to leave the connector alone, or pause.native to false to stop writing the framework's flag.

Horizon subclasses RedisQueue, so the package detects it and extends Horizon's class instead of the framework's. No configuration needed.

Finding jobs

By uuid:

Without a queue hint this walks every queue of every managed connection, so pass one when you know it: QueueManager::find($uuid, 'export').

By tag, which is what the index is for:

Jobs declare their own tags:

class:, queue: and connection: tags are added automatically (index.auto_tags).

Without tags the query walks the real Redis structures instead, which is always accurate but O(n) in queue length:

Other operations

delete() differs from cancel(): it only takes the job out of Redis and leaves no flag, so a job that is already reserved will still run.

Commands

Schedule queue-manager:prune daily if you leave the index on.

Events

How it works

The package reads and edits the structures Illuminate\Queue\RedisQueue maintains:

Two details matter and are easy to get wrong by hand:

Match on uuid, not on score. Scores in the delayed and reserved sets are timestamps, and jobs routinely share one. The uuid lives in the payload and is stable across the whole lifecycle, including the cjson re-encode Redis performs when a job is reserved.

Keep the notify list in sync. Every push adds a token to :notify and every pop removes one. An LREM on the queue list without a matching LPOP on the notify list leaves the two permanently out of step and wakes workers for jobs that are not there. Every removal here does both in one Lua script.

Its own keys, all under the configured prefix:

A job leaves the tag sets and lqm:jobs as soon as it reaches a terminal state, so those stay proportional to in-flight work rather than to total throughput.

Limitations

• Redis only. The API is behind contracts (JobRepository, PauseStore, CancellationStore, JobIndex) so other drivers can be added, but only Redis is implemented. Cancellation itself is driver-agnostic — it hangs off the JobProcessing event — but finding and deleting jobs is not.
• A running job cannot be killed, only asked to stop. Use Cancellable.
• Deleting a reserved job does not stop a worker that is executing it. It only removes the reservation, meaning nothing will retry that job if the worker dies.
• Lookups without a queue hint are O(n) across every queue. Pass a queue, or use tags.
• The index only knows jobs queued since installation, and only until they finish. Scanning is always the source of truth.
• Encrypted payloads (ShouldBeEncrypted) hide the batch id, so batch progress is not recorded when such a job is cancelled.

Testing

Feature tests need a Redis they are allowed to FLUSHDB:

Tests skip themselves when nothing answers on that port — a run reporting 40-odd skips means Redis was unreachable, not that everything passed. Override with REDIS_HOST, REDIS_PORT, REDIS_PASSWORD and REDIS_QUEUE_DB, and switch clients with REDIS_CLIENT=phpredis. CI runs both clients, because they disagree about key prefixing, variadic arguments and SCAN.

Contributing

See CONTRIBUTING.md. Security issues go through SECURITY.md, not the issue tracker.

License

MIT. See LICENSE.md.