Executor Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require phar-io/executor
   

   No additional configuration is required—it’s a lightweight, dependency-free package.

2. First Use Case: Executing a Simple Command Use the PharIo\Executor\Executor class to run shell commands directly from PHP:

   use PharIo\Executor\Executor;
   
   $executor = new Executor();
   $output = $executor->execute('ls -la', [], null, null);
   echo $output;
   

3. Where to Look First

   • Documentation: Phar-IO Executor on Packagist (limited, but the class is straightforward).
   • Source Code: GitHub Mirror (if available) for edge cases.
   • Laravel Integration: Use in Artisan commands, Console/Kernel.php, or service providers.

Implementation Patterns

Common Workflows

1. Running CLI Commands in Artisan Commands

   use PharIo\Executor\Executor;
   
   class DeployCommand extends Command
   {
       protected $signature = 'deploy:run';
       protected $description = 'Run deployment scripts';
   
       public function handle()
       {
           $executor = new Executor();
           $output = $executor->execute('git pull && php artisan migrate', [], null, null);
           $this->info($output);
       }
   }
   

2. Capturing Output and Errors Use the Output and ErrorOutput streams to log results:

   $output = new \Symfony\Component\Process\BufferedOutput();
   $errorOutput = new \Symfony\Component\Process\BufferedOutput();
   
   $executor->execute('php artisan queue:work', [], $output, $errorOutput);
   $this->info("Output: " . $output->getOutput());
   $this->error("Errors: " . $errorOutput->getOutput());
   

3. Environment-Specific Commands Dynamically build commands based on Laravel’s .env:

   $command = env('APP_ENV') === 'production'
       ? 'php artisan queue:work --daemon'
       : 'php artisan queue:work';
   $executor->execute($command, [], null, null);
   

4. Integration with Laravel’s Process Facade While not native, wrap the executor in a helper:

   if (!class_exists('ProcessExecutor')) {
       class ProcessExecutor {
           public static function run(string $command) {
               $executor = new Executor();
               return $executor->execute($command, [], null, null);
           }
       }
   }
   

   Usage:

   ProcessExecutor::run('php artisan optimize');
   

Gotchas and Tips

Pitfalls

1. No Symfony Process Dependency Unlike Symfony/Process, this package doesn’t support streams or signals natively. For advanced use cases (e.g., timeouts, signals), consider:

   // Fallback to Symfony/Process if needed
   $process = new \Symfony\Component\Process\Process(['ls', '-la']);
   $process->run();
   

2. Output Handling Quirks

   • The execute() method returns a string, not a Process object. For structured output, parse manually or use Symfony’s BufferedOutput.
   • No real-time output: Unlike Symfony’s Process, you can’t stream output line-by-line without buffering.

3. Security Risks

   • Arbitrary Command Injection: Always sanitize inputs if commands are user-provided:

     $safeCommand = escapeshellcmd($userInput);
     $executor->execute($safeCommand, [], null, null);
     

   • Environment Variables: Avoid passing sensitive data via command arguments. Use Laravel’s env() or encrypted storage.

4. Cross-Platform Issues

   • Commands like dir (Windows) vs. ls (Linux) may break. Use Laravel’s Str::contains() or config('app.os') to adapt:

     $command = config('app.os') === 'windows' ? 'dir' : 'ls';
     

Debugging Tips

1. Log Raw Output Redirect output to a file for debugging:

   file_put_contents(storage_path('logs/command.log'), $output);
   

2. Check Exit Codes The package doesn’t expose exit codes directly. Use exec() as a fallback if needed:

   exec($command, $output, $exitCode);
   $this->error("Failed with exit code: $exitCode");
   

3. Timeouts The package lacks built-in timeouts. Implement a wrapper:

   $start = microtime(true);
   $executor->execute($command, [], null, null);
   if (microtime(true) - $start > 30) { // 30s timeout
       throw new \RuntimeException('Command timed out');
   }
   

Extension Points

1. Custom Output Handlers Extend the executor to support callbacks:

   class CallbackExecutor extends Executor {
       public function executeWithCallback(string $command, array $env, ?callable $outputCallback) {
           $output = $this->execute($command, $env, null, null);
           if ($outputCallback) $outputCallback($output);
           return $output;
       }
   }
   

2. Laravel Service Provider Bind the executor to the container for dependency injection:

   $this->app->singleton(Executor::class, function () {
       return new Executor();
   });
   

   Usage in controllers/commands:

   use Illuminate\Support\Facades\App;
   
   $executor = App::make(Executor::class);
   

3. Event Dispatching Trigger Laravel events on command success/failure:

   $output = $executor->execute($command, [], null, null);
   if (str_contains($output, 'error')) {
       event(new CommandFailed($command));
   }