Response Sequences

Purpose and Scope

This document explains the ResponseSequence class, which provides ordered fake response simulation for testing. Response sequences allow tests to define a series of responses that will be returned in order as requests are made, enabling predictable testing of code that makes multiple HTTP requests.

For information about basic request faking with stub callbacks, see Faking Requests. For assertion methods used to verify request behavior, see Assertions.

---

Overview

The ResponseSequence class is a specialized testing utility that returns fake responses in a predefined order. Each invocation of the sequence consumes the next response from its internal queue, making it ideal for testing scenarios where code makes sequential HTTP requests and expects specific responses in a particular order.

Sources: src/ResponseSequence.php1-132

---

Architecture

The following diagram shows how ResponseSequence integrates with the Factory's stubbing system:

Sources: src/Factory.php175-178 src/Factory.php229-234 src/ResponseSequence.php118-131

---

Creating Response Sequences

Factory::sequence()

The sequence() method creates a new ResponseSequence instance with optional initial responses. The Factory tracks all created sequences for later verification.

Parameter	Type	Description
$responses	array	Optional array of initial responses

The created sequence is stored in the Factory's $responseSequences array at src/Factory.php66

Sources: src/Factory.php175-178

---

Factory::fakeSequence()

The fakeSequence() method creates a sequence and immediately registers it as a stub for a specific URL pattern. This is a convenience method that combines sequence creation with URL-based stubbing.

Parameter	Type	Default	Description
$url	string	'*'	URL pattern to match (supports wildcards)

Sources: src/Factory.php229-234

---

Sequence Response Lifecycle

The following diagram illustrates how a sequence returns responses over multiple invocations:

Sources: src/ResponseSequence.php118-131 src/ResponseSequence.php108-111

---

Adding Responses to Sequences

push()

Adds a response with the specified body, status code, and headers to the sequence.

Parameter	Type	Default	Description
$body	array|string|null	null	Response body (arrays are JSON-encoded)
$status	int	200	HTTP status code
$headers	array	[]	Response headers

Internally calls Factory::response() to create a PromiseInterface and adds it via pushResponse().

Sources: src/ResponseSequence.php37-42

---

pushStatus()

Adds a response with only a status code (empty body).

Parameter	Type	Description
$status	int	HTTP status code
$headers	array	Response headers

Sources: src/ResponseSequence.php47-52

---

pushFile()

Adds a response with file contents as the body.

Parameter	Type	Default	Description
$filePath	string	-	Path to file containing response body
$status	int	200	HTTP status code
$headers	array	[]	Response headers

Reads the file using file_get_contents() at src/ResponseSequence.php59

Sources: src/ResponseSequence.php57-64

---

pushFailedConnection()

Adds a connection failure to the sequence, useful for testing error handling.

Parameter	Type	Default	Description
$message	string|null	null	Custom error message

Uses Factory::failedConnection() to create a rejected promise with a ConnectException.

Sources: src/ResponseSequence.php69-74

---

pushResponse()

Adds a raw response to the sequence. This is the low-level method used by all other push methods.

Parameter	Type	Description
$response	mixed	Response to add (PromiseInterface, Closure, etc.)

The response is appended to the $responses array at src/ResponseSequence.php81

Sources: src/ResponseSequence.php79-84

---

Response Addition Methods Comparison

Method	Purpose	Body Type	Status	Headers
push()	General purpose response	array|string|null	Configurable	Configurable
pushStatus()	Status code only	Empty	Configurable	Configurable
pushFile()	File contents as body	File contents	Configurable	Configurable
pushFailedConnection()	Connection failure	N/A (exception)	N/A	N/A
pushResponse()	Raw response object	N/A	N/A	N/A

Sources: src/ResponseSequence.php37-84

---

Empty Sequence Behavior

Default Behavior

By default, a sequence throws an OutOfBoundsException when invoked after all responses are consumed. The $failWhenEmpty property controls this behavior at src/ResponseSequence.php19

Sources: src/ResponseSequence.php18-19 src/ResponseSequence.php120-122

---

whenEmpty()

Configures the sequence to return a default response when empty instead of throwing an exception.

Parameter	Type	Description
$response	Closure|PromiseInterface	Response to return when empty

Sets $failWhenEmpty to false and stores the $emptyResponse at src/ResponseSequence.php91-92

Sources: src/ResponseSequence.php89-95

---

dontFailWhenEmpty()

Convenience method that configures the sequence to return a default 200 OK response when empty.

Internally calls whenEmpty() with Factory::response() at src/ResponseSequence.php102

Sources: src/ResponseSequence.php100-103

---

Empty Sequence Behavior Flow

Sources: src/ResponseSequence.php118-131

---

Sequence Invocation

The __invoke() magic method is called when the sequence is used as a callable in the stubbing system. It consumes and returns the next response in the queue.

Parameter	Type	Description
$request	Request	The request object (may be used by Closure responses)

Invocation Logic

1. If $failWhenEmpty is true and sequence is empty → throws OutOfBoundsException
2. If $failWhenEmpty is false and sequence is empty → returns $emptyResponse
3. Otherwise → uses array_shift() to remove and return the first response
4. If response is a Closure → invokes it with the request, otherwise returns it directly

Sources: src/ResponseSequence.php118-131

---

Integration with Stubbing System

The following diagram shows how sequences integrate with the Factory's stub callback system:

Sources: src/Factory.php229-234 src/Factory.php254-256 src/ResponseSequence.php118-131

---

State Checking Methods

isEmpty()

Determines whether all responses have been consumed from the sequence.

Returns true when count($this->responses) === 0 at src/ResponseSequence.php110

Sources: src/ResponseSequence.php108-111

---

Factory::assertSequencesAreEmpty()

Verifies that all created sequences have been fully consumed in the test. This assertion ensures tests don't create more fake responses than actually needed.

Iterates through the $responseSequences array at src/Factory.php376 and calls isEmpty() on each sequence. Throws a PHPUnit assertion failure if any sequence still has responses.

Sources: src/Factory.php374-382

---

Internal State

The ResponseSequence class maintains the following internal properties:

Property	Type	Default	Description
$responses	array	constructor param	Queue of responses to return
$failWhenEmpty	bool	true	Whether to throw exception when empty
$emptyResponse	PromiseInterface	undefined	Response to return when empty (if not failing)

Sources: src/ResponseSequence.php14-32

---

Extensibility

The ResponseSequence class uses the Macroable trait at src/ResponseSequence.php14 allowing custom methods to be added at runtime. For information about runtime extension, see Runtime Extension with Macros.

Sources: src/ResponseSequence.php14

---

Storage in Factory

All sequences created via Factory::sequence() or Factory::fakeSequence() are stored in the Factory's $responseSequences array property at src/Factory.php66 This enables the assertSequencesAreEmpty() assertion to verify all sequences are consumed.

Sources: src/Factory.php65-66 src/Factory.php177 src/Factory.php231