Class Symfony\Component\Process\Process

InheritanceSymfony\Component\Process\Process
ImplementsIteratorAggregate
SubclassesSymfony\Component\Process\PhpProcess

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

Public Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
$exitCodes array Symfony\Component\Process\Process

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__clone() Symfony\Component\Process\Process
__construct() Constructor. Symfony\Component\Process\Process
__destruct() Symfony\Component\Process\Process
addErrorOutput() Adds a line to the STDERR stream. Symfony\Component\Process\Process
addOutput() Adds a line to the STDOUT stream. Symfony\Component\Process\Process
checkTimeout() Performs a check between the timeout definition and the time the process started. Symfony\Component\Process\Process
clearErrorOutput() Clears the process output. Symfony\Component\Process\Process
clearOutput() Clears the process output. Symfony\Component\Process\Process
disableOutput() Disables fetching output and error output from the underlying process. Symfony\Component\Process\Process
enableOutput() Enables fetching output and error output from the underlying process. Symfony\Component\Process\Process
getCommandLine() Gets the command line to be executed. Symfony\Component\Process\Process
getEnhanceSigchildCompatibility() Returns whether sigchild compatibility mode is activated or not. Symfony\Component\Process\Process
getEnhanceWindowsCompatibility() Gets whether or not Windows compatibility is enabled. Symfony\Component\Process\Process
getEnv() Gets the environment variables. Symfony\Component\Process\Process
getErrorOutput() Returns the current error output of the process (STDERR). Symfony\Component\Process\Process
getExitCode() Returns the exit code returned by the process. Symfony\Component\Process\Process
getExitCodeText() Returns a string representation for the exit code returned by the process. Symfony\Component\Process\Process
getIdleTimeout() Gets the process idle timeout (max. time since last output). Symfony\Component\Process\Process
getIncrementalErrorOutput() Returns the errorOutput incrementally. Symfony\Component\Process\Process
getIncrementalOutput() Returns the output incrementally. Symfony\Component\Process\Process
getInput() Gets the Process input. Symfony\Component\Process\Process
getIterator() Returns an iterator to the output of the process, with the output type as keys (Process::OUT/ERR). Symfony\Component\Process\Process
getOptions() Gets the options for proc_open. Symfony\Component\Process\Process
getOutput() Returns the current output of the process (STDOUT). Symfony\Component\Process\Process
getPid() Returns the Pid (process identifier), if applicable. Symfony\Component\Process\Process
getStatus() Gets the process status. Symfony\Component\Process\Process
getStopSignal() Returns the number of the signal that caused the child process to stop its execution. Symfony\Component\Process\Process
getTermSignal() Returns the number of the signal that caused the child process to terminate its execution. Symfony\Component\Process\Process
getTimeout() Gets the process timeout (max. runtime). Symfony\Component\Process\Process
getWorkingDirectory() Gets the working directory. Symfony\Component\Process\Process
hasBeenSignaled() Returns true if the child process has been terminated by an uncaught signal. Symfony\Component\Process\Process
hasBeenStopped() Returns true if the child process has been stopped by a signal. Symfony\Component\Process\Process
isOutputDisabled() Returns true in case the output is disabled, false otherwise. Symfony\Component\Process\Process
isPty() Returns PTY state. Symfony\Component\Process\Process
isPtySupported() Returns whether PTY is supported on the current operating system. Symfony\Component\Process\Process
isRunning() Checks if the process is currently running. Symfony\Component\Process\Process
isStarted() Checks if the process has been started with no regard to the current state. Symfony\Component\Process\Process
isSuccessful() Checks if the process ended successfully. Symfony\Component\Process\Process
isTerminated() Checks if the process is terminated. Symfony\Component\Process\Process
isTty() Checks if the TTY mode is enabled. Symfony\Component\Process\Process
mustRun() Runs the process. Symfony\Component\Process\Process
restart() Restarts the process. Symfony\Component\Process\Process
run() Runs the process. Symfony\Component\Process\Process
setCommandLine() Sets the command line to be executed. Symfony\Component\Process\Process
setEnhanceSigchildCompatibility() Activates sigchild compatibility mode. Symfony\Component\Process\Process
setEnhanceWindowsCompatibility() Sets whether or not Windows compatibility is enabled. Symfony\Component\Process\Process
setEnv() Sets the environment variables. Symfony\Component\Process\Process
setIdleTimeout() Sets the process idle timeout (max. time since last output). Symfony\Component\Process\Process
setInput() Sets the input. Symfony\Component\Process\Process
setOptions() Sets the options for proc_open. Symfony\Component\Process\Process
setPty() Sets PTY mode. Symfony\Component\Process\Process
setTimeout() Sets the process timeout (max. runtime). Symfony\Component\Process\Process
setTty() Enables or disables the TTY mode. Symfony\Component\Process\Process
setWorkingDirectory() Sets the current working directory. Symfony\Component\Process\Process
signal() Sends a POSIX signal to the process. Symfony\Component\Process\Process
start() Starts the process and returns after writing the input to STDIN. Symfony\Component\Process\Process
stop() Stops the process. Symfony\Component\Process\Process
wait() Waits for the process to terminate. Symfony\Component\Process\Process

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
buildCallback() Builds up the callback used by wait(). Symfony\Component\Process\Process
isSigchildEnabled() Returns whether PHP has been compiled with the '--enable-sigchild' option or not. Symfony\Component\Process\Process
updateStatus() Updates the status of the process, reads pipes. Symfony\Component\Process\Process

Property Details

$exitCodes public static property
public static array $exitCodes = [=> 'OK'=> 'General error'=> 'Misuse of shell builtins'126 => 'Invoked command cannot execute'127 => 'Command not found'128 => 'Invalid exit argument'129 => 'Hangup'130 => 'Interrupt'131 => 'Quit and dump core'132 => 'Illegal instruction'133 => 'Trace/breakpoint trap'134 => 'Process aborted'135 => 'Bus error: "access to undefined portion of memory object"'136 => 'Floating point exception: "erroneous arithmetic operation"'137 => 'Kill (terminate immediately)'138 => 'User-defined 1'139 => 'Segmentation violation'140 => 'User-defined 2'141 => 'Write to pipe with no one reading'142 => 'Signal raised by alarm'143 => 'Termination (request to terminate)'145 => 'Child process terminated, stopped (or continued*)'146 => 'Continue if stopped'147 => 'Stop executing temporarily'148 => 'Terminal stop signal'149 => 'Background process attempting to read from tty ("in")'150 => 'Background process attempting to write to tty ("out")'151 => 'Urgent data available on socket'152 => 'CPU time limit exceeded'153 => 'File size limit exceeded'154 => 'Signal raised by timer counting virtual time: "virtual timer expired"'155 => 'Profiling timer expired'157 => 'Pollable event'159 => 'Bad syscall']

Method Details

__clone() public method

public void __clone ( )
__construct() public method

Constructor.

public void __construct ( $commandline, $cwd null, array $env null, $input null, $timeout 60, array $options = [] )
$commandline string

The command line to run

$cwd string|null

The working directory or null to use the working dir of the current PHP process

$env array|null

The environment variables or null to use the same environment as the current PHP process

$input mixed|null

The input as stream resource, scalar or \Traversable, or null for no input

$timeout int|float|null

The timeout in seconds or null to disable

$options array

An array of options for proc_open

throws Symfony\Component\Process\Exception\RuntimeException

When proc_open is not installed

__destruct() public method

public void __destruct ( )
addErrorOutput() public method

Adds a line to the STDERR stream.

public void addErrorOutput ( $line )
$line string

The line to append

addOutput() public method

Adds a line to the STDOUT stream.

public void addOutput ( $line )
$line string

The line to append

buildCallback() protected method

Builds up the callback used by wait().

The callbacks adds all occurred output to the specific buffer and calls the user callback (if present) with the received output.

protected Closure buildCallback ( callable $callback null )
$callback callable|null

The user defined PHP callback

return Closure

A PHP closure

checkTimeout() public method

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

public void checkTimeout ( )
throws Symfony\Component\Process\Exception\ProcessTimedOutException

In case the timeout was reached

clearErrorOutput() public method

Clears the process output.

public Symfony\Component\Process\Process clearErrorOutput ( )
clearOutput() public method

Clears the process output.

public Symfony\Component\Process\Process clearOutput ( )
disableOutput() public method

Disables fetching output and error output from the underlying process.

public Symfony\Component\Process\Process disableOutput ( )
throws Symfony\Component\Process\Exception\RuntimeException

In case the process is already running

throws Symfony\Component\Process\Exception\LogicException

if an idle timeout is set

enableOutput() public method

Enables fetching output and error output from the underlying process.

public Symfony\Component\Process\Process enableOutput ( )
throws Symfony\Component\Process\Exception\RuntimeException

In case the process is already running

getCommandLine() public method

Gets the command line to be executed.

public string getCommandLine ( )
return string

The command to execute

getEnhanceSigchildCompatibility() public method

Returns whether sigchild compatibility mode is activated or not.

public bool getEnhanceSigchildCompatibility ( )
getEnhanceWindowsCompatibility() public method

Gets whether or not Windows compatibility is enabled.

This is true by default.

public bool getEnhanceWindowsCompatibility ( )
getEnv() public method

Gets the environment variables.

public array getEnv ( )
return array

The current environment variables

getErrorOutput() public method

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

public string getErrorOutput ( )
return string

The process error output

throws Symfony\Component\Process\Exception\LogicException

In case the process is not started

getExitCode() public method

Returns the exit code returned by the process.

public null|int getExitCode ( )
return null|int

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

throws Symfony\Component\Process\Exception\RuntimeException

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

getExitCodeText() public method

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.

See also:

public null|string getExitCodeText ( )
return null|string

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

getIdleTimeout() public method

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

public float|null getIdleTimeout ( )
return float|null

The timeout in seconds or null if it's disabled

getIncrementalErrorOutput() public method

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.

public string getIncrementalErrorOutput ( )
return string

The process error output since the last call

throws Symfony\Component\Process\Exception\LogicException

In case the process is not started

getIncrementalOutput() public method

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.

public string getIncrementalOutput ( )
return string

The process output since the last call

throws Symfony\Component\Process\Exception\LogicException

In case the process is not started

getInput() public method

Gets the Process input.

public resource|string|Iterator|null getInput ( )
return resource|string|Iterator|null

The Process input

getIterator() public method

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

public Generator getIterator ( $flags 0 )
$flags int

A bit field of Process::ITER_* flags

throws Symfony\Component\Process\Exception\LogicException

In case the process is not started

getOptions() public method

Gets the options for proc_open.

public array getOptions ( )
return array

The current options

getOutput() public method

Returns the current output of the process (STDOUT).

public string getOutput ( )
return string

The process output

throws Symfony\Component\Process\Exception\LogicException

In case the process is not started

getPid() public method

Returns the Pid (process identifier), if applicable.

public int|null getPid ( )
return int|null

The process id if running, null otherwise

getStatus() public method

Gets the process status.

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

public string getStatus ( )
return string

The current process status

getStopSignal() public method

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

It is only meaningful if hasBeenStopped() returns true.

public int getStopSignal ( )
throws Symfony\Component\Process\Exception\LogicException

In case the process is not terminated

getTermSignal() public method

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

It is only meaningful if hasBeenSignaled() returns true.

public int getTermSignal ( )
throws Symfony\Component\Process\Exception\RuntimeException

In case --enable-sigchild is activated

throws Symfony\Component\Process\Exception\LogicException

In case the process is not terminated

getTimeout() public method

Gets the process timeout (max. runtime).

public float|null getTimeout ( )
return float|null

The timeout in seconds or null if it's disabled

getWorkingDirectory() public method

Gets the working directory.

public string|null getWorkingDirectory ( )
return string|null

The current working directory or null on failure

hasBeenSignaled() public method

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

It always returns false on Windows.

public bool hasBeenSignaled ( )
throws Symfony\Component\Process\Exception\RuntimeException

In case --enable-sigchild is activated

throws Symfony\Component\Process\Exception\LogicException

In case the process is not terminated

hasBeenStopped() public method

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

It always returns false on Windows.

public bool hasBeenStopped ( )
throws Symfony\Component\Process\Exception\LogicException

In case the process is not terminated

isOutputDisabled() public method

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

public bool isOutputDisabled ( )
isPty() public method

Returns PTY state.

public bool isPty ( )
isPtySupported() public static method

Returns whether PTY is supported on the current operating system.

public static bool isPtySupported ( )
isRunning() public method

Checks if the process is currently running.

public bool isRunning ( )
return bool

True if the process is currently running, false otherwise

isSigchildEnabled() protected method

Returns whether PHP has been compiled with the '--enable-sigchild' option or not.

protected bool isSigchildEnabled ( )
isStarted() public method

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

public bool isStarted ( )
return bool

True if status is ready, false otherwise

isSuccessful() public method

Checks if the process ended successfully.

public bool isSuccessful ( )
return bool

True if the process ended successfully, false otherwise

isTerminated() public method

Checks if the process is terminated.

public bool isTerminated ( )
return bool

True if process is terminated, false otherwise

isTty() public method

Checks if the TTY mode is enabled.

public bool isTty ( )
return bool

True if the TTY mode is enabled, false otherwise

mustRun() public method

Runs the process.

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

public self mustRun ( callable $callback null )
$callback callable|null
throws Symfony\Component\Process\Exception\RuntimeException

if PHP was compiled with --enable-sigchild and the enhanced sigchild compatibility mode is not enabled

throws Symfony\Component\Process\Exception\ProcessFailedException

if the process didn't terminate successfully

restart() public method

Restarts the process.

Be warned that the process is cloned before being started.

See also start().

public Symfony\Component\Process\Process restart ( callable $callback null )
$callback callable|null

A PHP callback to run whenever there is some

                           output available on STDOUT or STDERR
return Symfony\Component\Process\Process

The new process

throws Symfony\Component\Process\Exception\RuntimeException

When process is already running

run() public method

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.

public int run ( $callback null )
$callback callable|null

A PHP callback to run whenever there is some

                           output available on STDOUT or STDERR
return int

The exit status code

throws Symfony\Component\Process\Exception\RuntimeException

When process stopped after receiving signal

throws Symfony\Component\Process\Exception\LogicException

In case a callback is provided and output has been disabled

setCommandLine() public method

Sets the command line to be executed.

public self setCommandLine ( $commandline )
$commandline string

The command to execute

return self

The current Process instance

setEnhanceSigchildCompatibility() public method

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

public self setEnhanceSigchildCompatibility ( $enhance )
$enhance bool
return self

The current Process instance

setEnhanceWindowsCompatibility() public method

Sets whether or not Windows compatibility is enabled.

public self setEnhanceWindowsCompatibility ( $enhance )
$enhance bool
return self

The current Process instance

setEnv() public method

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.

public self setEnv ( array $env )
$env array

The new environment variables

return self

The current Process instance

setIdleTimeout() public method

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

To disable the timeout, set this value to null.

public self setIdleTimeout ( $timeout )
$timeout int|float|null

The timeout in seconds

return self

The current Process instance

throws Symfony\Component\Process\Exception\LogicException

if the output is disabled

throws Symfony\Component\Process\Exception\InvalidArgumentException

if the timeout is negative

setInput() public method

Sets the input.

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

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

The content

return self

The current Process instance

throws Symfony\Component\Process\Exception\LogicException

In case the process is running

setOptions() public method

Sets the options for proc_open.

public self setOptions ( array $options )
$options array

The new options

return self

The current Process instance

setPty() public method

Sets PTY mode.

public self setPty ( $bool )
$bool bool
setTimeout() public method

Sets the process timeout (max. runtime).

To disable the timeout, set this value to null.

public self setTimeout ( $timeout )
$timeout int|float|null

The timeout in seconds

return self

The current Process instance

throws Symfony\Component\Process\Exception\InvalidArgumentException

if the timeout is negative

setTty() public method

Enables or disables the TTY mode.

public self setTty ( $tty )
$tty bool

True to enabled and false to disable

return self

The current Process instance

throws Symfony\Component\Process\Exception\RuntimeException

In case the TTY mode is not supported

setWorkingDirectory() public method

Sets the current working directory.

public self setWorkingDirectory ( $cwd )
$cwd string

The new working directory

return self

The current Process instance

signal() public method

Sends a POSIX signal to the process.

public Symfony\Component\Process\Process signal ( $signal )
$signal int

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

throws Symfony\Component\Process\Exception\LogicException

In case the process is not running

throws Symfony\Component\Process\Exception\RuntimeException

In case of failure

start() public method

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.

public void start ( callable $callback null )
$callback callable|null

A PHP callback to run whenever there is some

                           output available on STDOUT or STDERR
throws Symfony\Component\Process\Exception\RuntimeException

When process is already running

throws Symfony\Component\Process\Exception\LogicException

In case a callback is provided and output has been disabled

stop() public method

Stops the process.

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

The timeout in seconds

$signal int

A POSIX signal to send in case the process has not stop at timeout, default is SIGKILL (9)

return int

The exit-code of the process

updateStatus() protected method

Updates the status of the process, reads pipes.

protected void updateStatus ( $blocking )
$blocking bool

Whether to use a blocking read call

wait() public method

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.

public int wait ( callable $callback null )
$callback callable|null

A valid PHP callback

return int

The exitcode of the process

throws Symfony\Component\Process\Exception\RuntimeException

When process stopped after receiving signal

throws Symfony\Component\Process\Exception\LogicException

When process is not yet started