php-shellcommand

php-shellcommand (mikehaertl/php-shellcommand) is a lightweight PHP library that wraps external process execution in a clean, object-oriented Command class. Instead of juggling proc_open, exec, or shell_exec directly, you build a command, add escaped arguments, run it, and read back stdout, stderr, and the exit code from a single object.

It handles argument and command escaping across platforms, supports both blocking and non-blocking execution, and lets you pass input via stdin, set the working directory, environment variables, and timeouts. Because it has zero dependencies and works on very old PHP versions, it is a common building block in tools that shell out to binaries like ImageMagick, wkhtmltopdf, and Git.

What You Get

• A Command class that captures stdout, stderr, and exit code
• Cross-platform argument and command escaping
• Blocking and non-blocking (background) execution modes
• Control over working directory, environment variables, and stdin input
• Configurable execution timeout and error handling

Common Use Cases

• Shelling out to binaries like ImageMagick, FFmpeg, or wkhtmltopdf
• Running Git or other CLI tools from a PHP application
• Building higher-level PHP wrappers around command-line programs
• Capturing and inspecting external process output and errors reliably

Under The Hood

Architecture - The whole library is a single Command class under the mikehaertl\shellcommand namespace. You configure it via public properties and setters (command, args, escapeArgs, procEnv, procCwd, timeout, non-blocking mode), then call execute(), which internally uses proc_open to spawn the process, wire up the stdin/stdout/stderr pipes, and collect results. Getters (getOutput, getError, getExitCode) expose the captured results afterward.

Tech Stack - Pure PHP with no runtime dependencies and support all the way back to PHP 5.3. It relies solely on core process functions (proc_open, escapeshellarg/escapeshellcmd) and adapts escaping and pipe handling to the host OS. Tests use PHPUnit.

Code Quality - The single-file implementation is mature and heavily exercised in the wild (nearly 900k monthly downloads), with CommandTest and BlockingCommandTest covering blocking and non-blocking paths. Its longevity and small surface make it dependable, though active development is minimal since the design is complete.

API Design - The API is approachable: construct a Command, set the binary and arguments, call execute(), and read the outputs. Fluent addArg() handling and clear boolean returns keep the common case terse while still exposing lower-level knobs (custom escaping, environment, timeout) for advanced scenarios.