Download the PHP package mvpopuk/laravel-enhanced-failed-jobs without Composer

Queuewatch Laravel

Enhanced CLI

Installation

Basic Commands

Filtering Options

JSON Output Format

Queuewatch.io (Optional)

Official Laravel package for Queuewatch - Real-time queue failure monitoring with instant notifications.

• Real-time Failure Reporting - Automatically capture and report queue job failures to your Queuewatch dashboard
• Rich Exception Data - Full stack traces, job payloads, and server context
• Smart Filtering - Ignore specific jobs, queues, or exception types
• Remote Retry - Retry failed jobs directly from the Queuewatch dashboard
• Instant Notifications - Get notified via Slack, Discord, email, or webhooks when jobs fail

Requirements

• PHP 8.1+
• Laravel 10.x, 11.x, 12.x, or 13.x
• A Queuewatch account

Installation

Add your API key to .env:

That's it! The package automatically hooks into Laravel's queue system and starts reporting failures.

Getting Your API Key

1. Sign up at queuewatch.io
2. Create a new project in your dashboard
3. Copy the API key from Settings → API Keys
4. Add it to your .env file

Configuration

Publish the config file for advanced customization:

Available Options

Environment Variables

Testing Your Integration

This verifies your API key and connection. Add --send-test to send a test failure:

You should see the test failure appear in your Queuewatch dashboard within seconds.

What Gets Reported

When a job fails, Queuewatch captures:

• Job Details - Class name, queue, connection, attempts, max tries
• Exception - Message, class, file, line, full stack trace
• Payload - Complete job payload (can be disabled for sensitive data)
• Context - Server hostname, PHP version, Laravel version, timestamp
• Environment - Your configured environment label

Remote Retry

Enable remote retry to retry failed jobs directly from the Queuewatch dashboard:

Configure allowed queues for security:

When enabled, you can click "Retry" on any failed job in your Queuewatch dashboard, and it will be re-dispatched to your Laravel application.

Worker Monitoring

Report queue worker lifecycle (start, heartbeat, stop) to Queuewatch so you can see which workers are running, when they last checked in, and why they stopped. This is opt-in: it is disabled by default, so upgrading this package introduces no new behaviour until you turn it on.

Requires Laravel 12.20 or newer. Illuminate\Queue\Events\WorkerStarting — the event this feature relies on to detect a worker starting up — was not introduced until Laravel 12.20. On Laravel 10.x, 11.x, and 12.0-12.19, enabling worker monitoring reports nothing at all: no run is ever created, so every other lifecycle handler stays inert. A warning is logged when the application boots if you enable worker monitoring on an unsupported version.

Both variables are required — worker monitoring stays off if either QUEUEWATCH_WORKERS_ENABLED is false or QUEUEWATCH_API_KEY is empty. You can also tune how often a running worker reports in:

Scheduler

Heartbeats are buffered locally by the worker process and flushed to Queuewatch by a scheduled command, so your app's scheduler must be running:

The package registers queuewatch:workers:flush to run everyMinute() for you — you don't need to add it to your own schedule.

Cache store

The heartbeat buffer is written by the worker process and read by the scheduled flush command, so it needs a cache store that is shared and persists between processes — Redis, Memcached, DynamoDB, or a database store all work. The array and null drivers do not survive between processes and will silently lose every heartbeat; if your default cache store can't be used for this, set a dedicated one:

If the configured store can't survive between processes, a warning is logged when the application boots.

Stop reasons

Worker start, heartbeat, and stop reporting all share the same Laravel 12.20+ floor described above — this is narrower than the ^10–^13 range this package otherwise supports. Structured stop reasons (why a worker stopped — --max-jobs, --memory, a restart signal, etc.) also work from that same 12.20 floor, since WorkerStopReason and WorkerStopping::$reason were both backported to Laravel 12.x. What actually requires Laravel 13.30+ is the richer WorkerStopping payload added in that release — jobsProcessed, memoryUsage, and lastJobProcessedAt. Between 12.20 and 13.30, a stop is still reported with its reason; jobs processed falls back to this package's own in-process count, and memory usage / last-job-processed-at are simply omitted.

Notifications

Configure notifications in your Queuewatch dashboard:

• Slack - Get alerts in your team's Slack channel
• Discord - Send notifications to Discord webhooks
• Email - Receive email alerts for failures
• Webhooks - Integrate with any service via custom webhooks

Set up notification rules to filter by environment, job type, or failure frequency.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Marian Pop
• All Contributors

License

The MIT License (MIT). Please see License File for more information.