Process Exceptions

This document details the exception types used by the hypervel/process package for handling process execution failures and timeouts. It covers the structure, properties, and message formatting of ProcessFailedException and ProcessTimedOutException, explaining when they are thrown and how to access process information from them.

For information about configuring timeouts and timeout detection mechanisms, see Timeout Handling.

Overview

The package provides two specialized exception classes for process errors:

Exception	Base Class	Purpose	Key Property
ProcessFailedException	RuntimeException	Thrown when a process exits with non-zero code	ProcessResult $result
ProcessTimedOutException	Symfony RuntimeException	Thrown when a process exceeds timeout limits	ProcessResult $result

Both exceptions preserve the complete ProcessResult instance, allowing access to command details, output, error output, and exit codes even after failure.

Exception Class Hierarchy

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

ProcessFailedException

The ProcessFailedException is thrown when a process completes execution but exits with a non-zero exit code, indicating failure. This exception is typically triggered by calling throw() or throwIf() methods on a ProcessResult instance.

Exception Construction

The exception is constructed with a ProcessResult instance and automatically generates a detailed error message:

Sources: src/Exceptions/ProcessFailedException.php20-39

Message Format

The exception message follows this structure:

1. Base message: src/Exceptions/ProcessFailedException.php24-28

   The command "{command}" failed.
   
   Exit Code: {exitCode}
   

2. Output section (if not empty): src/Exceptions/ProcessFailedException.php30-32

   
   Output:
   ================
   {output}
   

3. Error output section (if not empty): src/Exceptions/ProcessFailedException.php34-36

   
   Error Output:
   ================
   {errorOutput}
   

This comprehensive formatting makes the exception message self-contained for debugging, eliminating the need to separately inspect the result object.

Sources: src/Exceptions/ProcessFailedException.php24-36

Properties

Property	Type	Visibility	Description
$result	ProcessResult	public	The complete process result instance

The $result property provides access to all process information via the ProcessResultContract interface, including:

• command() - The executed command
• exitCode() - The process exit code
• output() - Standard output
• errorOutput() - Error output
• successful() - Whether exit code was 0
• failed() - Whether exit code was non-zero

Sources: src/Exceptions/ProcessFailedException.php12-15

ProcessTimedOutException

The ProcessTimedOutException is thrown when a process exceeds its configured timeout or idle timeout limit. This exception wraps Symfony's native ProcessTimedOutException while adding access to the partial ProcessResult.

Exception Construction

The exception wraps both the original Symfony timeout exception and the process result:

Sources: src/Exceptions/ProcessTimedOutException.php21-26

Properties

Property	Type	Visibility	Description
$result	ProcessResult	public	The process result with partial output

The stored result contains:

• Command: The full command that was executed
• Exit code: null (process was terminated, did not exit naturally)
• Output: Any output captured before timeout occurred
• Error output: Any error output captured before timeout occurred

This allows inspection of partial results even though the process did not complete successfully.

Sources: src/Exceptions/ProcessTimedOutException.php12-16

Symfony Integration

The exception constructor accepts and wraps the Symfony timeout exception: src/Exceptions/ProcessTimedOutException.php21-26

__construct(SymfonyTimeoutException $original, ProcessResult $result)

The Symfony exception is preserved as the previous exception via parent::__construct(), maintaining the exception chain. The original Symfony message is reused, which includes details about whether the timeout was a general timeout or an idle timeout.

Sources: src/Exceptions/ProcessTimedOutException.php8-9 src/Exceptions/ProcessTimedOutException.php21-26

Accessing Process Information from Exceptions

Both exception types provide public access to the process result, enabling detailed error handling:

Exception Handling Patterns

Pattern	Use Case	Access Pattern
Re-throw with context	Add application context	Access $e->result->command() for logging
Retry logic	Retry on specific exit codes	Check $e->result->exitCode()
Partial output extraction	Use incomplete output	Access $e->result->output() from timeout
Conditional handling	Different handling per command	Match $e->result->command()

Exit Code Usage

The ProcessFailedException uses the exit code from the result as the exception code: src/Exceptions/ProcessFailedException.php38

parent::__construct($error, $result->exitCode() ?? 1)

This allows catching exceptions and switching on specific exit codes:

• Exit code 0: Process succeeded (exception not thrown)
• Exit code 1: Default generic failure (used if exitCode() returns null)
• Exit codes 2-255: Command-specific error codes

The ProcessTimedOutException preserves the Symfony exception's code instead, as the process did not exit naturally.

Sources: src/Exceptions/ProcessFailedException.php38 src/Exceptions/ProcessTimedOutException.php25

Exception Code Entities

The following table maps exception classes to their locations in the codebase:

Class	Namespace	File
ProcessFailedException	Hypervel\Process\Exceptions	src/Exceptions/ProcessFailedException.php
ProcessTimedOutException	Hypervel\Process\Exceptions	src/Exceptions/ProcessTimedOutException.php

Both exceptions require the ProcessResult contract from: Hypervel\Process\Contracts\ProcessResult

Sources: src/Exceptions/ProcessFailedException.php5-10 src/Exceptions/ProcessTimedOutException.php5-11