1. class
  2. Nette
  3. \
  4. Utils
  5. \
  6. Process

Process

final class Process

Represents a process, which can be started and controlled (reading output, writing input, waiting for completion).

Constants

private PollInterval

private DefaultTimeout

private StdIn

private StdOut

private StdErr

Methods

static Process
runExecutable(string $executable, array $arguments = [], array|null $env = null, array $options = [], mixed $stdin = '', mixed $stdout = null, mixed $stderr = null, string|null $directory = null, float|null $timeout = self::DefaultTimeout)

Starts an executable with given arguments. Because the arguments are passed as an array, the shell is never involved, so they need no escaping and there is no risk of shell injection.

static Process
runCommand(string $command, array|null $env = null, array $options = [], mixed $stdin = '', mixed $stdout = null, mixed $stderr = null, string|null $directory = null, float|null $timeout = self::DefaultTimeout)

Starts a process from a command string interpreted by the shell (/bin/sh on POSIX, cmd.exe on Windows).

__destruct()

No description

bool
isRunning()

Checks if the process is currently running.

void
wait(Closure|null $callback = null)

Finishes the process by waiting for its completion. While waiting, the captured output is read continuously and kept in memory; an optional callback is invoked with each new output/error chunk.

void
terminate()

Terminates the running process if it is still running.

int
getExitCode()

Returns the process exit code. If the process is still running, waits until it finishes.

bool
isSuccess()

Returns true if the process terminated with exit code 0.

void
ensureSuccess()

Waits for the process to finish and throws ProcessFailedException if exit code is not zero.

int|null
getPid()

Returns the PID of the running process, or null if it is not running.

string
getStdOutput()

Waits for the process to finish and returns everything it wrote to STDOUT.

string
getStdError()

Waits for the process to finish and returns everything it wrote to STDERR.

string
consumeStdOutput()

Returns the STDOUT data produced since the previous consumeStdOutput() call.

string
consumeStdError()

Returns the STDERR data produced since the previous consumeStdError() call. See consumeStdOutput().

void
writeStdInput(string $string)

Writes data into the process' STDIN. If STDIN is closed, throws exception.

void
closeStdInput()

Closes the STDIN pipe, indicating no more data will be sent.

Details

at line 63
static Process runExecutable(string $executable, array $arguments = [], array|null $env = null, array $options = [], mixed $stdin = '', mixed $stdout = null, mixed $stderr = null, string|null $directory = null, float|null $timeout = self::DefaultTimeout)

Starts an executable with given arguments. Because the arguments are passed as an array, the shell is never involved, so they need no escaping and there is no risk of shell injection.

Parameters

string $executable

Path to the executable binary.
array $arguments

Arguments passed to the executable.
array|null $env

Environment variables or null to use the same environment as the current process.
array $options

Additional options for proc_open(). On Windows the executable is launched directly, without cmd.exe.
mixed $stdin

Input: string, a readable resource (its content is copied to STDIN), a Process (its STDOUT is piped in), or null (STDIN stays open for writeStdInput()).
mixed $stdout

Output target: string filename, a writable resource backed by a real OS file descriptor (not php://memory etc.), false to discard, or null to capture into memory.
mixed $stderr

Error output target (same options as $stdout).
string|null $directory

Working directory.
float|null $timeout

Time limit in seconds, checked while waiting for or reading the process; null disables it.

Return Value

Process

at line 91
static Process runCommand(string $command, array|null $env = null, array $options = [], mixed $stdin = '', mixed $stdout = null, mixed $stderr = null, string|null $directory = null, float|null $timeout = self::DefaultTimeout)

Starts a process from a command string interpreted by the shell (/bin/sh on POSIX, cmd.exe on Windows).

Because the shell parses the string, NEVER pass unescaped user input here - use runExecutable() for that.

Parameters

string $command

Shell command to run.
array|null $env

Environment variables or null to use the same environment as the current process.
array $options

Options for proc_open(), e.g. ['bypass_shell' => true] on Windows to skip cmd.exe.
mixed $stdin

Input: string, a readable resource (its content is copied to STDIN), a Process (its STDOUT is piped in), or null (STDIN stays open for writeStdInput()).
mixed $stdout

Output target: string filename, a writable resource backed by a real OS file descriptor (not php://memory etc.), false to discard, or null to capture into memory.
mixed $stderr

Error output target (same options as $stdout).
string|null $directory

Working directory.
float|null $timeout

Time limit in seconds, checked while waiting for or reading the process; null disables it.

Return Value

Process

at line 149
__destruct()

No description

at line 159
bool isRunning()

Checks if the process is currently running.

Return Value

bool

at line 180
void wait(Closure|null $callback = null)

Finishes the process by waiting for its completion. While waiting, the captured output is read continuously and kept in memory; an optional callback is invoked with each new output/error chunk.

Parameters

Closure|null $callback

Return Value

void

at line 208
void terminate()

Terminates the running process if it is still running.

Return Value

void

at line 225
int getExitCode()

Returns the process exit code. If the process is still running, waits until it finishes.

Return Value

int

at line 235
bool isSuccess()

Returns true if the process terminated with exit code 0.

Return Value

bool

at line 244
void ensureSuccess()

Waits for the process to finish and throws ProcessFailedException if exit code is not zero.

Return Value

void

at line 256
int|null getPid()

Returns the PID of the running process, or null if it is not running.

Return Value

int|null

at line 265
string getStdOutput()

Waits for the process to finish and returns everything it wrote to STDOUT.

Return Value

string

at line 275
string getStdError()

Waits for the process to finish and returns everything it wrote to STDERR.

Return Value

string

at line 287
string consumeStdOutput()

Returns the STDOUT data produced since the previous consumeStdOutput() call.

To read everything incrementally, poll while ($p->isRunning()) calling this, then call it once more after the loop; that last call returns whatever the process wrote just before the loop noticed it had exited.

Return Value

string

at line 296
string consumeStdError()

Returns the STDERR data produced since the previous consumeStdError() call. See consumeStdOutput().

Return Value

string

at line 334
void writeStdInput(string $string)

Writes data into the process' STDIN. If STDIN is closed, throws exception.

Parameters

string $string

Return Value

void

at line 362
void closeStdInput()

Closes the STDIN pipe, indicating no more data will be sent.

Return Value

void