Supervisor Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require supervisorphp/supervisor
   

   Add the package to your composer.json and run composer install.

2. First Connection

   use Supervisor\Client;
   
   $client = new Client('unix:///var/run/supervisord.sock');
   $processes = $client->getAllProcessInfo();
   

   • Replace the socket path with your Supervisor’s actual socket (common locations: /var/run/supervisord.sock or tcp://127.0.0.1:9001).
   • Test connectivity by calling getAllProcessInfo()—if it returns an array, the connection works.

3. First Use Case: Restart a Process

   $client->restartProcess('your_process_name');
   

   • Useful for CI/CD pipelines or post-deployment hooks to ensure processes are fresh.

Implementation Patterns

Common Workflows

1. Process Management

   • Start/Stop/Restart:

     $client->startProcess('worker:queue');
     $client->stopProcess('worker:queue');
     $client->restartProcess('worker:queue');
     

   • Graceful Shutdown: Use stopProcess() with a timeout to avoid abrupt kills.
   • Batch Operations: Loop through getAllProcessInfo() to manage multiple processes dynamically.

2. Monitoring and Logging

   • Check Process Status:

     $status = $client->getProcessInfo('api:server');
     if ($status['statename'] !== 'RUNNING') {
         // Trigger alert or retry logic
     }
     

   • Tail Logs (via external tools like tail or logrotate hooks) and correlate with Supervisor events.

3. Event-Driven Actions

   • Post-Deploy Hooks:

     // In deploy script (e.g., Laravel Forge/Envoyer)
     $client = new Client('unix:///path/to/sock');
     $client->restartProcess('app:queue');
     

   • Health Checks: Integrate with Laravel’s Artisan::command() to validate process states.

4. Configuration Validation

   • Verify Supervisor Config:

     $client->reloadConfig(); // Reload after config changes
     $errors = $client->getAllProcessInfo(); // Check for 'exitstatus' !== 0
     

Integration Tips

• Laravel Artisan Commands:

  namespace App\Console\Commands;
  
  use Supervisor\Client;
  use Illuminate\Console\Command;
  
  class RestartSupervisorProcess extends Command
  {
      protected $signature = 'supervisor:restart {process}';
      public function handle(Client $client)
      {
          $client->restartProcess($this->argument('process'));
          $this->info("Restarted {$this->argument('process')}");
      }
  }
  

  • Register in app/Console/Kernel.php:

    protected $commands = [
        Commands\RestartSupervisorProcess::class,
    ];
    

• Service Providers: Bind the Client to the container for dependency injection:

  $this->app->singleton(Client::class, function () {
      return new Client(config('supervisor.socket'));
  });
  

• Environment Awareness: Use .env for socket paths:

  SUPERVISOR_SOCKET=unix:///var/run/supervisord.sock
  

  Then inject via config or service provider.

Gotchas and Tips

Pitfalls

1. Socket Permissions

   • Issue: Connection refused or Permission denied when connecting to Unix sockets.
   • Fix:
     • Ensure the PHP process (e.g., Laravel worker) has read/write access to the socket:

       chmod 666 /var/run/supervisord.sock
       

     • Or adjust Supervisor’s unix_http_server config to specify a user/group:

       [unix_http_server]
       file=/var/run/supervisord.sock
       user=www-data
       group=www-data
       

2. XML-RPC Limitations

   • Issue: Complex data structures (e.g., nested arrays) may not serialize correctly.
   • Fix: Flatten data or use JSON-RPC alternatives if available.

3. Process Name Mismatches

   • Issue: restartProcess() fails if the process name doesn’t match Supervisor’s config exactly (including case sensitivity).
   • Fix: Verify names with getAllProcessInfo() and use the exact string.

4. Race Conditions

   • Issue: Restarting a process mid-operation (e.g., during a database transaction) can cause corruption.
   • Fix: Implement health checks or use stopProcess() + startProcess() with delays.

5. Deprecated Methods

   • Issue: Older versions of the package may use deprecated Supervisor XML-RPC methods.
   • Fix: Check the Supervisor XML-RPC docs and update calls accordingly.

Debugging Tips

• Enable Supervisor Logging: Add to supervisord.conf:

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

  Tail logs during issues:

  tail -f /var/log/supervisor/supervisord.log
  

• Test Locally: Use a local Supervisor instance (e.g., via Docker) to test interactions before deploying.

• Error Handling: Wrap calls in try-catch:

  try {
      $client->restartProcess('process');
  } catch (\Supervisor\Exception\SupervisorException $e) {
      Log::error("Supervisor error: " . $e->getMessage());
  }
  

Extension Points

1. Custom Commands Extend the Client class to add domain-specific methods:

   class CustomSupervisorClient extends Client
   {
       public function restartQueueWorkers()
       {
           $this->restartProcess('queue:worker-1');
           $this->restartProcess('queue:worker-2');
       }
   }
   

2. Event Listeners Hook into Laravel events (e.g., deployed) to trigger Supervisor actions:

   public function handle()
   {
       $client = app(Client::class);
       $client->restartProcess('app:horizon');
   }
   

3. Monitoring Dashboard Build a Laravel route to display process statuses:

   Route::get('/supervisor/status', function () {
       $client = new Client(config('supervisor.socket'));
       return view('supervisor.status', ['processes' => $client->getAllProcessInfo()]);
   });
   

4. Configuration Reload Hooks Automate config reloads post-change:

   $client->reloadConfig();
   sleep(2); // Wait for reload
   $client->restartProcess('*'); // Restart all processes