Process Control Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aboutcoders/process-control
   

   Register the service provider in config/app.php:

   Aboutcoders\ProcessControl\ProcessControlServiceProvider::class,
   

2. Basic Usage Define a process in a Laravel command:

   use Aboutcoders\ProcessControl\ProcessControl;
   
   class ExampleProcess extends Command
   {
       protected $signature = 'process:example';
       protected $description = 'Run a controlled process';
   
       public function handle(ProcessControl $processControl)
       {
           $process = $processControl->create('example-process')
               ->setCommand('php artisan some:task')
               ->setTimeout(3600) // 1 hour
               ->setMaxRetries(3)
               ->run();
       }
   }
   

3. First Use Case

   • Queue a long-running task (e.g., image processing, report generation) without blocking the HTTP response.
   • Monitor process status via the ProcessControl facade or API endpoints (if exposed).

Implementation Patterns

Workflow: Process Lifecycle Management

1. Define the Process

   $process = $processControl->create('data-export')
       ->setCommand('php artisan export:data')
       ->setEnvironment(['APP_ENV=production'])
       ->setWorkingDirectory(storage_path('app'));
   

2. Execute & Monitor

   $process->run(); // Runs asynchronously
   $status = $process->status(); // 'pending', 'running', 'completed', 'failed'
   $output = $process->output(); // Logs/results
   

3. Retry Logic

   $process->setMaxRetries(3)
           ->setRetryDelay(60) // seconds
           ->run();
   

4. Event Listeners Bind to process events (e.g., ProcessStarted, ProcessFailed):

   ProcessControl::listen('ProcessFailed', function ($process) {
       Log::error("Process {$process->id} failed", $process->output());
   });
   

Integration Tips

• Laravel Queues: Combine with queue:work for distributed processing.

  $process->queueOn('high-priority'); // Uses Laravel's queue system
  

• API Endpoints: Expose process status via a controller:

  public function getProcessStatus($id)
  {
      return ProcessControl::find($id)->status();
  }
  

• Artisan Commands: Use ProcessControl in scheduled tasks (app/Console/Kernel.php):

  $schedule->command('process:example')->hourly();
  

Gotchas and Tips

Pitfalls

1. Process Isolation

   • Child processes do not inherit Laravel’s service container. Avoid calling app() or Eloquent directly in the command.
   • Fix: Pass required data via --option or environment variables.

2. Timeout Handling

   • Default timeout is unlimited. Always set a timeout to avoid zombie processes:

     ->setTimeout(300) // 5 minutes
     

3. Logging Overhead

   • Output buffering can bloat logs. Use --quiet in commands or filter output:

     ->setCommand('php artisan task --quiet')
     

4. Database Locks

   • Concurrent processes may cause race conditions (e.g., updating the same record).
   • Fix: Use database transactions or optimistic locking.

Debugging

• Check Process Table:

  php artisan process:list
  

• Inspect Output:

  $process->output(); // Raw logs
  $process->errorOutput(); // Stderr
  

• Kill Stuck Processes:

  $process->terminate(); // Force-stop
  

Extension Points

1. Custom Process Storage Override the default storage (e.g., switch to Redis):

   ProcessControl::setStorage(new RedisProcessStorage());
   

2. Pre/Post Hooks Extend the Process model to add custom logic:

   class CustomProcess extends Process
   {
       protected static function booted()
       {
           static::created(function ($process) {
               // Send Slack notification
           });
       }
   }
   

3. Docker/Kubernetes For containerized environments, use setContainer() to specify Docker commands:

   ->setCommand('docker run my-image')
   ->setContainer(true)