Process

Reference for the Process module: spawn an external command as a running process you can read from, write to and close, fork the current process across several workers, and read the command-line arguments a script was run with.

This page is a pure reference. For how the framework fits together, see the Guide.

Classes

Process - spawn a command, fork the current process, and read a running process.
ProcessResultData - a result that is either a success value or an error string.
ProcessSpawnData - the settings that describe a command to spawn.

Process

The main class. Its static functions spawn a command or fork the current process, and read the command-line arguments. An instance represents one running process, returned by Process::Command, with methods to check its state, read its output and error, send input, and close it.

Functions

Arguments Close Command Error ExitCode Forks Input IsRunning Output Send

Arguments

Process::Arguments(): array

The command-line arguments a script was run with, used when a PHP file is run directly from the terminal or as a command. It does not include the php command or the script name.

Returns array The list of arguments.

Close

$process->Close(): void

Close the process, closing its input, output and error pipes.

Returns void

Command

Process::Command(string $command, array $arguments = [], string $workingDirectory = '', array $environmentVariables = [], array $options = []): Process

Spawn a new process and return an object with functions for checking if the process is still running, getting the exit code, and getting the output of the process. The arguments are escaped before being passed to the command.

Name	Type	Description
`$command`	`string`	The command to run.
`$arguments`	`array`	The arguments passed to the command.
`$workingDirectory`	`string`	The working directory to run the command in.
`$environmentVariables`	`array`	The environment variables for the process.
`$options`	`array`	Options passed when opening the process.

Returns Process The running process.

Error

$process->Error(): string

The error output of the process.

Returns string The error output.

ExitCode

$process->ExitCode(): int

The exit code of the process.

Returns int The exit code.

Forks

Process::Forks(int $numProcesses, Callable $callback): void

Fork the current process at this point. It passes a boolean to the callback to indicate whether this is the main process or the subprocess.

Name	Type	Description
`$numProcesses`	`int`	The number of processes.
`$callback`	`Callable`	Called with true in the child process and false in the parent process.

Returns void

Input

$process->Input(): string

The input of the process, read from its input pipe.

Returns string The input read.

IsRunning

$process->IsRunning(): bool

Whether the process is still running.

Returns bool True while the process is running.

Output

$process->Output(): string

Read output from the process. Once the output is read it is discarded, so each call returns just the new data; when there is no new data a blank string is returned.

Returns string The new output, or a blank string.

Send

$process->Send(string $input): void

Send input to the process, writing it to the input pipe.

Name	Type	Description
`$input`	`string`	The input to send.

Returns void

ProcessResultData

A sum type that is either a success or an error. It has two optional fields, one for the success value and one for the error string. Its constructor is private; instances are created through the static functions below.

Properties

Name	Type	Description
`$success`	`mixed`	The success value, or null.
`$error`	`string\|null`	The error string, or null.

Functions

error FromJSON success

error

ProcessResultData::error(string $error): ProcessResultData

Create an error result holding the given error string.

Name	Type	Description
`$error`	`string`	The error string.

Returns ProcessResultData An error result.

FromJSON

ProcessResultData::FromJSON(stdClass $json): ProcessResultData

Build a result from a decoded JSON object, using its success or error field. Throws when the object has neither.

Name	Type	Description
`$json`	`stdClass`	A decoded JSON object with a success or error field.

Returns ProcessResultData The result.

success

ProcessResultData::success(mixed $success): ProcessResultData

Create a success result holding the given value.

Name	Type	Description
`$success`	`mixed`	The success value.

Returns ProcessResultData A success result.

ProcessSpawnData

The settings that describe a command to spawn: the command, its arguments, working directory, environment variables and options.

Properties

Name	Type	Description
`$command`	`string`	The command to run.
`$arguments`	`array`	The arguments passed to the command.
`$workingDirectory`	`string`	The working directory to run the command in.
`$environmentVariables`	`array`	The environment variables for the process.
`$options`	`array`	Options passed when opening the process.

Functions

__construct

new ProcessSpawnData(string $command = '', array $arguments = [], string $workingDirectory = '', array $environmentVariables = [], array $options = [])

Create the spawn settings from the given command and its arguments, working directory, environment variables and options.

Name	Type	Description
`$command`	`string`	The command to run.
`$arguments`	`array`	The arguments passed to the command.
`$workingDirectory`	`string`	The working directory to run the command in.
`$environmentVariables`	`array`	The environment variables for the process.
`$options`	`array`	Options passed when opening the process.