Synchronous Execution

Purpose and Scope

This document covers synchronous (blocking) process execution using the run() method. Synchronous execution waits for a process to complete before returning control to the caller, providing immediate access to the complete output, error output, and exit code.

For non-blocking execution where the calling code continues while the process runs in the background, see Asynchronous Execution. For sequential chaining of multiple processes, see Process Pipes. For concurrent execution of multiple processes, see Process Pools.

Sources: src/PendingProcess.php212-230

---

Execution Overview

The run() method on PendingProcess performs synchronous process execution. It blocks execution until the process completes (or times out), then returns a ProcessResult containing the complete outcome.

Basic Flow Diagram

Sources: src/PendingProcess.php212-230 src/PendingProcess.php258-290

---

The run() Method

The run() method is defined on the PendingProcess class and accepts two optional parameters:

Parameter	Type	Description
$command	array|string|null	Override the configured command. If null, uses the previously configured command.
$output	callable|null	Callback invoked with output as the process runs. Receives output type and data.

Return Type: ProcessResultContract - A completed process result with full output, error output, and exit code.

Exceptions:

• ProcessTimedOutException - Thrown when the process exceeds its timeout or idle timeout
• RuntimeException - Thrown when attempting to run an un-faked process with stray prevention enabled

Method Signature

Sources: src/PendingProcess.php212-230

---

Command Resolution

The run() method resolves the command to execute in the following priority order:

1. The $command parameter passed to run()
2. The command previously configured on the PendingProcess instance via command()

If neither is provided, the toSymfonyProcess() method will receive null and must handle command resolution.

Sources: src/PendingProcess.php214

---

Output Callbacks

The optional $output callback parameter enables real-time processing of output as the process generates it. This is useful for long-running processes where you want to display progress or log output incrementally.

Callback Signature

The output callback receives two parameters:

Parameter	Type	Description
$type	string	Either Process::OUT (stdout) or Process::ERR (stderr)
$data	string	The output data chunk

Output Callback Flow

Example Output Callback Usage

When calling run() with an output callback, the callback is invoked for each output chunk:

Note: Output callbacks are passed directly to Symfony's Process::run() method, which handles the incremental output streaming.

Sources: src/PendingProcess.php212 src/PendingProcess.php226

---

ProcessResult Return Value

Upon successful completion (or controlled failure), run() returns a ProcessResult instance that implements ProcessResultContract. This object provides access to all process outcome information.

ProcessResult Interface

Method	Return Type	Description
command()	string	The command that was executed
successful()	bool	True if exit code is 0
failed()	bool	True if exit code is non-zero
exitCode()	int|null	The process exit code
output()	string	Complete standard output
errorOutput()	string	Complete error output
throw()	static	Throws ProcessFailedException if process failed
throwIf()	static	Conditionally throws exception based on boolean

Result Inspection Flow

For detailed information on working with process results, including error handling methods like throw() and throwIf(), see Process Results.

Sources: src/ProcessResult.php1-119

---

Timeout Handling

Synchronous execution respects the timeout configuration set on the PendingProcess instance. When a timeout occurs, Symfony throws a SymfonyTimeoutException, which is caught and wrapped in a ProcessTimedOutException.

Timeout Configuration Methods

Method	Parameter	Description
timeout(int $timeout)	$timeout	Maximum seconds the process may run (default: 60)
idleTimeout(int $timeout)	$timeout	Maximum seconds without output
forever()	None	Disables timeout (sets to null)

Timeout Exception Flow

The ProcessTimedOutException includes the ProcessResult for the incomplete process, allowing access to partial output collected before the timeout.

For comprehensive timeout handling details, including how to access partial output from timed-out processes, see Timeout Handling.

Sources: src/PendingProcess.php227-229 src/PendingProcess.php123-148

---

Real vs Fake Execution Paths

The run() method supports both real process execution and fake/test execution. The execution path is determined by checking for registered fake handlers.

Execution Path Decision Tree

Fake Handler Resolution

The fakeFor() method searches registered fake handlers (from both the Factory and the PendingProcess instance) to find a matching handler for the command:

1. Exact command match
2. Wildcard pattern match (using Str::is())
3. Global handler (pattern '*')

Stray Process Prevention

When preventingStrayProcesses() returns true and no fake handler is found, run() throws a RuntimeException to prevent accidental real process execution during tests. This ensures comprehensive test coverage of all process interactions.

For detailed information on the faking system, see Faking Overview. For stray process prevention, see Preventing Stray Processes.

Sources: src/PendingProcess.php217-224 src/PendingProcess.php307-311 src/PendingProcess.php318-338

---

Symfony Process Conversion

Before execution, the run() method converts the PendingProcess configuration into a Symfony Process instance via the toSymfonyProcess() method.

Configuration Mapping

The following PendingProcess properties are applied to the Symfony Process:

PendingProcess Property	Symfony Process Method	Notes
$command	Process constructor	Array creates Process, string uses fromShellCommandline()
$path	setWorkingDirectory()	Defaults to getcwd() if not set
$timeout	setTimeout()	Default 60 seconds, null for no timeout
$idleTimeout	setIdleTimeout()	Only applied if set
$environment	Constructor 3rd parameter	Merged with system environment
$input	setInput()	Standard input for the process
$quietly	disableOutput()	Prevents output capture
$tty	setTty(true)	Enables TTY mode
$options	setOptions()	Raw proc_open options

Conversion Flow

Sources: src/PendingProcess.php258-290

---

Complete Execution Flow

The following diagram shows the complete flow from run() invocation through result return, including all decision points and error paths:

Sources: src/PendingProcess.php212-230