Supervisor Command Bundle Laravel Package

Getting Started

Minimal Setup

1. Verify Deprecation: Since this package is deprecated, assess whether YZSupervisorBundle (its dependency) meets your needs directly. If not, consider alternatives like supervisor/supervisor or custom CLI scripts.
2. Install Dependencies:

   composer require yzalis/supervisor-bundle sensio/framework-extra-bundle
   

3. Register Bundles in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony <4):

   // config/bundles.php
   return [
       // ...
       YZ\SupervisorBundle\YZSupervisorBundle::class => ['all' => true],
       Abc\Bundle\SupervisorCommandBundle\AbcSupervisorCommandBundle::class => ['all' => true],
   ];
   

4. First Use Case: List available commands to confirm functionality:

   php bin/console list abc:supervisor
   

   Expected output: Commands like abc:supervisor:start, abc:supervisor:stop, etc.

Implementation Patterns

Workflows

1. Supervisor Process Management:

   • Start/Stop/Restart processes via commands:

     php bin/console abc:supervisor:start <process_name>
     php bin/console abc:supervisor:restart-all
     

   • Tail Logs: Stream logs for a specific process:

     php bin/console abc:supervisor:tail <process_name>
     

   • Check Status: Verify process health:

     php bin/console abc:supervisor:status
     

2. Integration with Symfony Workflows:

   • Use SensioFrameworkExtraBundle annotations to bind commands to routes (e.g., for admin panels):

     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
     use Symfony\Component\Routing\Annotation\Route;
     
     /**
      * @Route("/admin/supervisor/restart", name="supervisor_restart")
      */
     public function restartAction() {
         $this->get('command_handler')->execute('abc:supervisor:restart-all');
     }
     

3. Event-Driven Triggers:

   • Hook commands into Symfony events (e.g., kernel.terminate) to auto-restart failed processes:

     // src/EventListener/SupervisorListener.php
     public function onTerminate(KernelEvents::TERMINATE, Event $event) {
         $this->get('command_handler')->execute('abc:supervisor:status');
     }
     

Configuration Tips

• Supervisor Config: Ensure supervisord.conf is properly configured (e.g., supervisorctl rpcpipe path):

  [rpcinterface:unix_http_server]
  unix_http_server_file=/var/run/supervisor.sock
  

• Environment Variables: Use .env for dynamic paths:

  SUPERVISOR_SOCKET=/var/run/supervisor.sock
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • The bundle is unmaintained. Prioritize YZSupervisorBundle or alternatives like:
     • spatie/laravel-supervisor (Laravel-specific).
     • Direct supervisorctl CLI calls via Symfony’s Process component.
   • Example alternative:

     use Symfony\Component\Process\Process;
     $process = new Process(['supervisorctl', 'restart', 'all']);
     $process->run();
     

2. Permission Issues:

   • Commands may fail if the Symfony user lacks permissions to /var/run/supervisor.sock. Fix with:

     sudo chown -R www-data:www-data /var/run/supervisor
     

   • Or configure supervisord to use a TCP socket (less secure but more flexible).

3. Command Not Found:

   • If abc:supervisor commands are missing, ensure:
     • The bundle is enabled in config/bundles.php.
     • YZSupervisorBundle is properly configured (check config.yml for yz_supervisor settings).

4. Process Naming:

   • Commands use Supervisor process names (not Symfony service IDs). Verify names with:

     supervisorctl list
     

Debugging

• Verbose Output: Add -v to commands for debugging:

  php bin/console abc:supervisor:start my_process -v
  

• Supervisor Logs: Check /var/log/supervisor/supervisord.log for errors.
• Dry Runs: Test commands in a staging environment first.

Extension Points

1. Custom Commands:

   • Extend the bundle by creating a new command class (e.g., MySupervisorCommand) and override logic:

     namespace App\Command;
     use Symfony\Component\Console\Command\Command;
     use Symfony\Component\Console\Input\InputInterface;
     use Symfony\Component\Console\Output\OutputInterface;
     
     class MySupervisorCommand extends Command {
         protected function execute(InputInterface $input, OutputInterface $output) {
             $supervisor = $this->getContainer()->get('yz_supervisor.supervisor');
             $supervisor->restart('my_custom_process');
         }
     }
     

   • Register it in services.yaml:

     commands:
         app.my_supervisor: App\Command\MySupervisorCommand
     

2. Event Listeners:

   • Subscribe to yz_supervisor.process_state_change events to react to process failures:

     // src/EventListener/ProcessListener.php
     public function onProcessStateChange(ProcessStateChangeEvent $event) {
         if ($event->getState() === ProcessStateChangeEvent::STATE_FAILED) {
             $this->get('command_handler')->execute('abc:supervisor:restart', [$event->getProcessName()]);
         }
     }
     

3. Configuration Overrides:

   • Override yz_supervisor settings in config/packages/yz_supervisor.yaml:

     yz_supervisor:
         supervisor_socket: '%env(SUPERVISOR_SOCKET)%'
         processes:
             my_process:
                 command: 'php bin/console my:long-running-task'
                 autostart: true
     

Performance Tips

• Batch Operations: Use restart-all instead of individual restarts to reduce overhead.
• Caching: Cache process status checks if polling frequently (e.g., via Symfony’s cache system).
• Async Execution: Offload commands to a queue (e.g., Symfony Messenger) for non-critical processes.

```markdown
## Alternatives Considered
| Feature               | `aboutcoders/supervisor-command-bundle` | `YZSupervisorBundle` | `spatie/laravel-supervisor` | Custom `supervisorctl` |
|-----------------------|------------------------------------------|----------------------|-----------------------------|------------------------|
| **Process Control**   | ✅ (Basic)                              | ✅ (Advanced)        | ✅ (Laravel)                | ✅ (Full)              |
| **Symfony Integration** | ✅ (Commands)                          | ✅ (Services)        | ✅ (Laravel)                | ❌ (Manual)            |
| **Event Hooks**       | ❌                                      | ✅                   | ❌                          | ❌                     |
| **Maintenance**       | ❌ (Deprecated)                        | ✅ (Active)          | ✅ (Active)                 | ✅ (Manual)            |
| **Laravel Support**   | ❌                                      | ❌                   | ✅                          | ❌                     |