Core Components

This document provides an overview of the fundamental building blocks that form the foundation of the hypervel/process package. These components work together to provide a fluent API for process execution, robust testing capabilities, and polymorphic behavior between real and fake process implementations.

For detailed information about process execution patterns (synchronous, asynchronous, pools, and pipes), see Process Execution. For information about the testing infrastructure, see Testing and Faking.

Component Overview

The package is built on four primary components that handle the complete lifecycle of process execution:

Component	Class/Interface	Purpose	Child Page
Factory	Factory	Central orchestrator for creating processes, managing faking mode, recording executions, and providing convenience methods for orchestration patterns	Factory
PendingProcess	PendingProcess	Fluent builder for configuring process parameters (command, path, timeout, environment, etc.) before execution	PendingProcess
Contracts	InvokedProcessContract, ProcessResultContract	Interface definitions that enable polymorphism between real and fake implementations	Contracts
Results	ProcessResult, InvokedProcess	Real implementations representing completed and running processes, wrapping Symfony Process	Process Results

These components form a layered architecture where the Factory creates PendingProcess instances, which execute and return objects implementing the contract interfaces, allowing seamless switching between real and fake implementations.

Sources: src/Factory.php src/PendingProcess.php src/Contracts/InvokedProcess.php src/Contracts/ProcessResult.php

Component Relationships

The following diagram illustrates how the core components relate to each other and their dependencies:

Key Relationships:

• Factory → PendingProcess: The Factory creates PendingProcess instances via newPendingProcess() src/Factory.php255-258 and proxies method calls src/Factory.php263-270
• PendingProcess → Contracts: PendingProcess execution methods return contract interfaces, not concrete types, enabling polymorphism
• Contracts → Implementations: Both real and fake implementations conform to the same contracts
• Implementations → Symfony: Real implementations wrap Symfony Process for actual OS interaction
• Factory ↔ Recording: Factory maintains a record of executed processes and results when in faking mode

Sources: src/Factory.php255-270 src/PendingProcess.php212-253

Process Execution Lifecycle

The following diagram shows how the core components interact during a typical process execution:

Lifecycle Steps:

1. Creation: Application calls a method on Factory, which creates a new PendingProcess instance src/Factory.php263-270
2. Configuration: Application chains configuration methods on PendingProcess (fluent API)
3. Conversion: PendingProcess converts configuration to Symfony Process src/PendingProcess.php258-290
4. Execution: Symfony Process executes the actual OS command
5. Result Creation: PendingProcess wraps Symfony Process in ProcessResult src/PendingProcess.php226
6. Recording: Factory records the execution if in recording mode src/PendingProcess.php220
7. Return: ProcessResult returned to application code
8. Inspection: Application inspects result through contract interface

Sources: src/Factory.php263-270 src/PendingProcess.php212-230 src/PendingProcess.php258-290

Configuration Flow

The PendingProcess class provides a fluent interface for process configuration:

The PendingProcess stores all configuration in public properties src/PendingProcess.php37-83:

• command - Command to execute (string or array)
• path - Working directory
• timeout - Maximum execution time in seconds
• idleTimeout - Maximum idle time without output
• environment - Additional environment variables
• input - Standard input data
• quietly - Whether to disable output
• tty - Whether to enable TTY mode
• options - Options passed to proc_open

These properties are read by toSymfonyProcess() src/PendingProcess.php258-290 to construct the Symfony Process instance.

Sources: src/PendingProcess.php37-83 src/PendingProcess.php102-204 src/PendingProcess.php258-290

Contract-Based Polymorphism

The contract interfaces enable the dual execution path architecture:

Contract Methods:

The ProcessResultContract src/Contracts/ProcessResult.php8-58 defines:

• command() - Get the executed command
• successful() / failed() - Check execution status
• exitCode() - Get exit code
• output() / errorOutput() - Get output streams
• seeInOutput() / seeInErrorOutput() - Search output
• throw() / throwIf() - Error handling

The InvokedProcessContract src/Contracts/InvokedProcess.php8-48 defines:

• id() - Get process ID
• signal() - Send signal to process
• running() - Check if still running
• output() / errorOutput() - Get current output
• latestOutput() / latestErrorOutput() - Get incremental output
• wait() - Block until completion, returns ProcessResultContract

This design ensures application code never depends on concrete implementations, only on contracts. The Factory determines whether to return real or fake implementations based on its configuration state.

Sources: src/Contracts/ProcessResult.php8-58 src/Contracts/InvokedProcess.php8-48

Factory Responsibilities

The Factory serves as the central orchestrator with multiple responsibilities:

Responsibility	Methods	Description
Process Creation	newPendingProcess(), __call()	Creates and configures PendingProcess instances
Faking Control	fake(), isRecording(), preventStrayProcesses()	Manages fake mode and enforcement
Recording	record(), recordIfRecording()	Stores executed processes for assertions
Assertions	assertRan(), assertRanTimes(), assertNotRan(), assertNothingRan()	Verifies process execution in tests
Orchestration	pool(), pipe(), concurrently()	Creates Pool and Pipe instances for complex workflows
Fake Helpers	result(), describe(), sequence()	Factory methods for creating fake process results

The Factory uses the Macroable trait src/Factory.php15-17 for runtime extensibility and proxies unknown method calls to a new PendingProcess instance src/Factory.php263-270 enabling a fluent API directly from the Factory.

Sources: src/Factory.php1-271

Component Properties and State

Factory State

The Factory maintains state for faking and recording src/Factory.php22-41:

• recording - Whether faking is enabled
• recorded - Array of [PendingProcess, ProcessResult] pairs
• fakeHandlers - Map of command patterns to handler closures
• preventStrayProcesses - Whether to throw on un-faked processes

PendingProcess State

PendingProcess stores all configuration as public properties src/PendingProcess.php27-90 making it transparent and easily inspectable. It also maintains a reference to its Factory src/PendingProcess.php30 and received fake handlers src/PendingProcess.php90

This stateful design allows:

1. Fluent Configuration: Each setter returns $this for method chaining
2. Transparency: Public properties allow inspection and testing
3. Lazy Execution: Configuration is separate from execution
4. Recording: Factory can inspect PendingProcess state when recording

Sources: src/Factory.php22-41 src/PendingProcess.php27-90

Integration with External Dependencies

The core components bridge between external dependencies:

Key Dependencies:

• Symfony Process: The underlying process execution engine src/PendingProcess.php258-290
• Hyperf Collection: Used for filtering fake handlers src/PendingProcess.php309-311 and recorded processes src/Factory.php157-159
• Macroable Trait: Enables runtime method extension on Factory src/Factory.php15-17
• Conditionable Trait: Provides conditional method execution on PendingProcess src/PendingProcess.php25

The core components abstract these dependencies, providing a consistent API regardless of the underlying implementation.

Sources: src/Factory.php15-17 src/PendingProcess.php25 src/PendingProcess.php258-290 src/PendingProcess.php309-311