Documentation

Process extends EventEmitter
in package

Process component.

This class borrows logic from Symfony's Process component for ensuring compatibility when PHP is compiled with the --enable-sigchild option.

This class also implements the EventEmitterInterface which allows you to react to certain events:

exit event: The exit event will be emitted whenever the process is no longer running. Event listeners will receive the exit code and termination signal as two arguments:

```php
$process = new Process('sleep 10');
$process->start();

$process->on('exit', function ($code, $term) {
    if ($term === null) {
        echo 'exit with code ' . $code . PHP_EOL;
    } else {
        echo 'terminated with signal ' . $term . PHP_EOL;
    }
});
```

Note that `$code` is `null` if the process has terminated, but the exit
code could not be determined (for example
[sigchild compatibility](#sigchild-compatibility) was disabled).
Similarly, `$term` is `null` unless the process has terminated in response to
an uncaught signal sent to it.
This is not a limitation of this project, but actual how exit codes and signals
are exposed on POSIX systems, for more details see also
[here](https://unix.stackexchange.com/questions/99112/default-exit-code-when-process-is-terminated).

It's also worth noting that process termination depends on all file descriptors
being closed beforehand.
This means that all [process pipes](#stream-properties) will emit a `close`
event before the `exit` event and that no more `data` events will arrive after
the `exit` event.
Accordingly, if either of these pipes is in a paused state (`pause()` method
or internally due to a `pipe()` call), this detection may not trigger.

Table of Contents

Properties

$pipes  : array<string|int, ReadableStreamInterface|WritableStreamInterface|DuplexStreamInterface>
Array with all process pipes (once started)
$stderr  : ReadableStreamInterface|null|DuplexStreamInterface|WritableStreamInterface
$stdin  : WritableStreamInterface|null|DuplexStreamInterface|ReadableStreamInterface
$stdout  : ReadableStreamInterface|null|DuplexStreamInterface|WritableStreamInterface
$listeners  : mixed
$onceListeners  : mixed
$cmd  : mixed
$cwd  : mixed
$enhanceSigchildCompatibility  : mixed
$env  : mixed
$exitCode  : mixed
$fallbackExitCode  : mixed
$fds  : mixed
$process  : mixed
$sigchild  : mixed
$sigchildPipe  : mixed
$status  : mixed
$stopSignal  : mixed
$termSignal  : mixed

Methods

__construct()  : mixed
Constructor.
close()  : mixed
Close the process.
emit()  : mixed
getCommand()  : string
Get the command string used to launch the process.
getExitCode()  : int|null
Get the exit code returned by the process.
getPid()  : int|null
Get the process ID.
getStopSignal()  : int|null
Get the signal that caused the process to stop its execution.
getTermSignal()  : int|null
Get the signal that caused the process to terminate its execution.
isRunning()  : bool
Return whether the process is still running.
isSigchildEnabled()  : bool
Return whether PHP has been compiled with the '--enable-sigchild' option.
isStopped()  : bool
Return whether the process has been stopped by a signal.
isTerminated()  : bool
Return whether the process has been terminated by an uncaught signal.
listeners()  : array<string|int, mixed>
on()  : mixed
once()  : mixed
removeAllListeners()  : mixed
removeListener()  : mixed
setSigchildEnabled()  : void
Enable or disable sigchild compatibility mode.
start()  : mixed
Start the process.
terminate()  : bool
Terminate the process with an optional signal.
closeExitCodePipe()  : mixed
Close the fourth pipe used to relay an exit code.
getCachedStatus()  : array<string|int, mixed>
Return the cached process status.
getFreshStatus()  : array<string|int, mixed>
Return the updated process status.
pollExitCodePipe()  : mixed
Check the fourth pipe for an exit code.
updateStatus()  : mixed
Update the process status, stop/term signals, and exit code.

Properties

$pipes

Array with all process pipes (once started)

public array<string|int, ReadableStreamInterface|WritableStreamInterface|DuplexStreamInterface> $pipes = array()

Unless explicitly configured otherwise during construction, the following standard I/O pipes will be assigned by default:

  • 0: STDIN (WritableStreamInterface)
  • 1: STDOUT (ReadableStreamInterface)
  • 2: STDERR (ReadableStreamInterface)

$enhanceSigchildCompatibility

private mixed $enhanceSigchildCompatibility

$fallbackExitCode

private mixed $fallbackExitCode

$sigchild

private static mixed $sigchild

$sigchildPipe

private mixed $sigchildPipe

$stopSignal

private mixed $stopSignal

$termSignal

private mixed $termSignal

Methods

__construct()

Constructor.

public __construct(string $cmd[, null|string $cwd = null ][, null|array<string|int, mixed> $env = null ][, null|array<string|int, mixed> $fds = null ]) : mixed
Parameters
$cmd : string

Command line to run

$cwd : null|string = null

Current working directory or null to inherit

$env : null|array<string|int, mixed> = null

Environment variables or null to inherit

$fds : null|array<string|int, mixed> = null

File descriptors to allocate for this process (or null = default STDIO streams)

Tags
throws
LogicException

On windows or when proc_open() is not installed

close()

Close the process.

public close() : mixed

This method should only be invoked via the periodic timer that monitors the process state.

emit()

public emit(mixed $event[, array<string|int, mixed> $arguments = [] ]) : mixed
Parameters
$event : mixed
$arguments : array<string|int, mixed> = []

getCommand()

Get the command string used to launch the process.

public getCommand() : string
Return values
string

getExitCode()

Get the exit code returned by the process.

public getExitCode() : int|null

This value is only meaningful if isRunning() has returned false. Null will be returned if the process is still running.

Null may also be returned if the process has terminated, but the exit code could not be determined (e.g. sigchild compatibility was disabled).

Return values
int|null

getPid()

Get the process ID.

public getPid() : int|null
Return values
int|null

getStopSignal()

Get the signal that caused the process to stop its execution.

public getStopSignal() : int|null

This value is only meaningful if isStopped() has returned true. Null will be returned if the process was never stopped.

Return values
int|null

getTermSignal()

Get the signal that caused the process to terminate its execution.

public getTermSignal() : int|null

This value is only meaningful if isTerminated() has returned true. Null will be returned if the process was never terminated.

Return values
int|null

isRunning()

Return whether the process is still running.

public isRunning() : bool
Return values
bool

isSigchildEnabled()

Return whether PHP has been compiled with the '--enable-sigchild' option.

public final static isSigchildEnabled() : bool
Tags
see
Process::isSigchildEnabled()
Return values
bool

isStopped()

Return whether the process has been stopped by a signal.

public isStopped() : bool
Return values
bool

isTerminated()

Return whether the process has been terminated by an uncaught signal.

public isTerminated() : bool
Return values
bool

listeners()

public listeners([mixed $event = null ]) : array<string|int, mixed>
Parameters
$event : mixed = null
Return values
array<string|int, mixed>

on()

public on(mixed $event, callable $listener) : mixed
Parameters
$event : mixed
$listener : callable

once()

public once(mixed $event, callable $listener) : mixed
Parameters
$event : mixed
$listener : callable

removeAllListeners()

public removeAllListeners([mixed $event = null ]) : mixed
Parameters
$event : mixed = null

removeListener()

public removeListener(mixed $event, callable $listener) : mixed
Parameters
$event : mixed
$listener : callable

setSigchildEnabled()

Enable or disable sigchild compatibility mode.

public final static setSigchildEnabled(bool $sigchild) : void

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
$sigchild : bool

start()

Start the process.

public start([LoopInterface|null $loop = null ][, float $interval = 0.1 ]) : mixed

After the process is started, the standard I/O streams will be constructed and available via public properties.

This method takes an optional LoopInterface|null $loop parameter that can be used to pass the event loop instance to use for this process. You can use a null value here in order to use the default loop. This value SHOULD NOT be given unless you're sure you want to explicitly use a given event loop instance.

Parameters
$loop : LoopInterface|null = null

Loop interface for stream construction

$interval : float = 0.1

Interval to periodically monitor process state (seconds)

Tags
throws
RuntimeException

If the process is already running or fails to start

terminate()

Terminate the process with an optional signal.

public terminate([int $signal = null ]) : bool
Parameters
$signal : int = null

Optional signal (default: SIGTERM)

Return values
bool —

Whether the signal was sent successfully

closeExitCodePipe()

Close the fourth pipe used to relay an exit code.

private closeExitCodePipe() : mixed

This should only be used if --enable-sigchild compatibility was enabled.

getCachedStatus()

Return the cached process status.

private getCachedStatus() : array<string|int, mixed>
Return values
array<string|int, mixed>

getFreshStatus()

Return the updated process status.

private getFreshStatus() : array<string|int, mixed>
Return values
array<string|int, mixed>

pollExitCodePipe()

Check the fourth pipe for an exit code.

private pollExitCodePipe() : mixed

This should only be used if --enable-sigchild compatibility was enabled.

updateStatus()

Update the process status, stop/term signals, and exit code.

private updateStatus() : mixed

Stop/term signals are only updated if the process is currently stopped or signaled, respectively. Otherwise, signal values will remain as-is so the corresponding getter methods may be used at a later point in time.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results