class PhpProcess extends Process

PhpProcess runs a PHP script in an independent process.

$p = new PhpProcess(''); $p->run(); print $p->getOutput()."\n";

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 $exitCodes Exit codes translation table. from Process

Methods

__construct(string $script, string $cwd = null, array $env = null, float|null $timeout = 60, array $php = null)

No description

static 
fromShellCommandline(string $command, string $cwd = null, array $env = null, mixed|null $input = null, float|null $timeout = 60)

Creates a Process instance as a command-line to be run in a shell wrapper.

from Process
__destruct()

No description

from Process
__clone()

No description

from Process
int
run(callable $callback = null, array $env = [])

Runs the process.

from Process
mustRun(callable $callback = null, array $env = [])

Runs the process.

from Process
start(callable $callback = null, array $env = [])

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

$this
restart(callable $callback = null, array $env = [])

Restarts the process.

from Process
int
wait(callable $callback = null)

Waits for the process to terminate.

from Process
bool
waitUntil(callable $callback)

Waits until the callback returns true.

from Process
int|null
getPid()

Returns the Pid (process identifier), if applicable.

from Process
$this
signal(int $signal)

Sends a POSIX signal to the process.

from Process
$this
disableOutput()

Disables fetching output and error output from the underlying process.

from Process
$this
enableOutput()

Enables fetching output and error output from the underlying process.

from Process
bool
isOutputDisabled()

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

from Process
string
getOutput()

Returns the current output of the process (STDOUT).

from Process
string
getIncrementalOutput()

Returns the output incrementally.

from Process
getIterator(int $flags = 0)

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

from Process
$this
clearOutput()

Clears the process output.

from Process
string
getErrorOutput()

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

from Process
string
getIncrementalErrorOutput()

Returns the errorOutput incrementally.

from Process
$this
clearErrorOutput()

Clears the process output.

from Process
int|null
getExitCode()

Returns the exit code returned by the process.

from Process
string|null
getExitCodeText()

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

from Process
bool
isSuccessful()

Checks if the process ended successfully.

from Process
bool
hasBeenSignaled()

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

from Process
int
getTermSignal()

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

from Process
bool
hasBeenStopped()

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

from Process
int
getStopSignal()

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

from Process
bool
isRunning()

Checks if the process is currently running.

from Process
bool
isStarted()

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

from Process
bool
isTerminated()

Checks if the process is terminated.

from Process
string
getStatus()

Gets the process status.

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

Stops the process.

from Process
addOutput(string $line)

Adds a line to the STDOUT stream.

from Process
addErrorOutput(string $line)

Adds a line to the STDERR stream.

from Process
string
getCommandLine()

Gets the command line to be executed.

from Process
setCommandLine(string|array $commandline) deprecated

Sets the command line to be executed.

from Process
float|null
getTimeout()

Gets the process timeout (max. runtime).

from Process
float|null
getIdleTimeout()

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

from Process
setTimeout(int|float|null $timeout)

Sets the process timeout (max. runtime).

from Process
setIdleTimeout(int|float|null $timeout)

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

from Process
setTty(bool $tty)

Enables or disables the TTY mode.

from Process
bool
isTty()

Checks if the TTY mode is enabled.

from Process
setPty(bool $bool)

Sets PTY mode.

from Process
bool
isPty()

Returns PTY state.

from Process
string|null
getWorkingDirectory()

Gets the working directory.

from Process
setWorkingDirectory(string $cwd)

Sets the current working directory.

from Process
array
getEnv()

Gets the environment variables.

from Process
setEnv(array $env)

Sets the environment variables.

from Process
resource|string|Iterator|null
getInput()

Gets the Process input.

from Process
setInput(string|int|float|bool|resource|Traversable|null $input)

Sets the input.

from Process
inheritEnvironmentVariables(bool $inheritEnv = true)

Sets whether environment variables will be inherited or not.

from Process
checkTimeout()

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

from Process
static bool
isTtySupported()

Returns whether TTY is supported on the current operating system.

from Process
static bool
isPtySupported()

Returns whether PTY is supported on the current operating system.

from Process
buildCallback(callable $callback = null)

Builds up the callback used by wait().

from Process
updateStatus(bool $blocking)

Updates the status of the process, reads pipes.

from Process
bool
isSigchildEnabled()

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

from Process
setPhpBinary($php) deprecated

Sets the path to the PHP binary to use.

Details

at line 34
__construct(string $script, string $cwd = null, array $env = null, float|null $timeout = 60, array $php = null)

Parameters

string $script The PHP script to run (as a string)
string $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
float|null $timeout The timeout in seconds or null to disable
array $php Path to the PHP binary to use with any additional arguments

in Process at line 191
static fromShellCommandline(string $command, string $cwd = null, array $env = null, mixed|null $input = null, float|null $timeout = 60)

Creates a Process instance as a command-line to be run in a shell wrapper.

Command-lines are parsed by the shell of your OS (/bin/sh on Unix-like, cmd.exe on Windows.) This allows using e.g. pipes or conditional execution. In this mode, signals are sent to the shell wrapper and not to your commands.

In order to inject dynamic values into command-lines, we strongly recommend using placeholders. This will save escaping values, which is not portable nor secure anyway:

$process = Process::fromShellCommandline('my_command "$MY_VAR"'); $process->run(null, ['MY_VAR' => $theValue]);

Parameters

string $command The command line to pass to the shell of the OS
string $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
float|null $timeout The timeout in seconds or null to disable

Exceptions

RuntimeException When proc_open is not installed

in Process at line 199
__destruct()

in Process at line 204
__clone()

in Process at line 231
int run(callable $callback = null, array $env = [])

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 $callback A PHP callback to run whenever there is some output available on STDOUT or STDERR
array $env An array of additional env vars to set when running the process

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

in Process at line 253
Process mustRun(callable $callback = null, array $env = [])

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
array $env An array of additional env vars to set when running the process

Return Value

Process

Exceptions

ProcessFailedException if the process didn't terminate successfully

at line 67
start(callable $callback = null, array $env = [])

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
array $env An array of additional env vars to set when running the process

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

in Process at line 374
$this restart(callable $callback = null, array $env = [])

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
array $env An array of additional env vars to set when running the process

Return Value

$this

Exceptions

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

See also

in Process at line 401
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

in Process at line 442
bool waitUntil(callable $callback)

Waits until the callback returns true.

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

Return Value

bool

Exceptions

RuntimeException When process timed out
LogicException When process is not yet started

in Process at line 482
int|null getPid()

Returns the Pid (process identifier), if applicable.

Return Value

int|null The process id if running, null otherwise

in Process at line 498
$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

in Process at line 513
$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

in Process at line 534
$this enableOutput()

Enables fetching output and error output from the underlying process.

Return Value

$this

Exceptions

RuntimeException In case the process is already running

in Process at line 550
bool isOutputDisabled()

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

Return Value

bool

in Process at line 563
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

in Process at line 585
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

in Process at line 609
Generator getIterator(int $flags = 0)

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

in Process at line 661
$this clearOutput()

Clears the process output.

Return Value

$this

in Process at line 678
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

in Process at line 701
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

in Process at line 720
$this clearErrorOutput()

Clears the process output.

Return Value

$this

in Process at line 734
int|null getExitCode()

Returns the exit code returned by the process.

Return Value

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

in Process at line 752
string|null 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|null A string representation for the exit status code, null if the Process is not terminated

See also

in Process at line 766
bool isSuccessful()

Checks if the process ended successfully.

Return Value

bool true if the process ended successfully, false otherwise

in Process at line 780
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

LogicException In case the process is not terminated

in Process at line 797
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

in Process at line 817
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

in Process at line 833
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

in Process at line 845
bool isRunning()

Checks if the process is currently running.

Return Value

bool true if the process is currently running, false otherwise

in Process at line 861
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

in Process at line 871
bool isTerminated()

Checks if the process is terminated.

Return Value

bool true if process is terminated, false otherwise

in Process at line 885
string getStatus()

Gets the process status.

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

Return Value

string The current process status

in Process at line 900
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

in Process at line 934
addOutput(string $line)

Adds a line to the STDOUT stream.

Parameters

string $line

in Process at line 948
addErrorOutput(string $line)

Adds a line to the STDERR stream.

Parameters

string $line

in Process at line 962
string getCommandLine()

Gets the command line to be executed.

Return Value

string The command to execute

in Process at line 976
Process setCommandLine(string|array $commandline) deprecated

deprecated since Symfony 4.2.

Sets the command line to be executed.

Parameters

string|array $commandline The command to execute

Return Value

Process The current Process instance

in Process at line 990
float|null getTimeout()

Gets the process timeout (max. runtime).

Return Value

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

in Process at line 1000
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

in Process at line 1016
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

in Process at line 1035
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

in Process at line 1055
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

in Process at line 1075
bool isTty()

Checks if the TTY mode is enabled.

Return Value

bool true if the TTY mode is enabled, false otherwise

in Process at line 1087
Process setPty(bool $bool)

Sets PTY mode.

Parameters

bool $bool

Return Value

Process

in Process at line 1099
bool isPty()

Returns PTY state.

Return Value

bool

in Process at line 1109
string|null getWorkingDirectory()

Gets the working directory.

Return Value

string|null The current working directory or null on failure

in Process at line 1127
Process setWorkingDirectory(string $cwd)

Sets the current working directory.

Parameters

string $cwd The new working directory

Return Value

Process The current Process instance

in Process at line 1139
array getEnv()

Gets the environment variables.

Return Value

array The current environment variables

in Process at line 1159
Process setEnv(array $env)

Sets the environment variables.

Each 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

in Process at line 1176
resource|string|Iterator|null getInput()

Gets the Process input.

Return Value

resource|string|Iterator|null The Process input

in Process at line 1192
Process setInput(string|int|float|bool|resource|Traversable|null $input)

Sets the input.

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

Parameters

string|int|float|bool|resource|Traversable|null $input The content

Return Value

Process The current Process instance

Exceptions

LogicException In case the process is running

in Process at line 1210
Process inheritEnvironmentVariables(bool $inheritEnv = true)

Sets whether environment variables will be inherited or not.

Parameters

bool $inheritEnv

Return Value

Process The current Process instance

in Process at line 1227
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

in Process at line 1249
static bool isTtySupported()

Returns whether TTY is supported on the current operating system.

Return Value

bool

in Process at line 1265
static bool isPtySupported()

Returns whether PTY is supported on the current operating system.

Return Value

bool

in Process at line 1307
protected Closure buildCallback(callable $callback = null)

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.

Parameters

callable $callback The user defined PHP callback

Return Value

Closure A PHP closure

in Process at line 1337
protected updateStatus(bool $blocking)

Updates the status of the process, reads pipes.

Parameters

bool $blocking Whether to use a blocking read call

in Process at line 1362
protected bool isSigchildEnabled()

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

Return Value

bool

at line 57
setPhpBinary($php) deprecated

deprecated since Symfony 4.2, use the $php argument of the constructor instead.

Sets the path to the PHP binary to use.

Parameters

$php