Supervisor Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require yzalis/supervisor
   

   Register the service provider in config/app.php under providers:

   Yzalis\Supervisor\SupervisorServiceProvider::class,
   

2. Publish Configuration

   php artisan vendor:publish --provider="Yzalis\Supervisor\SupervisorServiceProvider" --tag="supervisor-config"
   

   This generates config/supervisor.php with default settings.

3. First Use Case: Check Supervisor Status

   use Yzalis\Supervisor\Facades\Supervisor;
   
   // Check if Supervisor is running
   if (Supervisor::isRunning()) {
       echo "Supervisor is active!";
   }
   

4. Basic Configuration Edit config/supervisor.php to define your Supervisor socket path (default: /var/run/supervisord.sock).

Implementation Patterns

Common Workflows

1. Programmatic Process Management

• Start/Stop Processes

  Supervisor::startProcess('queue-worker');
  Supervisor::stopProcess('queue-worker');
  

• Reload Supervisor Config

  Supervisor::reloadConfig();
  

2. Process Monitoring

• List All Processes

  $processes = Supervisor::listProcesses();
  foreach ($processes as $process) {
      echo $process->name . ' (Status: ' . $process->status . ')' . PHP_EOL;
  }
  

• Check Process Status

  $status = Supervisor::getProcessStatus('queue-worker');
  if ($status === 'RUNNING') {
      // Handle accordingly
  }
  

3. Dynamic Configuration Updates

• Add/Update a Process via Code

  Supervisor::addProcess([
      'name' => 'custom-worker',
      'command' => 'php artisan queue:work --queue=custom',
      'autostart' => true,
      'autorestart' => true,
  ]);
  Supervisor::updateConfig();
  

4. Integration with Artisan Commands

use Illuminate\Console\Command;
use Yzalis\Supervisor\Facades\Supervisor;

class SupervisorCommand extends Command
{
    protected $signature = 'supervisor:restart {process}';
    protected $description = 'Restart a Supervisor process';

    public function handle()
    {
        $process = $this->argument('process');
        Supervisor::stopProcess($process);
        Supervisor::startProcess($process);
        $this->info("Restarted {$process}");
    }
}

5. Event-Driven Notifications

• Use Laravel's event system to trigger actions when processes fail:

  Supervisor::onProcessFailure(function ($process) {
      // Send Slack/Email alert
      \Log::error("Process {$process->name} failed!");
  });
  

Integration Tips

• Environment-Specific Configs Use Laravel's config('supervisor.socket_path') to dynamically set the socket path based on the environment (e.g., Docker vs. production).

• Laravel Scheduler Integration Combine with schedule:run to manage Supervisor processes alongside Laravel tasks:

  // In app/Console/Kernel.php
  protected function schedule(Schedule $schedule)
  {
      $schedule->command('supervisor:restart queue-worker')->daily();
  }
  

• Logging Redirect Supervisor logs to Laravel's logging system for centralized monitoring:

  Supervisor::setLogger(function ($message) {
      \Log::info('[Supervisor] ' . $message);
  });
  

Gotchas and Tips

Pitfalls

1. Socket Permissions

   • Ensure the PHP process (e.g., Laravel queue worker) has read/write access to the Supervisor socket (e.g., /var/run/supervisord.sock).
   • Fix: Adjust socket permissions or run PHP with the same user as Supervisor:

     chmod 777 /var/run/supervisord.sock  # Temporary fix (not recommended for production)
     

     Or configure Supervisor to use a Unix socket with proper permissions.

2. Config Reload Race Conditions

   • Calling Supervisor::updateConfig() while Supervisor is still processing a previous reload may cause errors.
   • Fix: Add a small delay or check the status before updating:

     if (Supervisor::isConfigReloading()) {
         sleep(1); // Wait briefly
     }
     Supervisor::updateConfig();
     

3. Process Naming Conflicts

   • Supervisor process names must be unique. Reusing names without proper cleanup can lead to duplicate entries.
   • Fix: Use descriptive names (e.g., app-queue-worker) and clean up old processes before updates.

4. Timeouts

   • Supervisor RPC calls may time out if the socket is unresponsive (e.g., Supervisor crashed).
   • Fix: Implement retry logic:

     try {
         Supervisor::stopProcess('queue-worker');
     } catch (\Yzalis\Supervisor\Exceptions\SupervisorException $e) {
         if (strpos($e->getMessage(), 'timeout') !== false) {
             // Retry or notify admin
         }
     }
     

Debugging Tips

1. Enable Supervisor Logging Add to supervisord.conf:

   [supervisord]
   logfile=/var/log/supervisor/supervisord.log
   logfile_maxbytes=1MB
   logfile_backups=1
   

2. Check RPC Errors Wrap calls in try-catch to log RPC-specific errors:

   try {
       Supervisor::startProcess('test');
   } catch (\Yzalis\Supervisor\Exceptions\RPCException $e) {
       \Log::error('Supervisor RPC Error: ' . $e->getMessage());
   }
   

3. Verify Process Definitions Use Supervisor::getAllProcessInfo() to debug process definitions before updates:

   $info = Supervisor::getAllProcessInfo();
   dd($info); // Inspect structure
   

Extension Points

1. Custom Process Factories Extend the package to support custom process definitions:

   Supervisor::extendProcessFactory(function ($name, $config) {
       if ($name === 'laravel-telescope') {
           $config['command'] = 'php artisan telescope:prune --hours=24';
       }
       return $config;
   });
   

2. Webhook Integration Trigger external actions (e.g., webhooks) on process state changes:

   Supervisor::onProcessStateChange(function ($process, $oldStatus, $newStatus) {
       if ($newStatus === 'STOPPED') {
           Http::post('https://your-webhook.url/alert', [
               'process' => $process->name,
               'status'  => $newStatus,
           ]);
       }
   });
   

3. Database-Backed Config Store Supervisor processes in a Laravel migration/table for version control:

   // Example migration
   Schema::create('supervisor_processes', function (Blueprint $table) {
       $table->id();
       $table->string('name')->unique();
       $table->json('config');
       $table->timestamps();
   });
   

   Then sync with Supervisor::updateConfig() after DB changes.

4. Docker Support For Dockerized environments, mount the Supervisor socket and configure Laravel to use the container's socket path:

   # docker-compose.yml
   services:
     supervisor:
       image: supervisor
       volumes:
         - ./supervisord.conf:/etc/supervisor/conf.d/supervisord.conf
         - /var/run/supervisord.sock:/var/run/supervisord.sock
   

   Update config/supervisor.php:

   'socket_path' => '/var/run/supervisord.sock',