Supervisor Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The supervisorphp/supervisor package enables programmatic interaction with Supervisor (a process control system) via XML-RPC, making it ideal for:
  • Dynamic process management (start/stop/restart workers, queues, or background jobs).
  • Automated deployment workflows (e.g., zero-downtime restarts, health checks).
  • Laravel-specific integrations (e.g., managing queue workers, cron jobs, or long-running tasks).
• Laravel Synergy: Supervisor is commonly used alongside Laravel’s queue workers (php artisan queue:work), scheduler, or event listeners. This package bridges the gap between Laravel’s task orchestration and Supervisor’s process control.
• Alternatives Considered: Native Supervisor CLI/API or direct XML-RPC calls (via curl/file_get_contents) are possible but less maintainable. This package abstracts complexity while retaining flexibility.

Integration Feasibility

• Laravel Compatibility:
  • Service Provider: Can be bootstrapped via Laravel’s ServiceProvider (e.g., SupervisorManager) to centralize process control logic.
  • Artisan Commands: Extend Laravel’s CLI with custom commands (e.g., php artisan supervisor:restart queue-worker).
  • Event Listeners: Trigger Supervisor actions on Laravel events (e.g., job:failed → restart worker).
• XML-RPC Dependency:
  • Requires Supervisor’s XML-RPC interface enabled ([rpcinterface:unix:///tmp/supervisor.sock] in config).
  • Risk: Supervisor misconfigurations (e.g., incorrect socket permissions) may break integrations.
• PHP Version: Last release in 2022; PHP 8.0+ compatibility should be verified (backward compatibility likely, but test thoroughly).

Technical Risk

Key Questions

1. Supervisor Configuration:
   • Is XML-RPC enabled and accessible from the Laravel app’s environment?
   • Are there existing Supervisor programs (e.g., queue-worker) to manage?
2. Failure Recovery:
   • How should Laravel handle Supervisor API timeouts or connection drops?
3. Permissions:
   • Does the Laravel process have read/write access to Supervisor’s socket?
4. Monitoring:
   • Will Supervisor’s logs be aggregated with Laravel’s (e.g., via ELK or Sentry)?
5. Alternatives:
   • Could a custom Process wrapper (using Symfony’s Process component) suffice for simpler use cases?

Integration Approach

Stack Fit

• Primary Use Cases:
  • Queue Workers: Restart stalled queue:work processes.
  • Cron Jobs: Manage Laravel scheduler processes dynamically.
  • Microservices: Orchestrate external PHP workers (e.g., image processors).
• Laravel-Specific Integrations:
  • Queue Drivers: Pair with database, redis, or beanstalkd queues.
  • Forge/Envoyer: Automate Supervisor updates during deployments.
  • Horizon: Complement Horizon’s process management with Supervisor’s reliability.

Migration Path

1. Assessment Phase:
   • Audit current Supervisor programs (e.g., queue-worker.conf).
   • Verify XML-RPC connectivity (php -r '$client = new \Supervisor\Client(); var_dump($client->getState());').
2. Proof of Concept:
   • Implement a minimal SupervisorService class to test CRUD operations (e.g., restart a program).
   • Example:

     $supervisor = new \Supervisor\Client('unix:///tmp/supervisor.sock');
     $supervisor->restart('queue-worker');
     

3. Laravel Integration:
   • Publish a config file (config/supervisor.php) for socket/timeout settings.
   • Bind the client to Laravel’s container:

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

4. Artisan Commands:
   • Create SupervisorCommand for CLI access:

     php artisan supervisor:restart queue-worker
     php artisan supervisor:status
     

Compatibility

• Supervisor Version: Tested with Supervisor 4.x (common in Laravel deployments). Downgrade if needed.
• PHP Extensions: No additional extensions required (XML-RPC is core).
• Laravel Packages:
  • Horizon: Use Supervisor to manage Horizon processes instead of systemd.
  • Laravel Zero: Control long-running CLI apps via Supervisor.

Sequencing

1. Pre-Deployment:
   • Configure Supervisor XML-RPC and socket permissions.
2. Deployment:
   • Use the package to restart workers post-migration (e.g., after composer install).
3. Runtime:
   • Monitor worker health via Supervisor events (e.g., STOPPED → auto-restart).

Operational Impact

Maintenance

• Package Updates:
  • Monitor for forks or upstream Supervisor API changes.
  • Pin version in composer.json to avoid breaking updates.
• Configuration Drift:
  • Store Supervisor program definitions in Laravel config or database (e.g., config/supervisor/programs.php).
  • Example:

    'programs' => [
        'queue-worker' => [
            'command' => 'php artisan queue:work --sleep=3 --tries=3',
            'numprocs' => 4,
        ],
    ],
    

Support

• Debugging:
  • Log Supervisor API responses/errors to Laravel’s log channel.
  • Example:

    try {
        $supervisor->restart('worker');
    } catch (\Supervisor\Exception\SupervisorException $e) {
        Log::error('Supervisor restart failed', ['error' => $e->getMessage()]);
    }
    

• Documentation:
  • Add a SUPERVISOR.md to the Laravel repo detailing:
    • Socket location and permissions.
    • Available Artisan commands.
    • Troubleshooting steps (e.g., "Supervisor not running?").

Scaling

• Horizontal Scaling:
  • Supervisor’s numprocs can scale workers across Laravel instances (e.g., 4 workers per app server).
  • Caveat: Avoid overloading a single Supervisor instance; distribute across servers if needed.
• Multi-Environment:
  • Use Laravel’s .env to switch Supervisor sockets (e.g., SUPERVISOR_SOCKET=/var/run/supervisor.sock).

Failure Modes

Ramp-Up

• Onboarding:
  • For Developers: Document how to add new Supervisor-managed programs via Laravel config.
  • For Ops: Provide a checklist for Supervisor setup (e.g., "Enable XML-RPC in /etc/supervisor/supervisord.conf").
• Training:
  • Demo a workflow: "Deploy code → Laravel triggers Supervisor restart → Zero downtime."
• Tooling:
  • Integrate with Laravel Forge/Envoyer for automated Supervisor updates during deployments.