Process Results

The ProcessResult class encapsulates the outcome of a completed process execution. It provides methods for inspecting exit codes, output streams, and handling process failures. The class implements the ProcessResultContract interface, enabling polymorphism between real process results and fake results used in testing.

ProcessResult wraps a Symfony Process instance and delegates all inspection methods to it. The wrapped process must have completed execution before the result instance is created.

Sources: src/ProcessResult.php11-119 src/Contracts/ProcessResult.php7-58

ProcessResult Contract

The ProcessResultContract interface defines the API for inspecting completed process outcomes. This contract enables polymorphism, allowing both real implementations (ProcessResult) and fake implementations (FakeProcessResult) to be used interchangeably.

Contract Structure

The contract defines three categories of methods:

Category	Methods	Purpose
Outcome Inspection	command(), exitCode(), output(), errorOutput()	Retrieve process execution data
Status Checking	successful(), failed(), seeInOutput(), seeInErrorOutput()	Evaluate process outcome
Error Handling	throw(), throwIf()	Conditionally raise exceptions for failures

Sources: src/Contracts/ProcessResult.php7-58

ProcessResult Implementation

The ProcessResult class provides the real implementation of ProcessResultContract by wrapping a Symfony Process instance.

Constructor and Internal State

The constructor accepts a Process parameter and stores it in the protected $process property. The passed process must have already completed execution—all output has been captured and the exit code is available.

Sources: src/ProcessResult.php11-20

Outcome Inspection Methods

These methods retrieve execution data from the completed process:

Command and Exit Code

Method	Return Type	Symfony Delegation	Description
command()	string	$process->getCommandLine()	Returns the full command string that was executed
exitCode()	?int	$process->getExitCode()	Returns the process exit code (0 for success, non-zero for failure, null if not started)

Sources: src/ProcessResult.php22-52

Output Streams

Method	Return Type	Symfony Delegation	Description
output()	string	$process->getOutput()	Returns all captured standard output (stdout)
errorOutput()	string	$process->getErrorOutput()	Returns all captured error output (stderr)

The output methods return the complete buffered content. If output was streamed during execution using callbacks, these methods return the accumulated buffer.

Sources: src/ProcessResult.php54-76

Status Checking Methods

These methods evaluate the process outcome:

Success and Failure Status

Method	Return Type	Implementation	Description
successful()	bool	$process->isSuccessful()	Returns true if exit code is 0
failed()	bool	!$this->successful()	Returns true if exit code is non-zero

Sources: src/ProcessResult.php30-44

Output Content Matching

Method	Return Type	Implementation	Description
seeInOutput(string)	bool	str_contains($this->output(), $output)	Returns true if stdout contains the given string
seeInErrorOutput(string)	bool	str_contains($this->errorOutput(), $output)	Returns true if stderr contains the given string

These convenience methods check for substring matches in the output streams, useful for validating expected output or detecting error messages.

Sources: src/ProcessResult.php62-84

Error Handling Methods

The ProcessResult class provides fluent methods for conditionally throwing exceptions when processes fail:

throw() Method

The throw() method:

1. Returns $this immediately if the process was successful (enabling fluent chaining)
2. Creates a ProcessFailedException instance if the process failed
3. Invokes the optional callback with the result and exception
4. Throws the exception

The callback parameter allows custom logging or error handling before the exception is thrown.

Sources: src/ProcessResult.php86-104

throwIf() Method

The throwIf(bool $condition, ?callable $callback) method conditionally invokes throw():

Condition	Behavior
$condition is true	Calls $this->throw($callback)
$condition is false	Returns $this without checking process status

This method enables conditional error handling based on application logic.

Sources: src/ProcessResult.php106-118

Exception Fluency

Both methods return static, enabling method chaining:

Result Creation

ProcessResult instances are created by two execution paths in the system:

Creation Flow Diagram

Synchronous Path

The PendingProcess::run() method executes a process synchronously:

1. Converts configuration to Symfony Process via toSymfonyProcess()
2. Calls $process->mustRun() to execute and block until completion
3. Wraps the completed process in new ProcessResult($process)
4. Returns the result immediately

This path provides blocking execution where run() does not return until the process completes.

Asynchronous Path

The PendingProcess::start() and InvokedProcess::wait() methods provide asynchronous execution:

1. start() calls $process->start() to begin execution without blocking
2. Wraps the running process in InvokedProcess
3. Application code can perform other work
4. Calling wait() on the invoked process blocks until completion
5. Wraps the completed process in new ProcessResult($process)

Both paths produce identical ProcessResult instances—the only difference is when blocking occurs.

Sources: src/PendingProcess.php162-209 src/InvokedProcess.php49-68 src/ProcessResult.php11-20

Integration with Process Lifecycle

ProcessResult is the terminal state in the process lifecycle, representing a completed execution:

Lifecycle Diagram

The ProcessResult class represents the final state after process execution completes. It is immutable—all inspection methods return data captured during execution. The result cannot be used to restart or modify the process.

Sources: src/PendingProcess.php162-209 src/InvokedProcess.php49-68 src/ProcessResult.php11-119

Usage Examples

Accessing Basic Process Information

Checking Process Status

Inspecting Process Output

Error Handling

Relationship with Other Components

ProcessResult is a core component in the Hypervel Process system that:

1. Is returned by the InvokedProcess when a process completes execution
2. Provides information used by ProcessFailedException when a process fails
3. Has a fake implementation (FakeProcessResult) for testing scenarios

Sources: src/Contracts/ProcessResult.php src/FakeProcessResult.php