API Reference

This page provides comprehensive reference documentation for all public methods and properties across the Hypervel HTTP Client package. It is organized by class and includes method signatures, parameters, and return types.

For conceptual information about how these components work together, see Core Components. For practical usage examples, see Making HTTP Requests and Response Processing. For testing-specific functionality, see Testing and Mocking.

---

Class Overview

Sources: src/Factory.php1-526 src/PendingRequest.php1-1667 src/Request.php1-268 src/Response.php1-501 src/ResponseSequence.php1-132

---

Factory Class

The Factory class is the entry point for creating HTTP requests and managing the testing infrastructure.

Sources: src/Factory.php31-526

Creation and Configuration Methods

Method	Signature	Description
__construct	__construct(?EventDispatcherInterface $dispatcher = null)	Creates a new Factory instance with optional event dispatcher
globalMiddleware	globalMiddleware(callable $middleware): static	Adds middleware to apply to every request
globalRequestMiddleware	globalRequestMiddleware(callable $middleware): static	Adds request-specific middleware to every request
globalResponseMiddleware	globalResponseMiddleware(callable $middleware): static	Adds response-specific middleware to every request
globalOptions	globalOptions(array|Closure $options): static	Sets options to apply to every request
createPendingRequest	createPendingRequest(): PendingRequest	Creates a new PendingRequest instance with global configuration

Sources: src/Factory.php92-417

Static Factory Methods

Method	Signature	Description
response	response(array|callable|int|PromiseInterface|Response|string|null $body = null, int $status = 200, array $headers = []): PromiseInterface	Creates a fake response for testing
failedConnection	failedConnection(?string $message = null): Closure	Creates a connection exception for testing

Sources: src/Factory.php138-170

Testing and Stubbing Methods

Method	Signature	Description
fake	fake(array|callable|null $callback = null): static	Registers stub callbacks to intercept requests
fakeSequence	fakeSequence(string $url = '*'): ResponseSequence	Creates and registers a response sequence for a URL pattern
sequence	sequence(array $responses = []): ResponseSequence	Creates a new ResponseSequence instance
stubUrl	stubUrl(string $url, array|callable|int|PromiseInterface|Response|string $callback): static	Stubs a specific URL with a callback or response
preventStrayRequests	preventStrayRequests(bool $prevent = true): static	Throws exception if any request is not faked
preventingStrayRequests	preventingStrayRequests(): bool	Checks if stray requests are being prevented
allowStrayRequests	allowStrayRequests(): static	Allows requests that are not faked
recordRequestResponsePair	recordRequestResponsePair(Request $request, ?Response $response): void	Records a request/response pair for assertions
recorded	recorded(?callable $callback = null): Collection	Gets recorded request/response pairs matching a callback

Sources: src/Factory.php172-399

Assertion Methods

Method	Signature	Description
assertSent	assertSent(callable $callback): void	Asserts a request matching the callback was sent
assertSentInOrder	assertSentInOrder(array $callbacks): void	Asserts requests were sent in the given order
assertNotSent	assertNotSent(callable $callback): void	Asserts a request matching the callback was not sent
assertNothingSent	assertNothingSent(): void	Asserts no requests were sent
assertSentCount	assertSentCount(int $count): void	Asserts the exact number of requests sent
assertSequencesAreEmpty	assertSequencesAreEmpty(): void	Asserts all response sequences are empty

Sources: src/Factory.php308-382

Connection Management Methods

Method	Signature	Description
registerConnection	registerConnection(string $name, array $config = []): static	Registers a named connection with configuration
getClient	getClient(?string $connection, HandlerStack $handlerStack, ?array $config = null): ClientInterface	Gets the HTTP client for a connection
createClient	createClient(HandlerStack $handlerStack): ClientInterface	Creates a new Guzzle client instance
getConnectionConfig	getConnectionConfig(string $name): array	Gets configuration for a specific connection
getConnectionConfigs	getConnectionConfigs(): array	Gets configuration for all connections
setConnectionConfig	setConnectionConfig(string $name, array $config): static	Sets configuration for a specific connection

Sources: src/Factory.php436-513

Accessor Methods

Method	Signature	Description
getDispatcher	getDispatcher(): ?EventDispatcherInterface	Gets the current event dispatcher
getGlobalMiddleware	getGlobalMiddleware(): array	Gets the array of global middleware

Sources: src/Factory.php420-433

---

PendingRequest Class

The PendingRequest class provides a fluent API for configuring and executing HTTP requests.

Sources: src/PendingRequest.php38-1667

Request Configuration Methods

Sources: src/PendingRequest.php212-521

Method	Signature	Description
baseUrl	baseUrl(string $url): static	Sets the base URL for the request
withUrlParameters	withUrlParameters(array $parameters = []): static	Sets URL parameters for template substitution
withQueryParameters	withQueryParameters(array $parameters): static	Sets query string parameters
withHeaders	withHeaders(array $headers): static	Adds headers to the request
withHeader	withHeader(string $name, mixed $value): static	Adds a single header to the request
replaceHeaders	replaceHeaders(array $headers): static	Replaces headers on the request
contentType	contentType(string $contentType): static	Sets the Content-Type header
accept	accept(string $contentType): static	Sets the Accept header
acceptJson	acceptJson(): static	Sets Accept header to application/json
withUserAgent	withUserAgent(bool|string $userAgent): static	Sets the User-Agent header

Sources: src/PendingRequest.php212-407

Body Format Methods

Method	Signature	Description
asJson	asJson(): static	Indicates the request contains JSON
asForm	asForm(): static	Indicates the request contains form parameters
asMultipart	asMultipart(): static	Indicates the request is multipart/form-data
withBody	withBody(StreamInterface|string $content, string $contentType = 'application/json'): static	Attaches a raw body to the request
attach	attach(array|string $name, $contents = '', ?string $filename = null, array $headers = []): static	Attaches a file to the request
bodyFormat	bodyFormat(string $format): static	Specifies the body format of the request

Sources: src/PendingRequest.php223-299

Authentication Methods

Method	Signature	Description
withBasicAuth	withBasicAuth(string $username, string $password): static	Sets basic authentication credentials
withDigestAuth	withDigestAuth(string $username, string $password): static	Sets digest authentication credentials
withToken	withToken(string $token, string $type = 'Bearer'): static	Sets an authorization token

Sources: src/PendingRequest.php369-397

Connection and Timeout Methods

Method	Signature	Description
timeout	timeout(float|int $seconds): static	Sets the request timeout in seconds
connectTimeout	connectTimeout(float|int $seconds): static	Sets the connection timeout in seconds
withCookies	withCookies(array $cookies, string $domain): static	Sets cookies for the request
maxRedirects	maxRedirects(int $max): static	Sets the maximum number of redirects
withoutRedirecting	withoutRedirecting(): static	Disables following redirects
withoutVerifying	withoutVerifying(): static	Disables TLS certificate verification
sink	sink($to): static	Sets the path where the response body should be stored
withOptions	withOptions(array $options): static	Replaces specified Guzzle options

Sources: src/PendingRequest.php420-521

Middleware Methods

Method	Signature	Description
withMiddleware	withMiddleware(callable $middleware): static	Adds middleware to the client handler stack
withRequestMiddleware	withRequestMiddleware(callable $middleware): static	Adds request-specific middleware
withResponseMiddleware	withResponseMiddleware(callable $middleware): static	Adds response-specific middleware
beforeSending	beforeSending(callable $callback): static	Adds a callback to execute before sending

Sources: src/PendingRequest.php523-561

Retry Configuration Methods

Method	Signature	Description
retry	retry(array|int $times, Closure|int $sleepMilliseconds = 0, ?callable $when = null, bool $throw = true): static	Configures retry behavior

Sources: src/PendingRequest.php493-508

Error Handling Methods

Method	Signature	Description
throw	throw(?callable $callback = null): static	Throws exception on server or client error
throwIf	throwIf(bool|callable $condition): static	Conditionally throws exception on error
throwUnless	throwUnless(bool|callable $condition): static	Throws exception unless condition is true

Sources: src/PendingRequest.php563-591

HTTP Verb Methods

Sources: src/PendingRequest.php623-794

Method	Signature	Description
get	get(string $url, array|JsonSerializable|string|null $query = null): PromiseInterface|Response	Issues a GET request
head	head(string $url, array|string|null $query = null): PromiseInterface|Response	Issues a HEAD request
post	post(string $url, array|JsonSerializable $data = []): PromiseInterface|Response	Issues a POST request
patch	patch(string $url, array $data = []): PromiseInterface|Response	Issues a PATCH request
put	put(string $url, array $data = []): PromiseInterface|Response	Issues a PUT request
delete	delete(string $url, array $data = []): PromiseInterface|Response	Issues a DELETE request
send	send(string $method, string $url, array $options = []): PromiseInterface|Response	Sends a request with the given HTTP method

Sources: src/PendingRequest.php623-794

Asynchronous Methods

Method	Signature	Description
async	async(bool $async = true): static	Enables asynchronous request mode
getPromise	getPromise(): ?PromiseInterface	Retrieves the pending request promise

Sources: src/PendingRequest.php1235-1250

Testing Methods

Method	Signature	Description
stub	stub(callable|Collection $callback): static	Registers stub callbacks to intercept requests
preventStrayRequests	preventStrayRequests(bool $prevent = true): static	Throws exception if request is not faked

Sources: src/PendingRequest.php1213-1232

Handler Stack Methods

Method	Signature	Description
buildClient	buildClient(): ClientInterface	Builds the Guzzle client
buildHandlerStack	buildHandlerStack(): HandlerStack	Builds the Guzzle handler stack
pushHandlers	pushHandlers(HandlerStack $handlerStack): HandlerStack	Adds handlers to the handler stack
buildBeforeSendingHandler	buildBeforeSendingHandler(): Closure	Builds the before-sending handler
buildRecorderHandler	buildRecorderHandler(): Closure	Builds the recorder handler
buildStubHandler	buildStubHandler(): Closure	Builds the stub handler
runBeforeSendingCallbacks	runBeforeSendingCallbacks(RequestInterface $request, array $options): RequestInterface	Executes before-sending callbacks
mergeOptions	mergeOptions(...$options): array	Merges options with current request options

Sources: src/PendingRequest.php1033-1202

Debugging Methods

Method	Signature	Description
dump	dump(): static	Dumps the request before sending
dd	dd(): static	Dumps the request and exits

Sources: src/PendingRequest.php593-621

Connection Methods

Method	Signature	Description
setConnection	setConnection(?string $connection): static	Sets the connection name
getConnection	getConnection(): ?string	Gets the current connection name
setConnectionConfig	setConnectionConfig(?array $config): static	Sets the connection configuration
getConnectionConfig	getConnectionConfig(): ?array	Gets the connection configuration

Sources: src/PendingRequest.php1252-1294

---

Request Class

The Request class wraps PSR-7 RequestInterface and provides convenience methods for inspecting request data.

Sources: src/Request.php14-268

Inspection Methods

Method	Signature	Description
method	method(): string	Gets the HTTP method
url	url(): string	Gets the request URL
hasHeader	hasHeader(string $key, mixed $value = null): bool	Checks if request has a header
hasHeaders	hasHeaders(array|string $headers): bool	Checks if request has multiple headers
header	header(string $key): array	Gets values for a header
headers	headers(): array	Gets all request headers
body	body(): string	Gets the request body as string
hasFile	hasFile(string $name, ?string $value = null, ?string $filename = null): bool	Checks if request contains a file

Sources: src/Request.php30-122

Data Access Methods

Method	Signature	Description
data	data(): array	Gets the request data (form or JSON)
query	query(): array	Gets the query string parameters
withData	withData(array $data): Request	Sets decoded data on the request
withQuery	withQuery(array $query = []): Request	Merges query parameters

Sources: src/Request.php124-215

Content Type Detection Methods

Method	Signature	Description
isForm	isForm(): bool	Checks if request is form-encoded
isJson	isJson(): bool	Checks if request is JSON
isMultipart	isMultipart(): bool	Checks if request is multipart

Sources: src/Request.php165-189

Conversion Methods

Method	Signature	Description
toPsrRequest	toPsrRequest(): RequestInterface	Gets the underlying PSR-7 request

Sources: src/Request.php217-223

ArrayAccess Implementation

Method	Signature	Description
offsetExists	offsetExists($offset): bool	Checks if data key exists
offsetGet	offsetGet($offset): mixed	Gets data by key
offsetSet	offsetSet($offset, mixed $value): void	Throws LogicException (read-only)
offsetUnset	offsetUnset($offset): void	Throws LogicException (read-only)

Sources: src/Request.php225-267

---

Response Class

The Response class wraps PSR-7 ResponseInterface and provides methods for extracting and inspecting response data.

Sources: src/Response.php25-501

Data Extraction Methods

Sources: src/Response.php58-152

Method	Signature	Description
body	body(): string	Gets the response body as string
json	json(?string $key = null, mixed $default = null): mixed	Gets JSON-decoded body as array
object	object(): array|object|null	Gets JSON-decoded body as object
collect	collect(?string $key = null): Collection	Gets JSON-decoded body as Collection
fluent	fluent(?string $key = null): Fluent	Gets JSON-decoded body as Fluent object
resource	resource()	Gets body as PHP resource
decodeUsing	decodeUsing(?Closure $callback): static	Sets a custom decode callback

Sources: src/Response.php59-152

Header Methods

Method	Signature	Description
header	header(string $header): string	Gets a single header value
headers	headers(): array	Gets all response headers

Sources: src/Response.php154-168

Status Methods

Method	Signature	Description
status	status(): int	Gets the HTTP status code
reason	reason(): string	Gets the reason phrase
effectiveUri	effectiveUri(): ?UriInterface	Gets the effective URI after redirects
successful	successful(): bool	Checks if status is 2xx
redirect	redirect(): bool	Checks if status is 3xx
failed	failed(): bool	Checks if client or server error
clientError	clientError(): bool	Checks if status is 4xx
serverError	serverError(): bool	Checks if status is 5xx

Sources: src/Response.php170-232

Status Code Checking Methods (via DeterminesStatusCode Trait)

The following methods are provided by the DeterminesStatusCode trait:

Method	Description
ok()	Status code 200
created()	Status code 201
accepted()	Status code 202
noContent()	Status code 204
movedPermanently()	Status code 301
found()	Status code 302
badRequest()	Status code 400
unauthorized()	Status code 401
paymentRequired()	Status code 402
forbidden()	Status code 403
notFound()	Status code 404
requestTimeout()	Status code 408
conflict()	Status code 409
unprocessableEntity()	Status code 422
tooManyRequests()	Status code 429
serverError()	Status code 500

Sources: src/Concerns/DeterminesStatusCode.php1-143

Error Handling Methods

Method	Signature	Description
onError	onError(callable $callback): static	Executes callback if there was an error
toException	toException(): ?RequestException	Creates exception from response
throw	throw(): static	Throws exception if error occurred
throwIf	throwIf(bool|Closure $condition): static	Conditionally throws exception
throwIfStatus	throwIfStatus(callable|int $statusCode): static	Throws exception if status matches
throwUnlessStatus	throwUnlessStatus(callable|int $statusCode): static	Throws exception unless status matches
throwIfClientError	throwIfClientError(): static	Throws exception if 4xx status
throwIfServerError	throwIfServerError(): static	Throws exception if 5xx status

Sources: src/Response.php234-373

Metadata Methods

Method	Signature	Description
cookies	cookies(): CookieJar	Gets the response cookies
handlerStats	handlerStats(): array	Gets handler statistics
close	close(): static	Closes the response stream

Sources: src/Response.php247-270

Conversion Methods

Method	Signature	Description
toPsrResponse	toPsrResponse(): ResponseInterface	Gets underlying PSR-7 response
__toString	__toString()	Converts response to string (body)

Sources: src/Response.php272-485

Debugging Methods

Method	Signature	Description
dump	dump(?string $key = null): static	Dumps response content
dd	dd(?string $key = null): void	Dumps response content and exits
dumpHeaders	dumpHeaders(): static	Dumps response headers
ddHeaders	ddHeaders()	Dumps response headers and exits

Sources: src/Response.php375-431

ArrayAccess Implementation

Method	Signature	Description
offsetExists	offsetExists($offset): bool	Checks if JSON key exists
offsetGet	offsetGet($offset): mixed	Gets JSON value by key
offsetSet	offsetSet($offset, mixed $value): void	Throws LogicException (read-only)
offsetUnset	offsetUnset($offset): void	Throws LogicException (read-only)

Sources: src/Response.php433-475

---

ResponseSequence Class

The ResponseSequence class manages ordered sequences of responses for testing purposes.

Sources: src/ResponseSequence.php12-132

Construction Methods

Method	Signature	Description
__construct	__construct(protected array $responses)	Creates a new response sequence
push	push(array|string|null $body = null, int $status = 200, array $headers = []): static	Adds a response to the sequence
pushStatus	pushStatus(int $status, array $headers = []): static	Adds a response with status code
pushFile	pushFile(string $filePath, int $status = 200, array $headers = []): static	Adds a response from file contents
pushFailedConnection	pushFailedConnection(?string $message = null): static	Adds a connection failure
pushResponse	pushResponse(mixed $response): static	Adds a raw response

Sources: src/ResponseSequence.php27-84

Configuration Methods

Method	Signature	Description
whenEmpty	whenEmpty(Closure|PromiseInterface $response): static	Sets default response when empty
dontFailWhenEmpty	dontFailWhenEmpty(): static	Returns default response when empty
isEmpty	isEmpty(): bool	Checks if sequence is depleted

Sources: src/ResponseSequence.php86-111

Invocation

Method	Signature	Description
__invoke	__invoke(Request $request): mixed	Gets next response in sequence

Sources: src/ResponseSequence.php113-131

---

Method Call Flow Diagram

Sources: src/Factory.php404-525 src/PendingRequest.php187-210 src/PendingRequest.php713-794

---

Macroable Methods

All major classes (Factory, PendingRequest, Request, Response, ResponseSequence) use the Macroable trait, which enables runtime method extension:

Method	Signature	Description
macro	macro(string $name, object|callable $macro)	Registers a custom macro
mixin	mixin(object $mixin, bool $replace = true)	Mixes another object's methods
hasMacro	hasMacro(string $name): bool	Checks if macro exists
flushMacros	flushMacros(): void	Removes all macros

Sources: src/Factory.php17-36 src/PendingRequest.php40-41 src/Request.php16 src/Response.php27-29 src/ResponseSequence.php14

---

Public Properties

PendingRequest Public Properties

None. All properties are protected or private.

Response Public Properties

Property	Type	Description
$cookies	?CookieJar	The request cookies
$transferStats	?TransferStats	Transfer statistics for the request

Sources: src/Response.php43-49

Request Public Properties

None. All properties are protected or private.

---

Property Access Diagram

Sources: src/Response.php43-260