Process

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

Parameters

string|array	$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

__destruct()

__clone()

int run($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

$callback

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

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

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

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

$this restart(callable $callback = null)

Restarts the process.

Be warned that the process is cloned before being started.

Parameters

callable

$callback

Return Value

$this

Exceptions

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

See also

start()

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

int|null getPid()

Returns the Pid (process identifier), if applicable.

Return Value

int|null

The process id if running, null otherwise

$this 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

$this

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

$this disableOutput()

Disables fetching output and error output from the underlying process.

Return Value

$this

Exceptions

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

$this enableOutput()

Enables fetching output and error output from the underlying process.

Return Value

$this

Exceptions

RuntimeException

In case the process is already running

bool isOutputDisabled()

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

Return Value

bool

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

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

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

$this clearOutput()

Clears the process output.

Return Value

$this

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

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

$this clearErrorOutput()

Clears the process output.

Return Value

$this

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

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

bool isSuccessful()

Checks if the process ended successfully.

Return Value

bool	true if the process ended successfully, false otherwise

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

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

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

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

bool isRunning()

Checks if the process is currently running.

Return Value

bool	true if the process is currently running, false otherwise

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

bool isTerminated()

Checks if the process is terminated.

Return Value

bool	true if process is terminated, false otherwise

string getStatus()

Gets the process status.

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

Return Value

string

The current process status

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

addOutput(string $line)

Adds a line to the STDOUT stream.

Parameters

string

$line

The line to append

addErrorOutput(string $line)

Adds a line to the STDERR stream.

Parameters

string

$line

The line to append

string getCommandLine()

Gets the command line to be executed.

Return Value

string

The command to execute

Process setCommandLine(string|array $commandline)

Sets the command line to be executed.

Parameters

string|array

$commandline

The command to execute

Return Value

Process

The current Process instance

float|null getTimeout()

Gets the process timeout (max. runtime).

Return Value

float|null

The timeout in seconds or null if it's disabled

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

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

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

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

bool isTty()

Checks if the TTY mode is enabled.

Return Value

bool	true if the TTY mode is enabled, false otherwise

Process setPty(bool $bool)

Sets PTY mode.

Parameters

bool

$bool

Return Value

Process

bool isPty()

Returns PTY state.

Return Value

bool

string|null getWorkingDirectory()

Gets the working directory.

Return Value

string|null

The current working directory or null on failure

Process setWorkingDirectory(string $cwd)

Sets the current working directory.

Parameters

string

$cwd

The new working directory

Return Value

Process

The current Process instance

array getEnv()

Gets the environment variables.

Return Value

array

The current environment variables

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. If it is false or null, it will be removed when env vars are otherwise inherited.

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

resource|string|Iterator|null getInput()

Gets the Process input.

Return Value

resource|string|Iterator|null

The Process input

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

array getOptions() ^deprecated

^deprecated

since version 3.3, to be removed in 4.0.

Gets the options for proc_open.

Return Value

array

The current options

Process setOptions(array $options) ^deprecated

^deprecated

since version 3.3, to be removed in 4.0.

Sets the options for proc_open.

Parameters

array

$options

The new options

Return Value

Process

The current Process instance

bool getEnhanceWindowsCompatibility() ^deprecated

^deprecated

since version 3.3, to be removed in 4.0. Enhanced Windows compatibility will always be enabled.

Gets whether or not Windows compatibility is enabled.

This is true by default.

Return Value

bool

Process setEnhanceWindowsCompatibility(bool $enhance) ^deprecated

^deprecated

since version 3.3, to be removed in 4.0. Enhanced Windows compatibility will always be enabled.

Sets whether or not Windows compatibility is enabled.

Parameters

bool

$enhance

Return Value

Process

The current Process instance

bool getEnhanceSigchildCompatibility() ^deprecated

^deprecated

since version 3.3, to be removed in 4.0. Sigchild compatibility will always be enabled.

Returns whether sigchild compatibility mode is activated or not.

Return Value

bool

Process setEnhanceSigchildCompatibility(bool $enhance) ^deprecated

^deprecated

since version 3.3, to be removed in 4.0.

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

Process inheritEnvironmentVariables(bool $inheritEnv = true)

Sets whether environment variables will be inherited or not.

Parameters

bool

$inheritEnv

Return Value

Process

The current Process instance

bool areEnvironmentVariablesInherited() ^deprecated

^deprecated

since version 3.3, to be removed in 4.0. Environment variables will always be inherited.

Returns whether environment variables will be inherited or not.

Return Value

bool

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

static bool isPtySupported()

Returns whether PTY is supported on the current operating system.

Return Value

bool