Copied!

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

Cloneable Instantiable Iterable
Constants
public Symfony\Component\Process\Process ::ERR = 'err'
public Symfony\Component\Process\Process ::ITER_KEEP_OUTPUT = 2
public Symfony\Component\Process\Process ::ITER_NON_BLOCKING = 1
public Symfony\Component\Process\Process ::ITER_SKIP_ERR = 8
public Symfony\Component\Process\Process ::ITER_SKIP_OUT = 4
public Symfony\Component\Process\Process ::OUT = 'out'
public Symfony\Component\Process\Process ::STATUS_READY = 'ready'
public Symfony\Component\Process\Process ::STATUS_STARTED = 'started'
public Symfony\Component\Process\Process ::STATUS_TERMINATED = 'terminated'
public Symfony\Component\Process\Process ::STDERR = 2
public Symfony\Component\Process\Process ::STDIN = 0
public Symfony\Component\Process\Process ::STDOUT = 1
public Symfony\Component\Process\Process ::TIMEOUT_PRECISION = 0.2
Properties
public static $exitCodes = [ 'OK' , 'General error' , 'Misuse of shell builtins' , 126 => 'Invoked command cannot execute' , 127 => 'Command not found' , 128 => 'Invalid exit argument' , 129 => 'Hangup' , 130 => 'Interrupt' , 131 => 'Quit and dump core' , 132 => 'Illegal instruction' , 133 => 'Trace/breakpoint trap' , 134 => 'Process aborted' , 135 => 'Bus error: "access to undefined portion of memory object"' , 136 => 'Floating point exception: "erroneous arithmetic operation"' , 137 => 'Kill (terminate immediately)' , 138 => 'User-defined 1' , 139 => 'Segmentation violation' , 140 => 'User-defined 2' , 141 => 'Write to pipe with no one reading' , 142 => 'Signal raised by alarm' , 143 => 'Termination (request to terminate)' , 145 => 'Child process terminated, stopped (or continued*)' , 146 => 'Continue if stopped' , 147 => 'Stop executing temporarily' , 148 => 'Terminal stop signal' , 149 => 'Background process attempting to read from tty ("in")' , 150 => 'Background process attempting to write to tty ("out")' , 151 => 'Urgent data available on socket' , 152 => 'CPU time limit exceeded' , 153 => 'File size limit exceeded' , 154 => 'Signal raised by timer counting virtual time: "virtual timer expired"' , 155 => 'Profiling timer expired' , 157 => 'Pollable event' , 159 => 'Bad syscall' ]
 

Exit codes translation table.

User-defined errors must use exit codes in the 64-113 range.

Methods
public __clone ()
public __construct ( array $command , ? string $cwd = NULL , ? array $env = NULL , $input = NULL , ? float $timeout = 60 )
 
  • throws LogicException When proc_open is not installed
public __destruct ()
public addErrorOutput ( string $line )
 

Adds a line to the STDERR stream.

  • internal
public addOutput ( string $line )
 

Adds a line to the STDOUT stream.

  • internal
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

  • throws ProcessTimedOutException In case the timeout was reached
public clearErrorOutput ()
 

Clears the process output.

  • return $this
public clearOutput ()
 

Clears the process output.

  • return $this
public disableOutput ()
 

Disables fetching output and error output from the underlying process.

  • return $this
  • throws RuntimeException In case the process is already running
  • throws LogicException if an idle timeout is set
public enableOutput ()
 

Enables fetching output and error output from the underlying process.

  • return $this
  • throws RuntimeException In case the process is already running
public static fromShellCommandline ( string $command , ? string $cwd = NULL , ? array $env = NULL , $input = NULL , ? float $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]);

  • return static
  • throws LogicException When proc_open is not installed
public getCommandLine ()
 

Gets the command line to be executed.

  • return string The command to execute
public getEnv ()
 

Gets the environment variables.

  • return array The current environment variables
public getErrorOutput ()
 

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

  • return string The process error output
  • throws LogicException in case the output has been disabled
  • throws LogicException In case the process is not started
public getExitCode ()
 

Returns the exit code returned by the process.

  • return int | null The exit status code, null if the Process is not terminated
public 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 string | null A string representation for the exit status code, null if the Process is not terminated
  • see http://tldp.org/LDP/abs/html/exitcodes.html
  • see http://en.wikipedia.org/wiki/Unix_signal
public getIdleTimeout ()
 

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

  • return float | null The timeout in seconds or null if it's disabled
public 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 string The process error output since the last call
  • throws LogicException in case the output has been disabled
  • throws LogicException In case the process is not started
public 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 string The process output since the last call
  • throws LogicException in case the output has been disabled
  • throws LogicException In case the process is not started
public getInput ()
 

Gets the Process input.

  • return resource | string | Iterator | null The Process input
public getIterator ( int $flags = 0 )
 

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

  • throws LogicException in case the output has been disabled
  • throws LogicException In case the process is not started
  • return Generator
public getLastOutputTime () : float
 

Gets the last output time in seconds.

  • return float | null The last output time in seconds or null if it isn't started
public getOutput ()
 

Returns the current output of the process (STDOUT).

  • return string The process output
  • throws LogicException in case the output has been disabled
  • throws LogicException In case the process is not started
public getPid ()
 

Returns the Pid (process identifier), if applicable.

  • return int | null The process id if running, null otherwise
public getStartTime () : float
 
  • throws LogicException in case process is not started
public getStatus ()
 

Gets the process status.

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

  • return string The current process status
public 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 int
  • throws LogicException In case the process is not terminated
public 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 int
  • throws RuntimeException In case --enable-sigchild is activated
  • throws LogicException In case the process is not terminated
public getTimeout ()
 

Gets the process timeout (max. runtime).

  • return float | null The timeout in seconds or null if it's disabled
public getWorkingDirectory ()
 

Gets the working directory.

  • return string | null The current working directory or null on failure
public hasBeenSignaled ()
 

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

It always returns false on Windows.

  • return bool
  • throws LogicException In case the process is not terminated
public hasBeenStopped ()
 

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

It always returns false on Windows.

  • return bool
  • throws LogicException In case the process is not terminated
public isOutputDisabled ()
 

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

  • return bool
public isPty ()
 

Returns PTY state.

  • return bool
public static isPtySupported ()
 

Returns whether PTY is supported on the current operating system.

  • return bool
public isRunning ()
 

Checks if the process is currently running.

  • return bool true if the process is currently running, false otherwise
public isStarted ()
 

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

  • return bool true if status is ready, false otherwise
public isSuccessful ()
 

Checks if the process ended successfully.

  • return bool true if the process ended successfully, false otherwise
public isTerminated ()
 

Checks if the process is terminated.

  • return bool true if process is terminated, false otherwise
public isTty ()
 

Checks if the TTY mode is enabled.

  • return bool true if the TTY mode is enabled, false otherwise
public static isTtySupported () : bool
 

Returns whether TTY is supported on the current operating system.

public mustRun ( ? callable $callback = NULL , array $env = [ ] ) : self
 

Runs the process.

This is identical to run() except that an exception is thrown if the process
exits with a non-zero exit code.

  • return $this
  • throws ProcessFailedException if the process didn't terminate successfully
  • final
public restart ( ? callable $callback = NULL , array $env = [ ] ) : self
 

Restarts the process.

Be warned that the process is cloned before being started.

  • return static
  • throws RuntimeException When process can't be launched
  • throws RuntimeException When process is already running
  • see \start()
  • final
public run ( ? callable $callback = NULL , array $env = [ ] ) : int
 

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.

  • return int The exit status code
  • throws RuntimeException When process can't be launched
  • throws RuntimeException When process is already running
  • throws ProcessTimedOutException When process timed out
  • throws ProcessSignaledException When process stopped after receiving signal
  • throws LogicException In case a callback is provided and output has been disabled
  • final
public 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.

  • return $this
public setIdleTimeout ( ? float $timeout )
 

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

To disable the timeout, set this value to null.

  • return $this
  • throws LogicException if the output is disabled
  • throws InvalidArgumentException if the timeout is negative
public setInput ( $input )
 

Sets the input.

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

  • return $this
  • throws LogicException In case the process is running
public setOptions ( array $options )
 

Defines options to pass to the underlying proc_open().

  • see https://php.net/proc_openfor the options supported by PHP. Enabling the "create_new_console" option allows a subprocess to continue to run after the main process exited, on both Windows and *nix
public setPty ( bool $bool )
 

Sets PTY mode.

  • return $this
public setTimeout ( ? float $timeout )
 

Sets the process timeout (max. runtime) in seconds.

To disable the timeout, set this value to null.

  • return $this
  • throws InvalidArgumentException if the timeout is negative
public setTty ( bool $tty )
 

Enables or disables the TTY mode.

  • return $this
  • throws RuntimeException In case the TTY mode is not supported
public setWorkingDirectory ( string $cwd )
 

Sets the current working directory.

  • return $this
public signal ( int $signal )
 

Sends a POSIX signal to the process.

  • return $this
  • throws LogicException In case the process is not running
  • throws RuntimeException In case --enable-sigchild is activated and the process can't be killed
  • throws RuntimeException In case of failure
public 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.

  • throws RuntimeException When process can't be launched
  • throws RuntimeException When process is already running
  • throws LogicException In case a callback is provided and output has been disabled
public stop ( float $timeout = 10 , ? int $signal = NULL )
 

Stops the process.

  • return int | null The exit-code of the process or null if it's not running
public 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.

  • return int The exitcode of the process
  • throws ProcessTimedOutException When process timed out
  • throws ProcessSignaledException When process stopped after receiving signal
  • throws LogicException When process is not yet started
public waitUntil ( callable $callback ) : bool
 

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.

  • throws RuntimeException When process timed out
  • throws LogicException When process is not yet started
  • throws ProcessTimedOutException In case the timeout was reached
Methods
protected 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.

  • return Closure A PHP closure
protected isSigchildEnabled ()
 

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

  • return bool
protected updateStatus ( bool $blocking )
 

Updates the status of the process, reads pipes.

Properties
private $callback
private $commandline
private $cwd
private $env
private $exitcode
private $fallbackStatus
private $hasCallback
private $idleTimeout
private $incrementalErrorOutputOffset
private $incrementalOutputOffset
private $input
private $lastOutputTime
private $latestSignal
private $options
private $outputDisabled
private $process
private $processInformation
private $processPipes
 
  • var PipesInterface
private $pty
private static $sigchild
private $starttime
private $status
private $stderr
private $stdout
private $timeout
private $tty
private $useFileHandles
Methods
private close () : int
 

Closes process resource, closes file handles, sets the exitcode.

  • return int The exitcode
private doSignal ( int $signal , bool $throwException ) : bool
 

Sends a POSIX signal to the process.

  • return bool True if the signal was sent successfully, false otherwise
  • throws LogicException In case the process is not running
  • throws RuntimeException In case --enable-sigchild is activated and the process can't be killed
  • throws RuntimeException In case of failure
private escapeArgument ( ? string $argument ) : string
 

Escapes a string to be used as a shell argument.

private getDefaultEnv () : array
private getDescriptors () : array
 

Creates the descriptors needed by the proc_open.

private prepareWindowsCommandLine ( string $cmd , array $env ) : string
private readPipes ( bool $blocking , bool $close )
 

Reads pipes, executes callback.

private readPipesForOutput ( string $caller , bool $blocking = false )
 

Reads pipes for the freshest output.

  • throws LogicException in case output has been disabled or process is not started
private replacePlaceholders ( string $commandline , array $env )
private requireProcessIsStarted ( string $functionName )
 

Ensures the process is running or terminated, throws a LogicException if the process has a not started.

  • throws LogicException if the process has not run
private requireProcessIsTerminated ( string $functionName )
 

Ensures the process is terminated, throws a LogicException if the process has a status different than "terminated".

  • throws LogicException if the process is not yet terminated
private resetProcessData ()
 

Resets data related to the latest run of the process.

private validateTimeout ( ? float $timeout ) : float
 

Validates and returns the filtered timeout.

  • throws InvalidArgumentException if the given timeout is a negative number
Properties
public static $exitCodes = [ 'OK' , 'General error' , 'Misuse of shell builtins' , 126 => 'Invoked command cannot execute' , 127 => 'Command not found' , 128 => 'Invalid exit argument' , 129 => 'Hangup' , 130 => 'Interrupt' , 131 => 'Quit and dump core' , 132 => 'Illegal instruction' , 133 => 'Trace/breakpoint trap' , 134 => 'Process aborted' , 135 => 'Bus error: "access to undefined portion of memory object"' , 136 => 'Floating point exception: "erroneous arithmetic operation"' , 137 => 'Kill (terminate immediately)' , 138 => 'User-defined 1' , 139 => 'Segmentation violation' , 140 => 'User-defined 2' , 141 => 'Write to pipe with no one reading' , 142 => 'Signal raised by alarm' , 143 => 'Termination (request to terminate)' , 145 => 'Child process terminated, stopped (or continued*)' , 146 => 'Continue if stopped' , 147 => 'Stop executing temporarily' , 148 => 'Terminal stop signal' , 149 => 'Background process attempting to read from tty ("in")' , 150 => 'Background process attempting to write to tty ("out")' , 151 => 'Urgent data available on socket' , 152 => 'CPU time limit exceeded' , 153 => 'File size limit exceeded' , 154 => 'Signal raised by timer counting virtual time: "virtual timer expired"' , 155 => 'Profiling timer expired' , 157 => 'Pollable event' , 159 => 'Bad syscall' ]
 

Exit codes translation table.

User-defined errors must use exit codes in the 64-113 range.

private static $sigchild
Methods
public static fromShellCommandline ( string $command , ? string $cwd = NULL , ? array $env = NULL , $input = NULL , ? float $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]);

  • return static
  • throws LogicException When proc_open is not installed
public static isPtySupported ()
 

Returns whether PTY is supported on the current operating system.

  • return bool
public static isTtySupported () : bool
 

Returns whether TTY is supported on the current operating system.

© 2020 Bruce Wells
Search Namespaces \ Classes
Configuration Numbers (0-9.) only