Factory

The Factory class serves as the central orchestrator for the entire process management system. It is responsible for creating processes, managing the faking system for testing, recording process executions, and providing entry points to orchestration patterns (Pipe and Pool). The Factory acts as the primary interface between application code and the process execution infrastructure.

For information about configuring individual processes, see PendingProcess. For details on the testing infrastructure enabled by Factory, see Testing and Faking.

Sources: src/Factory.php1-271

Core Responsibilities

The Factory class manages four distinct concerns:

Responsibility	Key Methods	Purpose
Process Creation	newPendingProcess(), __call()	Creates and configures PendingProcess instances
Faking System	fake(), result(), describe(), sequence()	Enables test mode and creates fake handlers
Recording & Assertions	record(), assertRan(), assertRanTimes(), assertNotRan(), assertNothingRan()	Tracks process executions and provides test assertions
Orchestration	pipe(), pool(), concurrently()	Creates Pipe and Pool instances for multi-process patterns

Sources: src/Factory.php13-271

Class Structure

Sources: src/Factory.php13-271

Process Creation

The Factory creates PendingProcess instances through two mechanisms:

Direct Creation

The newPendingProcess() method explicitly creates a new pending process and initializes it with the Factory's current fake handlers:

Sources: src/Factory.php255-258

Method Proxying

The Factory implements __call() to proxy undefined method calls to a new PendingProcess instance. This provides a fluent API where Factory methods appear to configure processes directly:

The __call() method checks for registered macros first (via the Macroable trait), then delegates to a new pending process:

src/Factory.php263-270

This delegation pattern allows the Factory to act as a facade, exposing the entire PendingProcess API without implementing it directly.

Sources: src/Factory.php263-270 src/Factory.php15-17

Faking System

The Factory manages the faking infrastructure that enables process testing without executing real commands.

State Management

The Factory maintains faking state through three properties:

Property	Type	Purpose
$recording	bool	Indicates if faking is enabled and processes should be recorded
$fakeHandlers	array<string, Closure>	Maps command patterns to fake handler callbacks
$preventStrayProcesses	bool	When true, throws exception if unmocked process is attempted

Sources: src/Factory.php19-41

Enabling Faking

The fake() method enables faking mode and configures handlers. It accepts three types of arguments:

Null argument - Creates a global catch-all handler that returns empty FakeProcessResult: src/Factory.php80-83

Closure argument - Uses the provided closure as a global handler for all commands: src/Factory.php86-89

Array argument - Maps specific commands (array keys) to handlers (array values). Numeric keys are treated as global handlers: src/Factory.php92-96

Sources: src/Factory.php76-99

Creating Fake Objects

The Factory provides three factory methods for creating fake process objects:

result() - Creates a FakeProcessResult with specified output, error output, and exit code: src/Factory.php46-53

describe() - Creates a FakeProcessDescription builder for complex fake process behavior: src/Factory.php58-61

sequence() - Creates a FakeProcessSequence that returns different results on successive invocations: src/Factory.php68-71

These methods provide a fluent API for constructing fake handlers in tests. See Fake Process Results, Fake Process Descriptions, and Fake Process Sequences for detailed usage.

Sources: src/Factory.php46-71

Stray Process Prevention

The preventStrayProcesses() method enables strict mode, where any process execution without a matching fake handler throws an exception:

src/Factory.php134-139

The preventingStrayProcesses() method checks if this mode is active: src/Factory.php144-147

This feature ensures comprehensive test coverage by failing loudly when unmocked processes are attempted. See Preventing Stray Processes for details.

Sources: src/Factory.php134-147

Recording System

The Factory tracks all process executions when faking is enabled, storing both the PendingProcess configuration and the resulting ProcessResultContract.

Recording State

The $recorded property stores an array of tuples, where each tuple contains:

• Index 0: The PendingProcess that was executed
• Index 1: The ProcessResultContract that was returned

src/Factory.php25-29

Recording Methods

isRecording() - Returns whether faking mode is active: src/Factory.php104-107

record() - Unconditionally appends a process/result pair to the recorded array: src/Factory.php124-129

recordIfRecording() - Conditionally records only if faking is enabled. This is called by PendingProcess after each execution: src/Factory.php112-119

Sources: src/Factory.php104-129

Assertion Methods

The Factory provides four assertion methods that delegate to PHPUnit to verify expected process interactions. All methods return $this for fluent chaining.

Method Signatures and Behavior

assertRan()

Asserts that at least one process matching the given criteria was executed. Accepts either:

• String: Matches against $process->command property
• Closure: Custom callback receiving ($process, $result) that returns boolean

src/Factory.php152-164

assertRanTimes()

Asserts that exactly $times processes matching the criteria were executed. Uses the same matching logic as assertRan():

src/Factory.php169-184

assertNotRan()

Asserts that zero processes matching the criteria were executed. Inverse of assertRan():

src/Factory.php189-201

The assertDidntRun() method is an alias: src/Factory.php206-209

assertNothingRan()

Asserts that no processes of any kind were executed:

src/Factory.php214-222

Sources: src/Factory.php152-222

Orchestration Pattern Creation

The Factory provides three methods for creating multi-process orchestration patterns.

Process Pool

pool(callable $callback) - Creates a Pool instance for concurrent process execution:

src/Factory.php227-230

The callback receives the Pool instance and configures processes to run concurrently. See Process Pools for details.

Process Pipe

pipe(array|callable $callback, ?callable $output = null) - Creates and executes a Pipe for sequential process execution with data flow:

src/Factory.php235-242

Accepts either:

• Array: Interpreted as array of commands to pipe sequentially
• Callable: Receives Pipe instance for custom configuration

The pipe is immediately executed via run() and returns a ProcessResultContract. See Process Pipes for details.

Concurrent Execution

concurrently(callable $callback, ?callable $output = null) - Shorthand for creating a pool, starting all processes, and waiting for completion:

src/Factory.php247-250

This combines pool(), start(), and wait() into a single operation, returning ProcessPoolResults.

Sources: src/Factory.php227-250

Factory State Diagram

The following diagram shows how Factory state transitions affect process execution:

Sources: src/Factory.php13-271

Integration with PendingProcess

The Factory passes its state to each created PendingProcess instance:

The newPendingProcess() method ensures that:

1. The PendingProcess receives a reference to the Factory (for recording)
2. The PendingProcess receives a copy of current fake handlers (for execution routing)

This design allows the Factory to centrally manage faking configuration while delegating execution logic to PendingProcess.

Sources: src/Factory.php255-258

Usage Examples

Basic Process Creation

Faking with Global Handler

Faking with Command-Specific Handlers

Orchestration Patterns

Sources: src/Factory.php1-271

Extension via Macros

The Factory uses the Macroable trait from Hyperf, allowing runtime extension with custom methods:

src/Factory.php15-17

The __call() implementation checks for macros before delegating to PendingProcess: src/Factory.php265-266

This enables adding custom functionality to the Factory without modifying the class itself.

Sources: src/Factory.php15-17 src/Factory.php263-270