Symfony2 API
Class

Symfony\Component\Process\Process

class Process

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

Constants

ERR

OUT

STATUS_READY

STATUS_STARTED

STATUS_TERMINATED

STDIN

STDOUT

STDERR

TIMEOUT_PRECISION

Properties

static array $exitCodes Exit codes translation table.

Methods

__construct(string $commandline, string $cwd = null, array $env = null, string $stdin = null, integer $timeout = 60, array $options = array())

Constructor.
__destruct()

__clone()

integer run(callback|null $callback = null)

Runs the process.
start(callback|null $callback = null)

Starts the process and returns after sending the STDIN.
Process restart(callable $callback = null)

Restarts the process.
integer wait(callback|null $callback = null)

Waits for the process to terminate.
integer|null getPid()

Returns the Pid (process identifier), if applicable.
Process signal(integer $signal)

Sends a posix signal to the process.
string getOutput()

Returns the current output of the process (STDOUT).
string getIncrementalOutput()

Returns the output incrementally.
string getErrorOutput()

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

Returns the errorOutput incrementally.
integer getExitCode()

Returns the exit code returned by the process.
string getExitCodeText()

Returns a string representation for the exit code returned by the process.
Boolean isSuccessful()

Checks if the process ended successfully.
Boolean hasBeenSignaled()

Returns true if the child process has been terminated by an uncaught signal.
integer getTermSignal()

Returns the number of the signal that caused the child process to terminate its execution.
Boolean hasBeenStopped()

Returns true if the child process has been stopped by a signal.
integer getStopSignal()

Returns the number of the signal that caused the child process to stop its execution.
Boolean isRunning()

Checks if the process is currently running.
Boolean isStarted()

Checks if the process has been started with no regard to the current state.
Boolean isTerminated()

Checks if the process is terminated.
string getStatus()

Gets the process status.
integer stop(integer|float $timeout = 10, integer $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.
Process setCommandLine(string $commandline)

Sets the command line to be executed.
integer|null getTimeout()

Gets the process timeout.
Process setTimeout(float|null $timeout)

Sets the process timeout.
Process setTty(boolean $tty)

Enables or disables the TTY mode.
Boolean isTty()

Checks if the TTY mode is enabled.
string getWorkingDirectory()

Gets the working directory.
Process setWorkingDirectory(string $cwd)

Sets the current working directory.
array getEnv()

Gets the environment variables.
Process setEnv(array $env)

Sets the environment variables.
string getStdin()

Gets the contents of STDIN.
Process setStdin(string $stdin)

Sets the contents of STDIN.
array getOptions()

Gets the options for proc_open.
Process setOptions(array $options)

Sets the options for proc_open.
Boolean getEnhanceWindowsCompatibility()

Gets whether or not Windows compatibility is enabled.
Process setEnhanceWindowsCompatibility(Boolean $enhance)

Sets whether or not Windows compatibility is enabled.
Boolean getEnhanceSigchildCompatibility()

Returns whether sigchild compatibility mode is activated or not.
Process setEnhanceSigchildCompatibility(Boolean $enhance)

Activates sigchild compatibility mode.
checkTimeout()

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

Details

at line 132
public __construct(string $commandline, string $cwd = null, array $env = null, string $stdin = null, integer $timeout = 60, array $options = array())

Constructor.

Parameters

string $commandline The command line to run
string $cwd The working directory
array $env The environment variables or null to inherit
string $stdin The STDIN content
integer $timeout The timeout in seconds
array $options An array of options for proc_open

Exceptions

RuntimeException When proc_open is not installed

at line 164
public __destruct()

at line 170
public __clone()

at line 203
public integer run(callback|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

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

Return Value

integer The exit status code

Exceptions

RuntimeException When process can't be launch or is stopped

at line 231
public start(callback|null $callback = null)

Starts the process and returns after sending the 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.
If there is no callback passed, the wait() method can be called
with true as a second parameter then the callback will get all data occurred
in (and since) the start call.

Parameters

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

Exceptions

RuntimeException When process can't be launch or is stopped
RuntimeException When process is already running

at line 347
public 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 launch or is stopped
RuntimeException When process is already running

See also

start()

at line 373
public integer wait(callback|null $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

callback|null $callback A valid PHP callback

Return Value

integer The exitcode of the process

Exceptions

RuntimeException When process timed out
RuntimeException When process stopped after receiving signal

at line 465
public integer|null getPid()

Returns the Pid (process identifier), if applicable.

Return Value

integer|null The process id if running, null otherwise

Exceptions

RuntimeException In case --enable-sigchild is activated

at line 486
public Process signal(integer $signal)

Sends a posix signal to the process.

Parameters

integer $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
RuntimeException In case of failure

at line 510
public string getOutput()

Returns the current output of the process (STDOUT).

Return Value

string The process output

at line 525
public 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

at line 542
public string getErrorOutput()

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

Return Value

string The process error output

at line 558
public 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

at line 577
public integer getExitCode()

Returns the exit code returned by the process.

Return Value

integer The exit status code

Exceptions

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

at line 599
public 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

string A string representation for the exit status code

See also

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

at line 613
public Boolean isSuccessful()

Checks if the process ended successfully.

Return Value

Boolean true if the process ended successfully, false otherwise

at line 629
public Boolean hasBeenSignaled()

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

It always returns false on Windows.

Return Value

Boolean

Exceptions

RuntimeException In case --enable-sigchild is activated

at line 651
public integer 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

integer

Exceptions

RuntimeException In case --enable-sigchild is activated

at line 671
public Boolean hasBeenStopped()

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

It always returns false on Windows.

Return Value

Boolean

at line 687
public integer 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

integer

at line 699
public Boolean isRunning()

Checks if the process is currently running.

Return Value

Boolean true if the process is currently running, false otherwise

at line 715
public Boolean isStarted()

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

Return Value

Boolean true if status is ready, false otherwise

at line 725
public Boolean isTerminated()

Checks if the process is terminated.

Return Value

Boolean true if process is terminated, false otherwise

at line 739
public string getStatus()

Gets the process status.

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

Return Value

string The current process status

at line 756
public integer stop(integer|float $timeout = 10, integer $signal = null)

Stops the process.

Parameters

integer|float $timeout The timeout in seconds
integer $signal A posix signal to send in case the process has not stop at timeout, default is SIGKILL

Return Value

integer The exit-code of the process

Exceptions

RuntimeException if the process got signaled

at line 798
public addOutput(string $line)

Adds a line to the STDOUT stream.

Parameters

string $line The line to append

at line 808
public addErrorOutput(string $line)

Adds a line to the STDERR stream.

Parameters

string $line The line to append

at line 818
public string getCommandLine()

Gets the command line to be executed.

Return Value

string The command to execute

at line 830
public 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 842
public integer|null getTimeout()

Gets the process timeout.

Return Value

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

at line 858
public Process setTimeout(float|null $timeout)

Sets the process timeout.

To disable the timeout, set this value to null.

Parameters

float|null $timeout The timeout in seconds

Return Value

Process The current Process instance

Exceptions

InvalidArgumentException if the timeout is negative

at line 884
public Process setTty(boolean $tty)

Enables or disables the TTY mode.

Parameters

boolean $tty True to enabled and false to disable

Return Value

Process The current Process instance

at line 896
public Boolean isTty()

Checks if the TTY mode is enabled.

Return Value

Boolean true if the TTY mode is enabled, false otherwise

at line 906
public string getWorkingDirectory()

Gets the working directory.

Return Value

string The current working directory

at line 925
public 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 937
public array getEnv()

Gets the environment variables.

Return Value

array The current environment variables

at line 949
public Process setEnv(array $env)

Sets the environment variables.

Parameters

array $env The new environment variables

Return Value

Process The current Process instance

at line 961
public string getStdin()

Gets the contents of STDIN.

Return Value

string The current contents

at line 973
public Process setStdin(string $stdin)

Sets the contents of STDIN.

Parameters

string $stdin The new contents

Return Value

Process The current Process instance

at line 985
public array getOptions()

Gets the options for proc_open.

Return Value

array The current options

at line 997
public 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 1011
public Boolean getEnhanceWindowsCompatibility()

Gets whether or not Windows compatibility is enabled.

This is true by default.

Return Value

Boolean

at line 1023
public Process setEnhanceWindowsCompatibility(Boolean $enhance)

Sets whether or not Windows compatibility is enabled.

Parameters

Boolean $enhance

Return Value

Process The current Process instance

at line 1035
public Boolean getEnhanceSigchildCompatibility()

Returns whether sigchild compatibility mode is activated or not.

Return Value

Boolean

at line 1051
public Process setEnhanceSigchildCompatibility(Boolean $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

Boolean $enhance

Return Value

Process The current Process instance

at line 1066
public 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

RuntimeException In case the timeout was reached