Castor Process — castor/process

# Castor Process Castor Process is a small process-management library for PHP. It starts external programs with `proc_open()`, exposes the child process standard streams as Castor IO objects, and gives you a focused API for polling, waiting, terminating, and inspecting exit status. The main entry point lives at `Castor\Os\Process`. Completed one-shot runs return `Castor\Os\Process\Result`, and process pipes use small classes under the `Castor\Os\Process` namespace. ## Install Castor packages are published in the Castor Composer repository, not Packagist. Add the repository first, then require the package: ```bash composer config repositories.castor composer https://castor-labs.github.io/php-packages composer require castor/process ``` The package requires PHP 8.3 or newer and the `pcntl` extension. ## Quick example ```php <?php use Castor\Os\Process; $result = Process::run(['php', '-r', 'fwrite(STDOUT, "Hello\\n");']); echo $result->exitCode; // 0 echo $result->stdout; // Hello\n echo $result->stderr; // "" ``` For simple commands, the result object gives you the exit code and captured output immediately. When you need lower-level control, `Process::start()` exposes `stdout` and `stderr` as `Castor\Io\Reader` streams and `stdin` as a `Castor\Io\Writer`. ## What's included **One-shot execution** — `Process::run()` handles the common case: start a command, close stdin, wait for completion, capture stdout and stderr, and return a `Castor\Os\Process\Result`. **Process startup** — `Process::start()` accepts either a command string or a list of command arguments, plus optional working directory and environment variables when you need lower-level lifecycle control. **Castor IO pipes** — Every process exposes `stdin`, `stdout`, and `stderr` as typed Castor IO objects. Use `collect()`, `Castor\Io\read_all()`, `Castor\Io\copy()`, `Castor\Io\Buffered\Reader`, or direct `read()` and `write()` calls. For line-oriented interactive input, `stdin` also provides `sendLine()`. **Lifecycle inspection** — Poll with `isRunning()`, read the child PID with `pid()`, wait with `wait()`, and inspect normal or signal-based termination with `getExitCode()`, `isSignaled()`, and `getTermSignal()`. **Timeouts** — Pass a total runtime timeout to `run()` or `wait()` to prevent hung commands from blocking forever. `start()` can set the default timeout for later `wait()` calls. When the timeout expires, Castor Process terminates the direct child process and throws `Castor\Os\Process\TimeoutException` while leaving the pipes readable. **Resource cleanup** — `close()` closes all three pipes and calls `proc_close()`. The destructor also closes open resources, but explicit cleanup keeps failures and ownership obvious. ## Learn more Start with [getting started](docs/getting-started.html), then read the guides for [starting processes](docs/starting-processes.html), [process IO](docs/process-io.html), [waiting and exit codes](docs/waiting-and-exit-codes.html), [error handling](docs/error-handling.html), and the complete [Process API reference](docs/process-api.html).

Next → Documentation