PHP Class Symfony\Component\Process\Process

Author: Fabien Potencier ([email protected])
Show file Open project: symfony/process Class Usage Examples

Public Properties

Property Type Description
$exitCodes array User-defined errors must use exit codes in the 64-113 range.

Public Methods

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

Protected Methods

Method Description
buildCallback ( callable $callback = null ) : Closure Builds up the callback used by wait().
isSigchildEnabled ( ) : boolean Returns whether PHP has been compiled with the '--enable-sigchild' option or not.
updateStatus ( boolean $blocking ) Updates the status of the process, reads pipes.

Private Methods

Method Description
close ( ) : integer Closes process resource, closes file handles, sets the exitcode.
doSignal ( integer $signal, boolean $throwException ) : boolean Sends a POSIX signal to the process.
getDescriptors ( ) : array Creates the descriptors needed by the proc_open.
readPipes ( boolean $blocking, boolean $close ) Reads pipes, executes callback.
readPipesForOutput ( string $caller, boolean $blocking = false ) Reads pipes for the freshest output.
requireProcessIsStarted ( string $functionName ) Ensures the process is running or terminated, throws a LogicException if the process has a not started.
requireProcessIsTerminated ( string $functionName ) Ensures the process is terminated, throws a LogicException if the process has a status different than terminated.
resetProcessData ( ) Resets data related to the latest run of the process.
validateTimeout ( integer | float | null $timeout ) : float | null Validates and returns the filtered timeout.

Method Details

__clone() public method

public __clone ( )

__construct() public method

Constructor.
public __construct ( string $commandline, string | null $cwd = null, array $env = null, mixed | null $input = null, integer | float | 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 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 integer | float | null The timeout in seconds or null to disable
$options array An array of options for proc_open

__destruct() public method

public __destruct ( )

addErrorOutput() public method

Adds a line to the STDERR stream.
public addErrorOutput ( string $line )
$line string The line to append

addOutput() public method

Adds a line to the STDOUT stream.
public addOutput ( string $line )
$line string The line to append

areEnvironmentVariablesInherited() public method

Returns whether environment variables will be inherited or not.
public areEnvironmentVariablesInherited ( ) : boolean
return boolean

buildCallback() protected method

The callbacks adds all occurred output to the specific buffer and calls the user callback (if present) with the received output.
protected buildCallback ( callable $callback = null ) : Closure
$callback callable The user defined PHP callback
return Closure A PHP closure

checkTimeout() public method

In case you run a background process (with the start method), you should trigger this method regularly to ensure the process timeout
public checkTimeout ( )

clearErrorOutput() public method

Clears the process output.
public clearErrorOutput ( ) : Process
return Process

clearOutput() public method

Clears the process output.
public clearOutput ( ) : Process
return Process

disableOutput() public method

Disables fetching output and error output from the underlying process.
public disableOutput ( ) : Process
return Process

enableOutput() public method

Enables fetching output and error output from the underlying process.
public enableOutput ( ) : Process
return Process

getCommandLine() public method

Gets the command line to be executed.
public getCommandLine ( ) : string
return string The command to execute

getEnhanceSigchildCompatibility() public method

Returns whether sigchild compatibility mode is activated or not.
public getEnhanceSigchildCompatibility ( ) : boolean
return boolean

getEnhanceWindowsCompatibility() public method

This is true by default.
public getEnhanceWindowsCompatibility ( ) : boolean
return boolean

getEnv() public method

Gets the environment variables.
public getEnv ( ) : array
return array The current environment variables

getErrorOutput() public method

Returns the current error output of the process (STDERR).
public getErrorOutput ( ) : string
return string The process error output

getExitCode() public method

Returns the exit code returned by the process.
public getExitCode ( ) : null | integer
return null | integer The exit status code, null if the Process is not terminated

getExitCodeText() public method

This method relies on the Unix exit code status standardization and might not be relevant for other operating systems.
See also: http://tldp.org/LDP/abs/html/exitcodes.html
See also: http://en.wikipedia.org/wiki/Unix_signal
public getExitCodeText ( ) : null | string
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 getIdleTimeout ( ) : float | null
return float | null The timeout in seconds or null if it's disabled

getIncrementalErrorOutput() public method

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 getIncrementalErrorOutput ( ) : string
return string The process error output since the last call

getIncrementalOutput() public method

In comparison with the getOutput method which always return the whole output, this one returns the new output since the last call.
public getIncrementalOutput ( ) : string
return string The process output since the last call

getInput() public method

Gets the Process input.
public getInput ( ) : resource | string | Iterator | null
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 getIterator ( integer $flags ) : Generator
$flags integer A bit field of Process::ITER_* flags
return Generator

getOptions() public method

Gets the options for proc_open.
public getOptions ( ) : array
return array The current options

getOutput() public method

Returns the current output of the process (STDOUT).
public getOutput ( ) : string
return string The process output

getPid() public method

Returns the Pid (process identifier), if applicable.
public getPid ( ) : integer | null
return integer | null The process id if running, null otherwise

getStatus() public method

The status is one of: ready, started, terminated.
public getStatus ( ) : string
return string The current process status

getStopSignal() public method

It is only meaningful if hasBeenStopped() returns true.
public getStopSignal ( ) : integer
return integer

getTermSignal() public method

It is only meaningful if hasBeenSignaled() returns true.
public getTermSignal ( ) : integer
return integer

getTimeout() public method

Gets the process timeout (max. runtime).
public getTimeout ( ) : float | null
return float | null The timeout in seconds or null if it's disabled

getWorkingDirectory() public method

Gets the working directory.
public getWorkingDirectory ( ) : string | null
return string | null The current working directory or null on failure

hasBeenSignaled() public method

It always returns false on Windows.
public hasBeenSignaled ( ) : boolean
return boolean

hasBeenStopped() public method

It always returns false on Windows.
public hasBeenStopped ( ) : boolean
return boolean

inheritEnvironmentVariables() public method

Sets whether environment variables will be inherited or not.
public inheritEnvironmentVariables ( boolean $inheritEnv = true ) : self
$inheritEnv boolean
return self The current Process instance

isOutputDisabled() public method

Returns true in case the output is disabled, false otherwise.
public isOutputDisabled ( ) : boolean
return boolean

isPty() public method

Returns PTY state.
public isPty ( ) : boolean
return boolean

isPtySupported() public static method

Returns whether PTY is supported on the current operating system.
public static isPtySupported ( ) : boolean
return boolean

isRunning() public method

Checks if the process is currently running.
public isRunning ( ) : boolean
return boolean 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 isSigchildEnabled ( ) : boolean
return boolean

isStarted() public method

Checks if the process has been started with no regard to the current state.
public isStarted ( ) : boolean
return boolean true if status is ready, false otherwise

isSuccessful() public method

Checks if the process ended successfully.
public isSuccessful ( ) : boolean
return boolean true if the process ended successfully, false otherwise

isTerminated() public method

Checks if the process is terminated.
public isTerminated ( ) : boolean
return boolean true if process is terminated, false otherwise

isTty() public method

Checks if the TTY mode is enabled.
public isTty ( ) : boolean
return boolean true if the TTY mode is enabled, false otherwise

mustRun() public method

This is identical to run() except that an exception is thrown if the process exits with a non-zero exit code.
public mustRun ( callable $callback = null ) : self
$callback callable
return self

restart() public method

Be warned that the process is cloned before being started.
See also: start()
public restart ( callable $callback = null ) : Process
$callback callable A PHP callback to run whenever there is some output available on STDOUT or STDERR
return Process The new process

run() public method

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 run ( callable | null $callback = null ) : integer
$callback callable | null A PHP callback to run whenever there is some output available on STDOUT or STDERR
return integer The exit status code

setCommandLine() public method

Sets the command line to be executed.
public setCommandLine ( string $commandline ) : self
$commandline string The command to execute
return self The current Process instance

setEnhanceSigchildCompatibility() public method

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 setEnhanceSigchildCompatibility ( boolean $enhance ) : self
$enhance boolean
return self The current Process instance

setEnhanceWindowsCompatibility() public method

Sets whether or not Windows compatibility is enabled.
public setEnhanceWindowsCompatibility ( boolean $enhance ) : self
$enhance boolean
return self The current Process instance

setEnv() public method

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 setEnv ( array $env ) : self
$env array The new environment variables
return self The current Process instance

setIdleTimeout() public method

To disable the timeout, set this value to null.
public setIdleTimeout ( integer | float | null $timeout ) : self
$timeout integer | float | null The timeout in seconds
return self The current Process instance

setInput() public method

This content will be passed to the underlying process standard input.
public setInput ( resource | scalar | Traversable | null $input ) : self
$input resource | scalar | Traversable | null The content
return self The current Process instance

setOptions() public method

Sets the options for proc_open.
public setOptions ( array $options ) : self
$options array The new options
return self The current Process instance

setPty() public method

Sets PTY mode.
public setPty ( boolean $bool ) : self
$bool boolean
return self

setTimeout() public method

To disable the timeout, set this value to null.
public setTimeout ( integer | float | null $timeout ) : self
$timeout integer | float | null The timeout in seconds
return self The current Process instance

setTty() public method

Enables or disables the TTY mode.
public setTty ( boolean $tty ) : self
$tty boolean True to enabled and false to disable
return self The current Process instance

setWorkingDirectory() public method

Sets the current working directory.
public setWorkingDirectory ( string $cwd ) : self
$cwd string The new working directory
return self The current Process instance

signal() public method

Sends a POSIX signal to the process.
public signal ( integer $signal ) : Process
$signal integer A valid POSIX signal (see http://www.php.net/manual/en/pcntl.constants.php)
return Process

start() public method

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 start ( callable $callback = null )
$callback callable A PHP callback to run whenever there is some output available on STDOUT or STDERR

stop() public method

Stops the process.
public stop ( integer | float $timeout = 10, integer $signal = null ) : integer
$timeout integer | float The timeout in seconds
$signal integer A POSIX signal to send in case the process has not stop at timeout, default is SIGKILL (9)
return integer The exit-code of the process

updateStatus() protected method

Updates the status of the process, reads pipes.
protected updateStatus ( boolean $blocking )
$blocking boolean Whether to use a blocking read call

wait() public method

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 wait ( callable $callback = null ) : integer
$callback callable A valid PHP callback
return integer The exitcode of the process

Property Details

$exitCodes public static property

User-defined errors must use exit codes in the 64-113 range.
public static array $exitCodes
return array