---

Chaperone

A powerful Laravel package that supervises and guards long-running queue jobs with health monitoring, circuit breaker protection, and intelligent recovery mechanisms. Ensures your background jobs complete successfully or recover gracefully from failures.

Requirements

Requires PHP 8.4+ and Laravel 11+

Installation

composer require cline/chaperone

Publish configuration and migrations:

php artisan vendor:publish --tag=chaperone-config
php artisan vendor:publish --tag=chaperone-migrations
php artisan migrate

Quick Start

Add the Supervised trait to any queue job and call heartbeat() to signal it's alive:

use Cline\Chaperone\Concerns\Supervised;
use Illuminate\Contracts\Queue\ShouldQueue;

class ImportUsers implements ShouldQueue
{
    use Supervised;

    public function handle(): void
    {
        $users = User::cursor();
        $total = User::count();

        foreach ($users as $index => $user) {
            $this->processUser($user);

            // Signal we're alive
            $this->heartbeat(['current_user' => $user->email]);

            // Report progress
            $this->reportProgress($index + 1, $total);
        }
    }
}

Monitor supervised jobs:

php artisan chaperone:monitor

Documentation

• Getting Started - Installation, configuration, and first supervised job
• Basic Supervision - Heartbeats, progress tracking, and health monitoring
• Circuit Breakers - Protect against cascading failures
• Resource Limits - Enforce memory, CPU, and disk limits
• Artisan Commands - CLI monitoring and management tools
• Configuration - Complete configuration reference

Key Features

• ✅ Health Monitoring - Track heartbeats and detect stuck/zombie jobs
• ✅ Circuit Breakers - Protect external services from cascading failures
• ✅ Resource Limits - Enforce memory, CPU, and disk usage constraints
• ✅ Progress Tracking - Monitor job completion with real-time progress
• ✅ Lifecycle Hooks - Callbacks for stuck, timeout, and resource violations
• ✅ Dead Letter Queue - Automatic handling of permanently failed jobs
• ✅ Observability - Integration with Laravel Pulse, Telescope, and Horizon
• ✅ Artisan Commands - Real-time monitoring dashboard and management tools
• ✅ Event System - Comprehensive events for custom monitoring and alerting

Change log

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

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please use the GitHub security reporting form rather than the issue queue.

Credits

• Brian Faust
• All Contributors

License

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