Error Handling

Purpose and Scope

This document provides an overview of error handling mechanisms in the hypervel/process package. It covers the custom exception types used to represent process failures and timeouts, as well as the patterns for triggering and handling these exceptions through the ProcessResult API.

For detailed information about specific exception types, see Process Exceptions. For timeout-specific behavior and configuration, see Timeout Handling.

Overview

The package provides two custom exception types that extend standard PHP exceptions to encapsulate process failure information:

Exception Class	Base Class	Purpose
ProcessFailedException	RuntimeException	Thrown when a process completes with a non-zero exit code
ProcessTimedOutException	RuntimeException	Thrown when a process exceeds its configured timeout

Both exceptions maintain a reference to the ProcessResult instance, allowing exception handlers to inspect the process state, output, and error output even after failure.

Sources: src/Exceptions/ProcessFailedException.php10 src/Exceptions/ProcessTimedOutException.php11

Error Handling Architecture

Exception Creation Flow

The package distinguishes between two types of failures:

1. Explicit failures: Process completes with non-zero exit code. A ProcessResult is returned and user code decides whether to throw via throw() or throwIf()
2. Timeout failures: Process exceeds timeout. ProcessTimedOutException is thrown immediately during execution

Sources: src/ProcessResult.php91-104 src/Exceptions/ProcessFailedException.php20-39 src/Exceptions/ProcessTimedOutException.php21-26

Exception Integration with ProcessResult

Component Relationships

The ProcessResult class provides the primary interface for error handling through two methods:

Method	Signature	Behavior
throw()	throw(?callable $callback = null): static	Throws ProcessFailedException if the process failed; returns self if successful
throwIf()	throwIf(bool $condition, ?callable $callback = null): static	Conditionally throws based on provided boolean condition

Both methods accept an optional callback that receives the ProcessResult and ProcessFailedException before the exception is thrown, allowing for logging or custom error handling logic.

Sources: src/ProcessResult.php86-118 src/Exceptions/ProcessFailedException.php12-15 src/Exceptions/ProcessTimedOutException.php12-16

Error Handling Patterns

The package supports three primary patterns for handling process errors:

1. Automatic Exception on Failure

$result = Process::run('some-command')->throw();

This pattern immediately throws ProcessFailedException if the process fails, suitable for critical operations where failure should halt execution.

Implementation: src/ProcessResult.php91-104

2. Conditional Exception

$result = Process::run('some-command')->throwIf($isProduction);

This pattern conditionally throws based on runtime conditions, useful for environment-specific error handling.

Implementation: src/ProcessResult.php106-118

3. Manual Inspection

$result = Process::run('some-command');
if ($result->failed()) {
 // Handle error manually
}

This pattern provides full control over error handling logic by inspecting the result without throwing exceptions.

Implementation: src/ProcessResult.php32-44

Exception Information Structure

Both exception types provide access to the complete process state at the time of failure:

Accessing Process Information from Exceptions

When catching exceptions, the original ProcessResult is available via the result public property:

Exception Property	Type	Description
result	ProcessResult	Complete process result with all output and metadata
message	string	Formatted error message including command, exit code, and output
code	int	Exit code of the failed process (or 1 for timeout)

Sources: src/Exceptions/ProcessFailedException.php12-39 src/Exceptions/ProcessTimedOutException.php12-26

Exception Message Format

The ProcessFailedException constructs a detailed error message that includes:

1. The executed command
2. The exit code
3. Standard output (if non-empty)
4. Error output (if non-empty)

This structured format ensures that exception logs contain all necessary debugging information without requiring manual inspection of the result object.

Message Construction: src/Exceptions/ProcessFailedException.php24-36

Integration with Fake Processes

Both exception types work seamlessly with the faking system. Fake handlers can return Throwable instances to simulate process failures during testing. See Faking Overview for details on throwing exceptions from fake handlers.

Sources: src/Exceptions/ProcessFailedException.php1-41 src/Exceptions/ProcessTimedOutException.php1-28