Process Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require php-standard-library/process
   

   No additional configuration is required—just autoload.

2. First Use Case: Running a Simple Command

   use PhpStandardLibrary\Process\Process;
   
   $process = new Process('ls -la');
   $process->run();
   
   if ($process->isSuccessful()) {
       echo "Output:\n" . $process->getOutput();
   } else {
       echo "Error: " . $process->getErrorOutput();
   }
   

3. Key Entry Points

   • Process::run() – Execute the command.
   • Process::isSuccessful() – Check exit code (0 = success).
   • Process::getOutput() / Process::getErrorOutput() – Retrieve streams.
   • Process::setWorkingDirectory() – Change cwd for the subprocess.
   • Process::setEnv() – Override environment variables.

Implementation Patterns

Common Workflows

1. CLI Automation (e.g., Git Hooks, Build Steps)

$process = new Process(['git', 'pull', 'origin', 'main']);
$process->setWorkingDirectory(base_path());
$process->run();

if (!$process->isSuccessful()) {
    throw new RuntimeException("Git pull failed: " . $process->getErrorOutput());
}

2. Real-Time Output Streaming (e.g., Logging)

$process = new Process('tail -f /var/log/app.log');
$process->start(); // Non-blocking start

while ($process->isRunning()) {
    echo $process->getOutput(); // Stream output incrementally
    usleep(100000); // Throttle
}

3. Environment-Specific Commands

$process = new Process('php artisan migrate');
$process->setEnv(['APP_ENV' => 'testing']);
$process->run();

4. Integration with Laravel Artisan

use Symfony\Component\Process\Process as SymfonyProcess; // Alias if needed
$process = new Process('php artisan queue:work --once');
$process->run();

Integration Tips

1. Error Handling Always check $process->isSuccessful() and log $process->getErrorOutput() for debugging.

2. Timeouts Use Process::setTimeout() to avoid hanging:

   $process->setTimeout(30); // 30 seconds
   

3. Dependency Injection Bind the Process class in Laravel’s service container for reusable instances:

   $this->app->bind(Process::class, function () {
       return new Process(config('app.command'));
   });
   

4. Laravel Artisan Integration Wrap in a custom command for reusability:

   use PhpStandardLibrary\Process\Process;
   
   class RunProcessCommand extends Command {
       protected $signature = 'app:run {command}';
       public function handle() {
           $process = new Process($this->argument('command'));
           $process->run();
           $this->line($process->getOutput());
       }
   }
   

Gotchas and Tips

Pitfalls

1. Blocking Calls

   • run() blocks until completion. Use start() + isRunning() for async workflows.
   • Fix: Check $process->isRunning() in a loop or use Process::wait() for non-blocking checks.

2. Output Buffering

   • Some commands (e.g., ffmpeg) buffer output. Use --no-buffer flags or stream incrementally.

3. Environment Variable Leaks

   • setEnv() overrides but doesn’t merge. Explicitly pass all required vars:

     $process->setEnv([
         'DB_HOST' => env('DB_HOST'),
         'APP_DEBUG' => 'false',
     ]);
     

4. Working Directory Permissions

   • Subprocesses inherit PHP’s umask. Use chmod or umask(0) if needed:

     $process->setWorkingDirectory(storage_path('logs'));
     

5. Signal Handling

   • The package doesn’t expose SIGKILL/SIGTERM. Use Process::terminate() for graceful stops.

Debugging Tips

1. Log Raw Output

   file_put_contents(
       storage_path('logs/process_debug.log'),
       $process->getOutput() . "\n" . $process->getErrorOutput()
   );
   

2. Check Exit Codes

   • Non-zero codes indicate failure. Use $process->getExitCode() for granular checks:

     if ($process->getExitCode() === 127) {
         // Command not found
     }
     

3. Dry Runs Simulate commands without execution:

   $process = new Process('ls /nonexistent');
   $process->dryRun(); // Returns false, no subprocess spawned
   

Extension Points

1. Custom Process Builders Create a decorator for reusable configurations:

   class GitProcess extends Process {
       public function __construct(string $repoPath) {
           parent::__construct(['git', '--git-dir=' . $repoPath]);
       }
   }
   

2. Event Listeners Hook into Process::start()/Process::run() to log or modify behavior:

   $process->onStart(function () {
       Log::info('Process started: ' . $this->getCommandLine());
   });
   

3. Laravel Service Provider Register a global helper:

   if (!function_exists('run_process')) {
       function run_process(string $command) {
           $process = new Process($command);
           $process->run();
           return $process;
       }
   }