Process
class Process implements IteratorAggregate
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 |
|
ITER_NON_BLOCKING |
|
ITER_KEEP_OUTPUT |
|
ITER_SKIP_OUT |
|
ITER_SKIP_ERR |
|
Properties
static | $exitCodes | Exit codes translation table. |
Methods
No description
Creates a Process instance as a command-line to be run in a shell wrapper.
No description
No description
Runs the process.
Starts the process and returns after writing the input to STDIN.
Restarts the process.
Waits for the process to terminate.
Waits until the callback returns true.
Returns the Pid (process identifier), if applicable.
Sends a POSIX signal to the process.
Disables fetching output and error output from the underlying process.
Enables fetching output and error output from the underlying process.
Returns true in case the output is disabled, false otherwise.
Returns the current output of the process (STDOUT).
Returns the output incrementally.
Returns an iterator to the output of the process, with the output type as keys (Process::OUT/ERR).
Clears the process output.
Returns the current error output of the process (STDERR).
Returns the errorOutput incrementally.
Clears the process output.
Returns the exit code returned by the process.
Returns a string representation for the exit code returned by the process.
Checks if the process ended successfully.
Returns true if the child process has been terminated by an uncaught signal.
Returns the number of the signal that caused the child process to terminate its execution.
Returns true if the child process has been stopped by a signal.
Returns the number of the signal that caused the child process to stop its execution.
Checks if the process is currently running.
Checks if the process has been started with no regard to the current state.
Checks if the process is terminated.
Gets the process status.
Stops the process.
Adds a line to the STDOUT stream.
Adds a line to the STDERR stream.
Gets the command line to be executed.
Gets the process timeout (max. runtime).
Gets the process idle timeout (max. time since last output).
Sets the process timeout (max. runtime).
Sets the process idle timeout (max. time since last output).
Checks if the TTY mode is enabled.
Returns PTY state.
Gets the working directory.
Sets the current working directory.
Gets the environment variables.
Sets whether environment variables will be inherited or not.
Performs a check between the timeout definition and the time the process started.
Returns whether TTY is supported on the current operating system.
Returns whether PTY is supported on the current operating system.
Builds up the callback used by wait().
Updates the status of the process, reads pipes.
Returns whether PHP has been compiled with the '--enable-sigchild' option or not.
Details
__construct(array $command, string $cwd = null, array $env = null, mixed|null $input = null, float|null $timeout = 60)
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]);
int
run(callable $callback = null, array $env = array())
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.
Process
mustRun(callable $callback = null, array $env = array())
Runs the process.
This is identical to run() except that an exception is thrown if the process exits with a non-zero exit code.
start(callable $callback = null, array $env = array())
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.
$this
restart(callable $callback = null, array $env = array())
Restarts the process.
Be warned that the process is cloned before being started.
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.
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.
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.
Generator
getIterator(int $flags = 0)
Returns an iterator to the output of the process, with the output type as keys (Process::OUT/ERR).
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.
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.
bool
hasBeenSignaled()
Returns true if the child process has been terminated by an uncaught signal.
It always returns false on Windows.
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.
bool
hasBeenStopped()
Returns true if the child process has been stopped by a signal.
It always returns false on Windows.
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.
Process
setCommandLine(string|array $commandline)
deprecated
deprecated since Symfony 4.2.
Sets the command line to be executed.
Process
setTimeout(int|float|null $timeout)
Sets the process timeout (max. runtime).
To disable the timeout, set this value to null.
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.
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.
Process
setInput(string|int|float|bool|resource|Traversable|null $input)
Sets the input.
This content will be passed to the underlying process standard input.
Process
inheritEnvironmentVariables(bool $inheritEnv = true)
Sets whether environment variables will be inherited or not.
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
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.