Child Process Laravel Package

Getting Started

Install the package via Composer: composer require react/child-process. Start by reading the Quickstart example in the README — it’s minimal and demonstrates the core pattern: create a Process, call start(), attach data listeners to stdout/stderr, and handle the exit event. First use case: run a simple command (e.g., php artisan list) and stream its output without blocking the EventLoop. Avoid complex shell constructs initially; use escapeshellarg() when passing user input or paths with spaces.

Implementation Patterns

• Streaming I/O: Attach event listeners to $process->stdout, $process->stdin, $process->stderr for async data handling (e.g., on('data'), on('end')). Use $process->stdin->write() to stream input interactively (e.g., for REPL-like tools or long-running processes).
• Chaining Sequential Commands: Instead of complex shell chains (cmd1 && cmd2), start processes sequentially using exit events to maintain fine-grained control and error handling:

  $p1 = new Process('build');  
  $p1->start();  
  $p1->on('exit', fn() => $p2 = new Process('test')->start());  
  

• Signal Handling: Use $process->terminate($signal) for graceful shutdowns. For robust cleanup, close all pipes ($process->pipes) before sending signals to prevent zombie processes or lingering descriptors.
• Unix Optimization: Prefix long-running single commands with exec on Unix to avoid the shell wrapper (e.g., exec sleep 5) — improves PID accuracy and signal targeting.
• Testing/Debugging: Stream stderr alongside stdout to catch errors without exit code parsing; use Loop::addTimer() for timeouts with explicit termination logic.

Gotchas and Tips

• Shell Wrapper Quirks: On Unix, all commands run inside sh -c unless prefixed with exec. This means signals target the shell (PID ≠ child PID), and pipes inherit to sub-processes — often causing termination issues. Always test signal behavior in your environment.
• Windows Limitations: Non-blocking I/O pipes are unsupported. Avoid relying on stdout/stderr for real-time streaming on Windows; consider alternatives like log files. Use cmd /c explicitly for shell built-ins.
• Paused Streams Block Exit: If any pipe is paused (e.g., via pipe() or manual pause()), the process may not detect termination. Always resume or close pipes before expecting exit.
• Custom Pipes: When overriding pipes, ensure FDs are correctly specified per proc_open() format. Misconfigured pipes (e.g., missing 0, 1, 2) can cause $stdin/$stdout properties to be unset.
• Memory Safety: Avoid buffering large outputs in memory — rely on streaming. Use drain events on stdin when writing large payloads:

  $process->stdin->on('drain', fn() => $process->stdin->write('...'));  
  

• Version Awareness: The package is on development v0.7. Ensure you read the README for the branch you’re using — v0.6 vs. v0.7 may differ (check composer.json for version pins).