Process

MMO\core\server · 1 symbol · generated 30 Sep 2026

class

Process

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

class MMO\core\server\Process implements IteratorAggregate, Stringable use MMO\core\classes\tPropertyGetter

Namespace: MMO\core\server
Implements: IteratorAggregate, Stringable
Uses traits: tPropertyGetter
Author: Fabien Potencier <fabien@symfony.com>, Romain Neutron <imprec@gmail.com>, Marc Mouret <marc@hydra-agency.com>

NOTE: adapted from Symfony's Process component. On non-Windows platforms, the command is run via a shell as `exec <command>` (see [`start`](https://mmoframework.fr/documentation/mmo.core/php/server/Process.md#process-start)) so that proc_open's process handle refers directly to the target program (not an intermediary shell) -- required for signals/kill/pid to actually target the right process. A direct, well-known consequence: `exec` REPLACES the shell, so it can only run ONE program -- shell builtins with no real executable backing them (e.g. bare `exit N`) and compound syntax (`cmd1; cmd2`, pipes, `&&`) don't work as a single Process command; wrap them in a real script (e.g. `#!/bin/sh` file) instead. Verified concretely: a real single-executable script correctly reports its exit code, stdout, and stderr; a bare `exit 7` command instead fails with exit code 127 ("command not found"), since `exit` has no standalone executable -- this is the exec-technique's known, intentional trade-off, not a bug.

$p = new Process('/path/to/script.sh'); $p->run(); echo $p->getOutput();

Index

	ITER_KEEP_OUTPUT
	ITER_NON_BLOCKING
	ITER_SKIP_ERR
	ITER_SKIP_OUT
	STATUS_READY
	STATUS_STARTED
	STATUS_TERMINATED
	STDERR
	STDOUT
	callback
	command
	cwd
	env
	exitcode
	fallbackStatus
	idleTimeout
	incrementalErrorOutputOffset
	incrementalOutputOffset
	info
	input
	lastOutputTime
	latestSignal
	outputDisabled
	process
	processPipes
	pty
	starttime
	status
	stderr
	stdout
	timeout
	tty
	addOutput($line, $type)	Adds a line to the STDOUT stream.
	buildCallback($callback)	Builds up the callback used by wait().
	checkTimeout()	Performs a check between the timeout definition and the time the process started.
	clearOutput($type)	Clears the process output.
	close()	Closes process resource, closes file handles, sets the exitcode.
	debugName()
	getExitCode()	Returns the exit code returned by the process.
	getIncrementalOutput($type)	Returns the output incrementally.
	getIterator($flags)	Returns an iterator to the output of the process, with the output type as keys (Process::OUT/ERR).
	getOutput($type)	Returns the current output of the process (STDOUT).
	getPid()	Returns the Pid (process identifier), if applicable.
	getStatus()	Gets the process status.
	getStopSignal()	Returns the number of the signal that caused the child process to stop its execution.
	getTermSignal()	Returns the number of the signal that caused the child process to terminate its execution.
	hasBeenSignaled()	Returns true if the child process has been terminated by an uncaught signal.
	hasBeenStopped()	Returns true if the child process has been stopped by a signal.
	isRunning()	Checks if the process is currently running.
	isStarted()	Checks if the process has been started with no regard to the current state.
	isSuccessful()	Checks if the process ended successfully.
	isTerminated()	Checks if the process is terminated.
	logErrors($logger, $logCommand)	Log the process's stderr output, if it has any, as a warning.
	readPipes($blocking, $close)	Reads pipes, executes callback.
	readPipesForOutput($blocking)	Reads pipes for the freshest output.
	reset()	Resets data related to the latest run of the process.
	restart($callback, $env)	Restarts the process.
	run($callback, $env)	Runs the process.
	setEnv($env)	Sets the environment variables.
	setIdleTimeout($timeout)	Sets the process idle timeout (max.
	setInput($input)	Sets the input.
	setOutputDisabled($disable)	Disables/Enables fetching output and error output from the underlying process.
	setPty($pty)	Sets PTY mode.
	setTimeout($timeout)	Sets the process timeout (max.
	setTty($tty)	Enables or disables the TTY mode.
	setWorkingDirectory($cwd)	Sets the current working directory.
	signal($signal, $throwException)	Sends a POSIX signal to the process.
	start($callback, $env)	Starts the process and returns after writing the input to STDIN.
	stop($timeout, $signal)	Stops the process.
	updateStatus($blocking)	Updates the status of the process, reads pipes.
	wait($callback)	Waits for the process to terminate.
	waitUntil($callback)	Waits until the callback returns true.
	__clone()	A clone is a fresh, not-yet-started process (its own run's output/status is not carried over -- see `reset`).
	__construct($command, $cwd, $env, $input, $timeout)
	__destruct()	Force-stops the process (if still running) when this object is garbage-collected, so it's never left running unattended.
	__get($key)	__get -- allow read access to a protected/private property from outside the class.
	__isset($key)	__isset
	__toString()

Constants9

ITER_KEEP_OUTPUT

const ITER_KEEP_OUTPUT = 2

ITER_NON_BLOCKING

const ITER_NON_BLOCKING = 1

ITER_SKIP_ERR

const ITER_SKIP_ERR = 8

ITER_SKIP_OUT

const ITER_SKIP_OUT = 4

STATUS_READY

const STATUS_READY = 0

STATUS_STARTED

const STATUS_STARTED = 1

STATUS_TERMINATED

const STATUS_TERMINATED = 2

STDERR

const STDERR = 2

STDOUT

const STDOUT = 1

Properties23

callback

protected $callback = null

command

protected string $command

Type: string

cwd

protected string $cwd

Type: string

env

protected ?array $env = null

Type: null | array

exitcode

protected ?int $exitcode = null

Type: null | int

fallbackStatus

protected array $fallbackStatus = []

Type: array

idleTimeout

protected ?float $idleTimeout = null

Type: null | float

incrementalErrorOutputOffset

protected int $incrementalErrorOutputOffset = 0

Type: int

incrementalOutputOffset

protected int $incrementalOutputOffset = 0

Type: int

info

protected ?array $info = null

Type: null | array

input

protected mixed $input

Type: mixed

lastOutputTime

protected ?float $lastOutputTime

Type: null | float

latestSignal

protected $latestSignal = null

outputDisabled

protected bool $outputDisabled = false

Type: bool

process

protected $process = null

processPipes

protected $processPipes = null

pty

protected bool $pty = false

Type: bool

starttime

protected ?float $starttime

Type: null | float

status

protected int $status = 0

Type: int

stderr

protected $stderr = null

stdout

protected $stdout = null

timeout

protected ?float $timeout

Type: null | float

tty

protected bool $tty = false

Type: bool

Methods46

addOutput($line, $type)

Process.php:1023

Adds a line to the STDOUT stream.

function addOutput(string $line, int $type = self::STDOUT)

$line	string
$type = self::STDOUT	int
returns

buildCallback($callback)

Process.php:181

Builds up the callback used by wait().

protected function buildCallback(?callable $callback = null)

The callbacks adds all occurred output to the specific buffer and calls the user callback (if present) with the received output.

$callback = null	null \| callable	The user defined PHP callback
returns		A PHP closure

checkTimeout()

Process.php:517

Performs a check between the timeout definition and the time the process started.

function checkTimeout()

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

returns
throws		In case the timeout was reached

clearOutput($type)

Process.php:952

Clears the process output.

function clearOutput(int $type = self::STDOUT)

$type = self::STDOUT	int
returns

close()

Process.php:232

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

protected function close(): int

returns

int

The exitcode

debugName()

Process.php:130

function debugName()

returns

getExitCode()

Process.php:772

Returns the exit code returned by the process.

function getExitCode(): ?int

returns

null | int

The exit status code, null if the Process is not terminated

getIncrementalOutput($type)

Process.php:934

Returns the output incrementally.

function getIncrementalOutput(int $type = self::STDOUT)

In comparison with the getOutput method which always return the whole output, this one returns the new output since the last call.

$type = self::STDOUT	int
returns		The process output since the last call
throws		in case the output has been disabled
throws		In case the process is not started

getIterator($flags)

Process.php:977

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

function getIterator(int $flags = 0): Traversable

$flags = 0	int	A bit field of Process::ITER_* flags
returns	Traversable
throws		in case the output has been disabled
throws		In case the process is not started

getOutput($type)

Process.php:917

Returns the current output of the process (STDOUT).

function getOutput(int $type = self::STDOUT)

$type = self::STDOUT	int
returns		The process output
throws		in case the output has been disabled
throws		In case the process is not started

getPid()

Process.php:903

Returns the Pid (process identifier), if applicable.

function getPid()

returns

The process id if running, null otherwise

getStatus()

Process.php:763

Gets the process status.

function getStatus(): int

returns

int

The current process status: one of the STATUS_* constants

getStopSignal()

Process.php:893

Returns the number of the signal that caused the child process to stop its execution.

function getStopSignal()

It is only meaningful if hasBeenStopped() returns true.

returns
throws		In case the process is not terminated

getTermSignal()

Process.php:846

Returns the number of the signal that caused the child process to terminate its execution.

function getTermSignal()

It is only meaningful if hasBeenSignaled() returns true.

returns
throws		In case --enable-sigchild is activated
throws		In case the process is not terminated

hasBeenSignaled()

Process.php:865

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

function hasBeenSignaled()

It always returns false on Windows.

returns
throws		In case the process is not terminated

hasBeenStopped()

Process.php:879

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

function hasBeenStopped()

It always returns false on Windows.

returns
throws		In case the process is not terminated

isRunning()

Process.php:807

Checks if the process is currently running.

function isRunning()

returns

true if the process is currently running, false otherwise

isStarted()

Process.php:819

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

function isStarted()

returns

true if status is ready, false otherwise

isSuccessful()

Process.php:798

Checks if the process ended successfully.

function isSuccessful()

returns

true if the process ended successfully, false otherwise

isTerminated()

Process.php:828

Checks if the process is terminated.

function isTerminated()

returns

true if process is terminated, false otherwise

logErrors($logger, $logCommand)

Process.php:140

Log the process's stderr output, if it has any, as a warning.

function logErrors(Psr\Log\LoggerInterface $logger, bool $logCommand = true)

$logger	`LoggerInterface`
$logCommand = true	bool	if true, append the command line itself to the logged message.
returns		the stderr output that was logged (empty if there was none).

readPipes($blocking, $close)

Process.php:212

Reads pipes, executes callback.

protected function readPipes(bool $blocking, bool $close)

$blocking	bool	Whether to use blocking calls or not
$close	bool	Whether to close file handles or not
returns

readPipesForOutput($blocking)

Process.php:199

Reads pipes for the freshest output.

protected function readPipesForOutput(bool $blocking = false)

$blocking = false	bool	Whether to use blocking calls or not
returns
throws		in case output has been disabled or process is not started

reset()

Process.php:156

Resets data related to the latest run of the process.

protected function reset()

returns

restart($callback, $env)

Process.php:547

Restarts the process.

function restart(?callable $callback = null, array $env = []): self

Be warned that the process is cloned before being started.

See: start()

$callback = null	null \| callable	A PHP callback to run whenever there is some output available on STDOUT or STDERR
$env = []	array
returns	self
throws		When process can't be launched
throws		When process is already running

run($callback, $env)

Process.php:419

Runs the process.

function run(?callable $callback = null, array $env = []): int

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.

$callback = null	null \| callable	A PHP callback to run whenever there is some output available on STDOUT or STDERR
$env = []	array
returns	int	The exit status code
throws		When process can't be launched
throws		When process is already running
throws		When process timed out
throws		When process stopped after receiving signal
throws		In case a callback is provided and output has been disabled

setEnv($env)

Process.php:268

Sets the environment variables.

function setEnv(?array $env)

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.

$env	null \| array	The new environment variables
returns

setIdleTimeout($timeout)

Process.php:389

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

function setIdleTimeout(?float $timeout)

To disable the timeout, set this value to null.

$timeout	null \| float
returns
throws		if the output is disabled
throws		if the timeout is negative

setInput($input)

Process.php:306

Sets the input.

function setInput($input)

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

$input		The content
returns
throws		In case the process is running
throws		In case the input is not of the correct type

setOutputDisabled($disable)

Process.php:357

Disables/Enables fetching output and error output from the underlying process.

function setOutputDisabled($disable)

$disable
returns
throws		In case the process is already running
throws		if an idle timeout is set

setPty($pty)

Process.php:328

Sets PTY mode.

function setPty(bool $pty)

$pty	bool
returns

setTimeout($timeout)

Process.php:373

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

function setTimeout(?float $timeout)

To disable the timeout, set this value to null or 0.

$timeout	null \| float
returns
throws		if the timeout is negative

setTty($tty)

Process.php:339

Enables or disables the TTY mode.

function setTty(bool $tty)

$tty	bool
returns
throws		in case the TTY mode is not supported

setWorkingDirectory($cwd)

Process.php:285

Sets the current working directory.

function setWorkingDirectory(?string $cwd)

$cwd	null \| string
returns

signal($signal, $throwException)

Process.php:692

Sends a POSIX signal to the process.

function signal(int $signal, bool $throwException = true): bool

$signal	int	A valid POSIX signal (see https://php.net/pcntl.constants)
$throwException = true	bool	Whether to throw exception in case signal failed
returns	bool	True if the signal was sent successfully, false otherwise
throws		In case the process is not running
throws		In case --enable-sigchild is activated and the process can't be killed
throws		In case of failure

start($callback, $env)

Process.php:444

Starts the process and returns after writing the input to STDIN.

function start(?callable $callback = null, array $env = []): void

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.

$callback = null	null \| callable	A PHP callback to run whenever there is some output available on STDOUT or STDERR
$env = []	array
returns	void
throws		When process can't be launched
throws		When process is already running
throws		In case a callback is provided and output has been disabled

stop($timeout, $signal)

Process.php:565

Stops the process.

function stop(float $timeout = 10.0, ?int $signal = null): int

$timeout = 10.0	float	The timeout in seconds
$signal = null	null \| int	A POSIX signal to send in case the process has not stop at timeout, default is SIGKILL (9)
returns	int	The exit-code of the process or null if it's not running

updateStatus($blocking)

Process.php:736

Updates the status of the process, reads pipes.

protected function updateStatus(bool $blocking): void

$blocking	bool	Whether to use a blocking read call
returns	void

wait($callback)

Process.php:607

Waits for the process to terminate.

function wait(?callable $callback = null): int

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.

$callback = null	null \| callable	A valid PHP callback
returns	int	The exitcode of the process
throws		When process timed out
throws		When process stopped after receiving signal
throws		When process is not yet started

waitUntil($callback)

Process.php:651

Waits until the callback returns true.

function waitUntil(callable $callback): bool

$callback	callable
returns	bool
throws		When process timed out
throws		When process is not yet started
throws		In case the timeout was reached

__clone()

Process.php:120

A clone is a fresh, not-yet-started process (its own run's output/status is not carried over -- see reset).

function __clone()

__construct($command, $cwd, $env, $input, $timeout)

Process.php:105

function __construct( string $command, ?string $cwd = null, ?array $env = null, $input = null, ?float $timeout = 60.0 )

$command	string	The command to run and its arguments listed as separate entries
$cwd = null	null \| string	The working directory or null to use the working dir of the current PHP process
$env = null	null \| array	The environment variables or null to use the same environment as the current PHP process
$input = null		The input as stream resource, scalar or \Traversable, or null for no input
$timeout = 60.0	null \| float	The timeout in seconds or null to disable
throws		When proc_open is not installed

__destruct()

Process.php:115

Force-stops the process (if still running) when this object is garbage-collected, so it's never left running unattended.

function __destruct()

__get($key)

tPropertyGetter.php:25

__get -- allow read access to a protected/private property from outside the class.

function __get($key)

$key
returns
throws		if no such property exists at all (a declared-but-uninitialized typed property is returned as-is here, and would raise PHP's own "must not be accessed before initialization" error, not this exception)

$thing->name; // 'Marc'

$thing->doesNotExist; // throws eNotFound

__isset($key)

tPropertyGetter.php:36

__isset

function __isset($key)

$key
returns

isset($thing->name); // true

__toString()

Process.php:125

function __toString(): string

returns

string

the raw command line.