Process Laravel Package

Getting Started

Install via Composer:

composer require illuminate/process

This package is typically auto-registered in Laravel 10+ (no service provider needed). Use it immediately in tinker, commands, or jobs:

use Illuminate\Process\Factory as ProcessFactory;

$process = app(ProcessFactory::class)->run('composer validate');
if ($process->successful()) {
    echo "Valid!"; // or $process->output();
}

Key entry points: app(ProcessFactory::class), Process::fake(), or the Process facade (if aliased). Start with run() for simple blocking calls, and start() for interactive/streaming workflows.

Implementation Patterns

• Command isolation & safety: Prefer run('php artisan ...') over shell_exec()—handles escaping, avoids shell injection, and provides structured return values.
• Real-time output: Use start() with callbacks for long tasks (e.g., npm build, database migrations):

  Process::start('npm run build', function ($type, $buffer) {
      if ($type === Process::OUT) write_to_log($buffer);
  })->wait();
  

• Parallel builds/asset processing: Group independent commands with batch() for concurrency:

  Process::batch([
      fn() => Process::run('build:svg'),
      fn() => Process::run('build:css'),
  ])->timeout(120)->run();
  

• Shared process config: Use for() to apply environment or directory defaults across related commands:

  $builder = Process::for('deploy')->path(base_path('deploy-scripts'));
  $builder->run('init');
  $builder->run('migrate');
  

• Integration with HTTP dispatchers: Call external CLI tools triggered by web requests (e.g., PDF generation with wkhtmltopdf) while managing timeouts securely.

Gotchas and Tips

• throw() is opt-in: Non-zero exit codes return $process->failed() as true—explicitly call ->throw() to throw exceptions (avoids silent failures).
• Bashism vs. plain PHP: Use shell: false for security in start()/run() if avoiding shell interpretation:

  Process::run(['php', 'script.php'], timeout: 10, shell: false);
  

• Streaming large outputs: Disable line buffering only when needed (->lineLength(0)) and validate input—unbounded buffering risks memory exhaustion.
• TTY limitations: On Laravel Vapor or FPM, ->tty(true) may hang or fail; reserve for CLI contexts.
• Fake it for testing: Replace real processes with mocks in tests:

  Process::fake([
      'npm run build' => Process::result(
          output: 'Build successful',
          errorOutput: '',
          exitCode: 0
      ),
  ]);
  

• Timeout pitfalls: .timeout() applies to each process in a batch; use ->timeout() on the batch itself for overall limit.
• Debugging: Enable ->withoutTimeout() during local dev to avoid intermittent failures—but never in production.
• Windows gotcha: Avoid backslashes in command args (e.g., C:\path\to\file); use forward slashes or str_replace('\\', '/', $path).