Process
class Process
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 |
Properties
| static | $exitCodes | Exit codes translation table. |
Methods
| __construct(string $commandline, string|null $cwd = null, array $env = null, string|null $input = null, int|float|null $timeout = 60, array $options = array()) | ||
| __destruct() | ||
| __clone() | ||
| int | run(callable|null $callback = null) Runs the process. |
|
| Process | mustRun(callable|null $callback = null) Runs the process. |
|
| start(callable|null $callback = null) Starts the process and returns after writing the input to STDIN. |
||
| $this | restart(callable|null $callback = null) Restarts the process. |
|
| int | wait(callable|null $callback = null) Waits for the process to terminate. |
|
| int|null | getPid() Returns the Pid (process identifier), if applicable. |
|
| $this | signal(int $signal) Sends a POSIX signal to the process. |
|
| $this | disableOutput() Disables fetching output and error output from the underlying process. |
|
| $this | 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. |
|
| $this | clearOutput() Clears the process output. |
|
| string | getErrorOutput() Returns the current error output of the process (STDERR). |
|
| string | getIncrementalErrorOutput() Returns the errorOutput incrementally. |
|
| $this | 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. |
|
| Process | 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). |
|
| Process | setTimeout(int|float|null $timeout) Sets the process timeout (max. runtime). |
|
| Process | setIdleTimeout(int|float|null $timeout) Sets the process idle timeout (max. time since last output). |
|
| Process | setTty(bool $tty) Enables or disables the TTY mode. |
|
| bool | isTty() Checks if the TTY mode is enabled. |
|
| Process | setPty(bool $bool) Sets PTY mode. |
|
| bool | isPty() Returns PTY state. |
|
| string|null | 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|null | getStdin() deprecated Gets the contents of STDIN. |
|
| null|string | getInput() Gets the Process input. |
|
| Process | setStdin(string|null $stdin) deprecated Sets the contents of STDIN. |
|
| Process | setInput(mixed $input) Sets the input. |
|
| array | getOptions() Gets the options for proc_open. |
|
| Process | setOptions(array $options) Sets the options for proc_open. |
|
| bool | getEnhanceWindowsCompatibility() Gets whether or not Windows compatibility is enabled. |
|
| Process | setEnhanceWindowsCompatibility(bool $enhance) Sets whether or not Windows compatibility is enabled. |
|
| bool | getEnhanceSigchildCompatibility() Returns whether sigchild compatibility mode is activated or not. |
|
| Process | setEnhanceSigchildCompatibility(bool $enhance) Activates sigchild compatibility mode. |
|
| 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
__construct(string $commandline, string|null $cwd = null, array $env = null, string|null $input = null, int|float|null $timeout = 60, array $options = array())
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 |
| string|null | $input | The 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(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 |
Process mustRun(callable|null $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|null | $callback |
Return Value
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|null $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|null | $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 |
$this restart(callable|null $callback = null)
Restarts the process.
Be warned that the process is cloned before being started.
Parameters
| callable|null | $callback | A PHP callback to run whenever there is some output available on STDOUT or STDERR |
Return Value
| $this |
Exceptions
| RuntimeException | When process can't be launched |
| RuntimeException | When process is already running |
See also
| start() |
int wait(callable|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
| callable|null | $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 |
$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 $commandline)
Sets the command line to be executed.
Parameters
| string | $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
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.
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 |
string|null getStdin() deprecated
deprecated
since version 2.5, to be removed in 3.0. Use setInput() instead. This method is deprecated in favor of getInput.Gets the contents of STDIN.
Return Value
| string|null | The current contents |
null|string getInput()
Gets the Process input.
Return Value
| null|string | The Process input |
Process setStdin(string|null $stdin) deprecated
deprecated
since version 2.5, to be removed in 3.0. Use setInput() instead.Sets the contents of STDIN.
Parameters
| string|null | $stdin | The new contents |
Return Value
| Process | The current Process instance |
Exceptions
| LogicException | In case the process is running |
| InvalidArgumentException | In case the argument is invalid |
Process setInput(mixed $input)
Sets the input.
This content will be passed to the underlying process standard input.
Parameters
| mixed | $input | The content |
Return Value
| Process | The current Process instance |
Exceptions
| LogicException | In case the process is running Passing an object as an input is deprecated since version 2.5 and will be removed in 3.0. |
array getOptions()
Gets the options for proc_open.
Return Value
| array | The current options |
Process setOptions(array $options)
Sets the options for proc_open.
Parameters
| array | $options | The new options |
Return Value
| Process | The current Process instance |
bool getEnhanceWindowsCompatibility()
Gets whether or not Windows compatibility is enabled.
This is true by default.
Return Value
| bool |
Process setEnhanceWindowsCompatibility(bool $enhance)
Sets whether or not Windows compatibility is enabled.
Parameters
| bool | $enhance |
Return Value
| Process | The current Process instance |
bool getEnhanceSigchildCompatibility()
Returns whether sigchild compatibility mode is activated or not.
Return Value
| bool |
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 |
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 |
© 2004–2017 Fabien Potencier
Licensed under the MIT License.
http://api.symfony.com/2.8/Symfony/Component/Process/Process.html