Symfony Process

Symfony Process is a standalone PHP component for executing external commands as sub-processes without dealing with exec(), proc_open(), or shell-escaping pitfalls directly. It wraps process creation in a Process class that handles argument escaping, timeouts, working directories, environment variables, and streaming stdout/stderr in real time, on both Unix-like systems and Windows.

As one of Symfony’s foundational, framework-agnostic components, it’s usable in any PHP project regardless of whether the rest of the app runs on Symfony, and with roughly 17.3 million monthly Composer installs it’s a de facto standard for shelling out safely from PHP — used by tools like Composer itself, PHPUnit-adjacent tooling, and countless deployment and build scripts.

What You Get

• A Process class for running external commands with automatic, safe argument escaping (no manual shell-quoting)
• Synchronous (run()) and asynchronous (start()) execution modes with real-time stdout/stderr callbacks
• Configurable timeouts, idle timeouts, working directory, and environment variables per process
• An ExecutableFinder for locating binaries across PATH and common installation locations
• Cross-platform support, including Windows-specific quirks like CreateNewConsole handling
• A PhpProcess/PhpSubprocess helper for spawning child PHP processes with the correct interpreter and ini settings

Common Use Cases

• Running shell commands (git, npm, rsync, etc.) from a PHP deploy script or Symfony console command without manual escaping
• Streaming build or migration tool output back to a CLI in real time via the process’s output callback
• Enforcing a timeout on a long-running external command so it can’t hang a web request or worker indefinitely
• Spawning isolated PHP subprocesses (e.g. for parallel test runners or sandboxed script execution)

Under The Hood

Architecture — The component centers on Process.php, which wraps proc_open() and manages an internal Pipes abstraction (Pipes/UnixPipes.php, Pipes/WindowsPipes.php) to handle platform-specific stream and pipe quirks, particularly around Windows’ blocking-pipe behavior. InputStream.php supports feeding data to a running process’s stdin incrementally, and ExecutableFinder/PhpExecutableFinder locate binaries and the PHP interpreter itself across different environments; a Messenger subdirectory integrates with Symfony Messenger for running commands as async message handlers.

Tech Stack — Requires PHP 8.4.1+ on its current development branch (older tagged releases support earlier PHP versions per Symfony’s backward-compatibility promise) with zero required third-party dependencies — it only depends on core PHP process-control functions, keeping the component lightweight enough to use outside the Symfony framework entirely.

Code Quality — 41 PHP files include a substantial Tests/ suite covering ExecutableFinderTest, PhpProcessTest, edge cases like non-stoppable processes and output memory limits (NonStopableProcess.php, OutputMemoryLimitProcess.php), and Windows console-creation behavior (CreateNewConsoleTest.php) — indicating deliberate coverage of the platform-specific edge cases process management is notorious for. With 201 contributors and a century of monthly releases across supported branches, the component follows Symfony’s disciplined, backward-compatible release process.

API Design — The Process class follows a consistent builder-like pattern (Process::fromShellCommandline() or array-based constructor, then run()/start()/wait()), and array-based command construction is favored specifically to avoid shell-injection footguns that plague raw exec()/shell_exec() usage — a deliberate safety-first design choice documented throughout the README and official docs.