class Process implements IteratorAggregate

Process is a thin wrapper around proc_* functions to easily start independent PHP processes.

Constants

ERR

OUT

STATUS_READY

STATUS_STARTED

STATUS_TERMINATED

STDIN

STDOUT

STDERR

TIMEOUT_PRECISION

ITER_NON_BLOCKING

ITER_KEEP_OUTPUT

ITER_SKIP_OUT

ITER_SKIP_ERR

Properties

static array $exitCodes Exit codes translation table.

Methods

__construct(string $commandline, string|null $cwd = null, array $env = null, mixed|null $input = null, int|float|null $timeout = 60, array $options = array())

Constructor.

__destruct()

No description

__clone()

No description

int
run(callable|null $callback = null)

Runs the process.

mustRun(callable $callback = null)

Runs the process.

start(callable $callback = null)

Starts the process and returns after writing the input to STDIN.

restart(callable $callback = null)

Restarts the process.

int
wait(callable $callback = null)

Waits for the process to terminate.

int|null
getPid()

Returns the Pid (process identifier), if applicable.

signal(int $signal)

Sends a POSIX signal to the process.

disableOutput()

Disables fetching output and error output from the underlying process.

enableOutput()

Enables fetching output and error output from the underlying process.

bool
isOutputDisabled()

Returns true in case the output is disabled, false otherwise.

string
getOutput()

Returns the current output of the process (STDOUT).

string
getIncrementalOutput()

Returns the output incrementally.

getIterator(int $flags)

Returns an iterator to the output of the process, with the output type as keys (Process::OUT/ERR).

clearOutput()

Clears the process output.

string
getErrorOutput()

Returns the current error output of the process (STDERR).

string
getIncrementalErrorOutput()

Returns the errorOutput incrementally.

clearErrorOutput()

Clears the process output.

null|int
getExitCode()

Returns the exit code returned by the process.

null|string
getExitCodeText()

Returns a string representation for the exit code returned by the process.

bool
isSuccessful()

Checks if the process ended successfully.

bool
hasBeenSignaled()

Returns true if the child process has been terminated by an uncaught signal.

int
getTermSignal()

Returns the number of the signal that caused the child process to terminate its execution.

bool
hasBeenStopped()

Returns true if the child process has been stopped by a signal.

int
getStopSignal()

Returns the number of the signal that caused the child process to stop its execution.

bool
isRunning()

Checks if the process is currently running.

bool
isStarted()

Checks if the process has been started with no regard to the current state.

bool
isTerminated()

Checks if the process is terminated.

string
getStatus()

Gets the process status.

int
stop(int|float $timeout = 10, int $signal = null)

Stops the process.

addOutput(string $line)

Adds a line to the STDOUT stream.

addErrorOutput(string $line)

Adds a line to the STDERR stream.

string
getCommandLine()

Gets the command line to be executed.

setCommandLine(string $commandline)

Sets the command line to be executed.

float|null
getTimeout()

Gets the process timeout (max. runtime).

float|null
getIdleTimeout()

Gets the process idle timeout (max. time since last output).

setTimeout(int|float|null $timeout)

Sets the process timeout (max. runtime).

setIdleTimeout(int|float|null $timeout)

Sets the process idle timeout (max. time since last output).

setTty(bool $tty)

Enables or disables the TTY mode.

bool
isTty()

Checks if the TTY mode is enabled.

setPty(bool $bool)

Sets PTY mode.

bool
isPty()

Returns PTY state.

string|null
getWorkingDirectory()

Gets the working directory.

setWorkingDirectory(string $cwd)

Sets the current working directory.

array
getEnv()

Gets the environment variables.

setEnv(array $env)

Sets the environment variables.

resource|string|Iterator|null
getInput()

Gets the Process input.

setInput(resource|scalar|Traversable|null $input)

Sets the input.

array
getOptions()

Gets the options for proc_open.

setOptions(array $options)

Sets the options for proc_open.

bool
getEnhanceWindowsCompatibility()

Gets whether or not Windows compatibility is enabled.

setEnhanceWindowsCompatibility(bool $enhance)

Sets whether or not Windows compatibility is enabled.

bool
getEnhanceSigchildCompatibility()

Returns whether sigchild compatibility mode is activated or not.

setEnhanceSigchildCompatibility(bool $enhance)

Activates sigchild compatibility mode.

inheritEnvironmentVariables(bool $inheritEnv = true)

Sets whether environment variables will be inherited or not.

bool
areEnvironmentVariablesInherited()

Returns whether environment variables will be inherited or not.

checkTimeout()

Performs a check between the timeout definition and the time the process started.

static bool
isPtySupported()

Returns whether PTY is supported on the current operating system.

Details

at line line 148
__construct(string $commandline, string|null $cwd = null, array $env = null, mixed|null $input = null, int|float|null $timeout = 60, array $options = array())

Constructor.

Parameters

string $commandline The command line to run
string|null $cwd The working directory or null to use the working dir of the current PHP process
array $env The environment variables or null to use the same environment as the current PHP process
mixed|null $input The input as stream resource, scalar or \Traversable, or null for no input
int|float|null $timeout The timeout in seconds or null to disable
array $options An array of options for proc_open

Exceptions

RuntimeException When proc_open is not installed

at line line 177
__destruct()

at line line 182
__clone()

at line line 206
int run(callable|null $callback = null)

Runs the process.

The callback receives the type of output (out or err) and some bytes from the output in real-time. It allows to have feedback from the independent process during execution.

The STDOUT and STDERR are also available after the process is finished via the getOutput() and getErrorOutput() methods.

Parameters

callable|null $callback A PHP callback to run whenever there is some output available on STDOUT or STDERR

Return Value

int The exit status code

Exceptions

RuntimeException When process can't be launched
RuntimeException When process stopped after receiving signal
LogicException In case a callback is provided and output has been disabled

at line line 226
Process mustRun(callable $callback = null)

Runs the process.

This is identical to run() except that an exception is thrown if the process exits with a non-zero exit code.

Parameters

callable $callback

Return Value

Process

Exceptions

RuntimeException if PHP was compiled with --enable-sigchild and the enhanced sigchild compatibility mode is not enabled
ProcessFailedException if the process didn't terminate successfully

at line line 258
start(callable $callback = null)

Starts the process and returns after writing the input to STDIN.

This method blocks until all STDIN data is sent to the process then it returns while the process runs in the background.

The termination of the process can be awaited with wait().

The callback receives the type of output (out or err) and some bytes from the output in real-time while writing the standard input to the process. It allows to have feedback from the independent process during execution.

Parameters

callable $callback A PHP callback to run whenever there is some output available on STDOUT or STDERR

Exceptions

RuntimeException When process can't be launched
RuntimeException When process is already running
LogicException In case a callback is provided and output has been disabled

at line line 344
Process restart(callable $callback = null)

Restarts the process.

Be warned that the process is cloned before being started.

Parameters

callable $callback A PHP callback to run whenever there is some output available on STDOUT or STDERR

Return Value

Process The new process

Exceptions

RuntimeException When process can't be launched
RuntimeException When process is already running

See also

start()

at line line 371
int wait(callable $callback = null)

Waits for the process to terminate.

The callback receives the type of output (out or err) and some bytes from the output in real-time while writing the standard input to the process. It allows to have feedback from the independent process during execution.

Parameters

callable $callback A valid PHP callback

Return Value

int The exitcode of the process

Exceptions

RuntimeException When process timed out
RuntimeException When process stopped after receiving signal
LogicException When process is not yet started

at line line 407
int|null getPid()

Returns the Pid (process identifier), if applicable.

Return Value

int|null The process id if running, null otherwise

at line line 423
Process signal(int $signal)

Sends a POSIX signal to the process.

Parameters

int $signal A valid POSIX signal (see http://www.php.net/manual/en/pcntl.constants.php)

Return Value

Process

Exceptions

LogicException In case the process is not running
RuntimeException In case --enable-sigchild is activated and the process can't be killed
RuntimeException In case of failure

at line line 438
Process disableOutput()

Disables fetching output and error output from the underlying process.

Return Value

Process

Exceptions

RuntimeException In case the process is already running
LogicException if an idle timeout is set

at line line 459
Process enableOutput()

Enables fetching output and error output from the underlying process.

Return Value

Process

Exceptions

RuntimeException In case the process is already running

at line line 475
bool isOutputDisabled()

Returns true in case the output is disabled, false otherwise.

Return Value

bool

at line line 488
string getOutput()

Returns the current output of the process (STDOUT).

Return Value

string The process output

Exceptions

LogicException in case the output has been disabled
LogicException In case the process is not started

at line line 510
string getIncrementalOutput()

Returns the output incrementally.

In comparison with the getOutput method which always return the whole output, this one returns the new output since the last call.

Return Value

string The process output since the last call

Exceptions

LogicException in case the output has been disabled
LogicException In case the process is not started

at line line 534
Generator getIterator(int $flags)

Returns an iterator to the output of the process, with the output type as keys (Process::OUT/ERR).

Parameters

int $flags A bit field of Process::ITER_* flags

Return Value

Generator

Exceptions

LogicException in case the output has been disabled
LogicException In case the process is not started

at line line 586
Process clearOutput()

Clears the process output.

Return Value

Process

at line line 603
string getErrorOutput()

Returns the current error output of the process (STDERR).

Return Value

string The process error output

Exceptions

LogicException in case the output has been disabled
LogicException In case the process is not started

at line line 626
string getIncrementalErrorOutput()

Returns the errorOutput incrementally.

In comparison with the getErrorOutput method which always return the whole error output, this one returns the new error output since the last call.

Return Value

string The process error output since the last call

Exceptions

LogicException in case the output has been disabled
LogicException In case the process is not started

at line line 645
Process clearErrorOutput()

Clears the process output.

Return Value

Process

at line line 661
null|int getExitCode()

Returns the exit code returned by the process.

Return Value

null|int The exit status code, null if the Process is not terminated

Exceptions

RuntimeException In case --enable-sigchild is activated and the sigchild compatibility mode is disabled

at line line 683
null|string getExitCodeText()

Returns a string representation for the exit code returned by the process.

This method relies on the Unix exit code status standardization and might not be relevant for other operating systems.

Return Value

null|string A string representation for the exit status code, null if the Process is not terminated

See also

http://tldp.org/LDP/abs/html/exitcodes.html
http://en.wikipedia.org/wiki/Unix_signal

at line line 697
bool isSuccessful()

Checks if the process ended successfully.

Return Value

bool true if the process ended successfully, false otherwise

at line line 712
bool hasBeenSignaled()

Returns true if the child process has been terminated by an uncaught signal.

It always returns false on Windows.

Return Value

bool

Exceptions

RuntimeException In case --enable-sigchild is activated
LogicException In case the process is not terminated

at line line 733
int getTermSignal()

Returns the number of the signal that caused the child process to terminate its execution.

It is only meaningful if hasBeenSignaled() returns true.

Return Value

int

Exceptions

RuntimeException In case --enable-sigchild is activated
LogicException In case the process is not terminated

at line line 753
bool hasBeenStopped()

Returns true if the child process has been stopped by a signal.

It always returns false on Windows.

Return Value

bool

Exceptions

LogicException In case the process is not terminated

at line line 769
int getStopSignal()

Returns the number of the signal that caused the child process to stop its execution.

It is only meaningful if hasBeenStopped() returns true.

Return Value

int

Exceptions

LogicException In case the process is not terminated

at line line 781
bool isRunning()

Checks if the process is currently running.

Return Value

bool true if the process is currently running, false otherwise

at line line 797
bool isStarted()

Checks if the process has been started with no regard to the current state.

Return Value

bool true if status is ready, false otherwise

at line line 807
bool isTerminated()

Checks if the process is terminated.

Return Value

bool true if process is terminated, false otherwise

at line line 821
string getStatus()

Gets the process status.

The status is one of: ready, started, terminated.

Return Value

string The current process status

at line line 836
int stop(int|float $timeout = 10, int $signal = null)

Stops the process.

Parameters

int|float $timeout The timeout in seconds
int $signal A POSIX signal to send in case the process has not stop at timeout, default is SIGKILL (9)

Return Value

int The exit-code of the process

at line line 872
addOutput(string $line)

Adds a line to the STDOUT stream.

Parameters

string $line The line to append

at line line 888
addErrorOutput(string $line)

Adds a line to the STDERR stream.

Parameters

string $line The line to append

at line line 902
string getCommandLine()

Gets the command line to be executed.

Return Value

string The command to execute

at line line 914
Process setCommandLine(string $commandline)

Sets the command line to be executed.

Parameters

string $commandline The command to execute

Return Value

Process The current Process instance

at line line 926
float|null getTimeout()

Gets the process timeout (max. runtime).

Return Value

float|null The timeout in seconds or null if it's disabled

at line line 936
float|null getIdleTimeout()

Gets the process idle timeout (max. time since last output).

Return Value

float|null The timeout in seconds or null if it's disabled

at line line 952
Process setTimeout(int|float|null $timeout)

Sets the process timeout (max. runtime).

To disable the timeout, set this value to null.

Parameters

int|float|null $timeout The timeout in seconds

Return Value

Process The current Process instance

Exceptions

InvalidArgumentException if the timeout is negative

at line line 971
Process setIdleTimeout(int|float|null $timeout)

Sets the process idle timeout (max. time since last output).

To disable the timeout, set this value to null.

Parameters

int|float|null $timeout The timeout in seconds

Return Value

Process The current Process instance

Exceptions

LogicException if the output is disabled
InvalidArgumentException if the timeout is negative

at line line 991
Process setTty(bool $tty)

Enables or disables the TTY mode.

Parameters

bool $tty True to enabled and false to disable

Return Value

Process The current Process instance

Exceptions

RuntimeException In case the TTY mode is not supported

at line line 1018
bool isTty()

Checks if the TTY mode is enabled.

Return Value

bool true if the TTY mode is enabled, false otherwise

at line line 1030
Process setPty(bool $bool)

Sets PTY mode.

Parameters

bool $bool

Return Value

Process

at line line 1042
bool isPty()

Returns PTY state.

Return Value

bool

at line line 1052
string|null getWorkingDirectory()

Gets the working directory.

Return Value

string|null The current working directory or null on failure

at line line 1070
Process setWorkingDirectory(string $cwd)

Sets the current working directory.

Parameters

string $cwd The new working directory

Return Value

Process The current Process instance

at line line 1082
array getEnv()

Gets the environment variables.

Return Value

array The current environment variables

at line line 1100
Process setEnv(array $env)

Sets the environment variables.

An environment variable value should be a string. If it is an array, the variable is ignored.

That happens in PHP when 'argv' is registered into the $_ENV array for instance.

Parameters

array $env The new environment variables

Return Value

Process The current Process instance

at line line 1120
resource|string|Iterator|null getInput()

Gets the Process input.

Return Value

resource|string|Iterator|null The Process input

at line line 1136
Process setInput(resource|scalar|Traversable|null $input)

Sets the input.

This content will be passed to the underlying process standard input.

Parameters

resource|scalar|Traversable|null $input The content

Return Value

Process The current Process instance

Exceptions

LogicException In case the process is running

at line line 1152
array getOptions()

Gets the options for proc_open.

Return Value

array The current options

at line line 1164
Process setOptions(array $options)

Sets the options for proc_open.

Parameters

array $options The new options

Return Value

Process The current Process instance

at line line 1178
bool getEnhanceWindowsCompatibility()

Gets whether or not Windows compatibility is enabled.

This is true by default.

Return Value

bool

at line line 1190
Process setEnhanceWindowsCompatibility(bool $enhance)

Sets whether or not Windows compatibility is enabled.

Parameters

bool $enhance

Return Value

Process The current Process instance

at line line 1202
bool getEnhanceSigchildCompatibility()

Returns whether sigchild compatibility mode is activated or not.

Return Value

bool

at line line 1218
Process setEnhanceSigchildCompatibility(bool $enhance)

Activates sigchild compatibility mode.

Sigchild compatibility mode is required to get the exit code and determine the success of a process when PHP has been compiled with the --enable-sigchild option

Parameters

bool $enhance

Return Value

Process The current Process instance

at line line 1232
Process inheritEnvironmentVariables(bool $inheritEnv = true)

Sets whether environment variables will be inherited or not.

Parameters

bool $inheritEnv

Return Value

Process The current Process instance

at line line 1244
bool areEnvironmentVariablesInherited()

Returns whether environment variables will be inherited or not.

Return Value

bool

at line line 1257
checkTimeout()

Performs a check between the timeout definition and the time the process started.

In case you run a background process (with the start method), you should trigger this method regularly to ensure the process timeout

Exceptions

ProcessTimedOutException In case the timeout was reached

at line line 1281
static bool isPtySupported()

Returns whether PTY is supported on the current operating system.

Return Value

bool