 |
VOOZH | about |
|
VOOZH | about |
This document describes the two core contracts in the hypervel/process package: ProcessResult and InvokedProcess. These interfaces define stable APIs that enable the dual execution model, allowing both real system processes and fake test implementations to be used interchangeably. For information about the concrete implementations of these contracts, see Process Results. For information about how these contracts are used in asynchronous execution, see Asynchronous Execution. For information about the fake implementations, see Faking Overview.
The package defines two primary contracts that abstract process execution and results:
| Contract | Purpose | Primary Usage |
|---|---|---|
ProcessResult | Represents the outcome of a completed process | Returned by synchronous run() and asynchronous wait() |
InvokedProcess | Represents a running process that can be monitored | Returned by asynchronous start() for non-blocking execution |
These contracts serve as the foundation for the package's dual execution model, where application code interacts with interfaces rather than concrete implementations.
Sources:
Sources:
The ProcessResult interface defines methods for inspecting the outcome of a completed process. All methods on this contract are read-only operations that examine the process state after execution has finished.
Sources:
| Method | Return Type | Description |
|---|---|---|
command() | string | Returns the original command string that was executed |
successful() | bool | Returns true if exit code is 0, false otherwise |
failed() | bool | Returns true if exit code is non-zero, false otherwise |
exitCode() | ?int | Returns the process exit code, or null if process hasn't completed |
The successful() and failed() methods are inverse operations - exactly one will always return true for a completed process. These provide a fluent interface for imperative status checking without requiring exception handling.
Sources:
| Method | Return Type | Description |
|---|---|---|
output() | string | Returns the complete standard output (STDOUT) as a string |
errorOutput() | string | Returns the complete error output (STDERR) as a string |
seeInOutput(string $output) | bool | Checks if the given string exists anywhere in STDOUT |
seeInErrorOutput(string $output) | bool | Checks if the given string exists anywhere in STDERR |
The seeInOutput() and seeInErrorOutput() methods provide convenient assertion-style checks for testing output content without requiring string manipulation or regular expressions for simple substring matching.
Sources:
| Method | Signature | Description |
|---|---|---|
throw(?callable $callback = null) | static | Throws ProcessFailedException if process failed |
throwIf(bool $condition, ?callable $callback = null) | static | Throws ProcessFailedException if process failed AND condition is true |
Both methods accept an optional callback that receives the ProcessResult instance and returns a string to be used as the exception message. If no callback is provided, a default message is generated. These methods return static to enable fluent chaining when the process succeeds.
Sources:
The InvokedProcess interface defines methods for interacting with a running process. Unlike ProcessResult, which represents a completed process, InvokedProcess provides real-time monitoring and control of an active process.
Sources:
| Method | Return Type | Description |
|---|---|---|
id() | ?int | Returns the OS process ID if running, null if process has terminated |
signal(int $signal) | static | Sends a Unix signal to the process (e.g., SIGTERM, SIGKILL) |
running() | bool | Returns true if process is still executing, false if completed |
The signal() method returns static to enable fluent chaining. Signal constants are typically from the standard PHP SIGTERM, SIGKILL, etc. constants.
Sources:
| Method | Return Type | Description |
|---|---|---|
output() | string | Returns all STDOUT data captured since process started |
errorOutput() | string | Returns all STDERR data captured since process started |
latestOutput() | string | Returns STDOUT data captured since last call to this method |
latestErrorOutput() | string | Returns STDERR data captured since last call to this method |
The distinction between output() and latestOutput() enables incremental output processing. The "latest" methods maintain internal state tracking what has been retrieved, allowing polling loops to process only new output since the last check.
Sources:
The wait(?callable $output = null) method blocks until the process completes and returns a ProcessResult instance. The optional $output callback is invoked periodically with output data as it becomes available, enabling real-time output streaming without requiring manual polling.
Sources:
The contract architecture enables the package's dual execution model where application code remains unchanged whether executing real processes or using fakes in tests.
| Contract | Real Implementation | Fake Implementation | Creation Source |
|---|---|---|---|
ProcessResult | Hypervel\Process\ProcessResult | Hypervel\Process\FakeProcessResult | PendingProcess::run() or InvokedProcess::wait() |
InvokedProcess | Hypervel\Process\InvokedProcess | Hypervel\Process\FakeInvokedProcess | PendingProcess::start() |
Sources:
The Factory class determines which implementation to return based on its recording state. When Factory::fake() has been called, all contract implementations are swapped to their fake counterparts. Application code depends only on the contracts, never on concrete classes.
Sources:
This pattern uses the boolean methods on ProcessResult to check status without exception handling.
Sources:
This pattern uses the throw() method to raise exceptions on failure, leveraging PHP's exception propagation.
Sources:
This pattern uses InvokedProcess to monitor a running process and retrieve incremental output.
Sources:
This pattern uses signal() to send Unix signals for process control.
Sources:
The contracts provide the following stability guarantees:
Method Signatures: All method signatures in both contracts are considered stable API. Breaking changes will follow semantic versioning.
Return Types: Return types are strictly typed and will not change within major versions.
Implementation Substitution: Any code written against the contracts will work identically whether using real or fake implementations.
Exception Consistency: Both real and fake implementations throw the same exception types from the same methods.
These guarantees enable confident usage in both application and test code, knowing that the interface will remain stable across the dual execution model.
Sources:
Refresh this wiki