Supervisor Client Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require mondalaci/supervisor-client
   

   (Note: Consider migrating to SupervisorPHP as this package is deprecated.)

2. Basic Connection For Unix socket (default Supervisor config):

   $supervisor = new \SupervisorClient\SupervisorClient('unix:///var/run/supervisor.sock');
   

   For TCP/IP:

   $supervisor = new \SupervisorClient\SupervisorClient('your-server.com', 9001);
   

3. First Use Case: List All Processes

   $processes = $supervisor->supervisor.getAllProcessInfo();
   dd($processes);
   

Where to Look First

• Supervisor XML-RPC API Docs – Understand available methods.
• SupervisorClient class – Review constructor and methods like setAuth(), setTimeout().
• Example in tests/ – Practical usage patterns for common tasks (e.g., starting/stopping processes).

Implementation Patterns

Core Workflows

1. Process Management

• Start/Stop/Restart:

  $supervisor->supervisor.startProcess('your_process_name');
  $supervisor->supervisor.stopProcess('your_process_name');
  $supervisor->supervisor.restartProcess('your_process_name');
  

• Reload Config:

  $supervisor->supervisor.reloadConfig();
  

2. Monitoring

• Check Process Status:

  $status = $supervisor->supervisor.getProcessInfo('your_process_name');
  

• List All Processes:

  $allProcesses = $supervisor->supervisor.getAllProcessInfo();
  

3. Event Handling (via supervisor.read)

• Subscribe to events (e.g., process state changes):

  $events = $supervisor->supervisor.read(1000); // Timeout in ms
  

4. Authentication & Timeouts

• Secure connections:

  $supervisor->setAuth('admin', 'securepassword');
  $supervisor->setTimeout(5000); // 5 seconds
  

Integration Tips

Laravel-Specific Patterns

1. Service Provider Binding Bind the client in AppServiceProvider for dependency injection:

   public function register()
   {
       $this->app->singleton('supervisor', function ($app) {
           $supervisor = new \SupervisorClient\SupervisorClient('unix:///var/run/supervisor.sock');
           $supervisor->setAuth(config('supervisor.username'), config('supervisor.password'));
           return $supervisor;
       });
   }
   

2. Artisan Commands Create custom commands for CLI process management:

   use Illuminate\Console\Command;
   use SupervisorClient\SupervisorClient;
   
   class SupervisorCommand extends Command
   {
       protected $supervisor;
   
       public function __construct(SupervisorClient $supervisor)
       {
           parent::__construct();
           $this->supervisor = $supervisor;
       }
   
       public function handle()
       {
           $this->info('Restarting all processes...');
           $this->supervisor->supervisor.restartAllProcesses();
       }
   }
   

3. Event Listeners Trigger actions based on Supervisor events (e.g., log failures):

   $events = $supervisor->supervisor.read(1000);
   foreach ($events as $event) {
       if ($event['eventname'] === 'PROCESS_STATE_EVENT') {
           event(new ProcessStateChanged($event['data']));
       }
   }
   

4. Configurable Endpoints Store connection details in .env:

   SUPERVISOR_SOCKET=unix:///var/run/supervisor.sock
   SUPERVISOR_USERNAME=admin
   SUPERVISOR_PASSWORD=secret
   

   Load in config/supervisor.php:

   return [
       'socket' => env('SUPERVISOR_SOCKET'),
       'auth' => [
           'username' => env('SUPERVISOR_USERNAME'),
           'password' => env('SUPERVISOR_PASSWORD'),
       ],
   ];
   

Gotchas and Tips

Pitfalls

1. Deprecation Warning

   • This package is unmaintained. Prioritize migrating to SupervisorPHP for long-term projects.
   • SupervisorPHP supports async operations, Promises, and better error handling.

2. Connection Issues

   • Permission Denied: Ensure the PHP process (e.g., Laravel worker) has read/write access to the socket file (/var/run/supervisor.sock).

     chmod 666 /var/run/supervisor.sock
     

   • Timeouts: Default timeout is 30 seconds. Adjust with setTimeout() for slow environments.

3. Authentication Failures

   • Verify credentials in Supervisor’s [inet_http_server] or [unix_http_server] section in supervisord.conf:

     [inet_http_server]
     username=admin
     password=secret
     

   • If using Unix socket, ensure chmod permissions are correct for the socket file.

4. XML-RPC Quirks

   • Method Names: Supervisor’s XML-RPC API uses dot notation (e.g., supervisor.getAllProcessInfo).
   • Error Handling: Wrap calls in try-catch for SupervisorClientException:

     try {
         $supervisor->supervisor.invalidMethod();
     } catch (\SupervisorClient\Exception\SupervisorClientException $e) {
         Log::error($e->getMessage());
     }
     

5. Process Naming

   • Supervisor process names are case-sensitive and must match those in supervisord.conf.
   • Use getAllProcessInfo() to debug naming issues.

Debugging Tips

1. Enable Supervisor Logging Add to supervisord.conf:

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

2. Raw XML-RPC Debugging Use curl to test the API directly:

   curl -X POST --data-binary '<?xml version="1.0"?><methodCall><methodName>supervisor.getAllProcessInfo</methodName></methodCall>' http://admin:secret@localhost:9001/RPC2
   

3. Check Socket Path Verify the socket path in supervisord.conf:

   [unix_http_server]
   file=/var/run/supervisor.sock
   

Extension Points

1. Custom RPC Methods Extend the client to wrap Supervisor’s undocumented methods:

   class ExtendedSupervisorClient extends \SupervisorClient\SupervisorClient
   {
       public function getProcessStats($processName)
       {
           return $this->call('supervisor.getProcessStats', [$processName]);
       }
   }
   

2. Event Dispatcher Integration Create a Laravel event listener for Supervisor events:

   $supervisor->supervisor.read(1000); // Poll every second
   $events = json_decode($supervisor->supervisor.read(1000), true);
   foreach ($events as $event) {
       if ($event['eventname'] === 'PROCESS_STATE_EVENT') {
           event(new ProcessFailed($event['data']['name']));
       }
   }
   

3. Retry Logic Implement exponential backoff for transient failures:

   $attempts = 0;
   $maxAttempts = 3;
   while ($attempts < $maxAttempts) {
       try {
           $supervisor->supervisor.restartProcess('critical_job');
           break;
       } catch (\Exception $e) {
           $attempts++;
           sleep(2 ** $attempts);
       }
   }
   

Note: For new projects, evaluate SupervisorPHP for its modern features (async, Promises, better Laravel integration).