Middleware Configuration

This page documents how to configure the middleware system in the API client. It covers enabling/disabling middleware processing, setting middleware options that are passed to middleware instances, managing middleware arrays for request and response pipelines, and understanding middleware caching behavior.

For information about the middleware architecture and how pipelines work, see Middleware Overview. For details on creating custom middleware, see Creating Custom Middleware.

---

Purpose and Scope

The middleware configuration system controls how middleware is applied to API requests and responses. Configuration can be set at two levels:

• ApiClient level: Default configuration inherited by all PendingRequest instances
• PendingRequest level: Per-request configuration that overrides client defaults

This page focuses on the configuration mechanics. For middleware implementation details, see Request Middleware and Response Middleware.

Sources: src/ApiClient.php14-116 src/PendingRequest.php22-342

---

Configuration Methods Overview

The following table summarizes all middleware configuration methods available:

Method	Available On	Purpose
enableMiddleware()	ApiClient, PendingRequest	Enable middleware processing
disableMiddleware()	ApiClient, PendingRequest	Disable middleware processing
getEnableMiddleware()	ApiClient	Check if middleware is enabled
withMiddlewareOptions()	PendingRequest	Set options passed to middleware
withRequestMiddleware()	PendingRequest	Replace request middleware array
withResponseMiddleware()	PendingRequest	Replace response middleware array
withAddedRequestMiddleware()	PendingRequest	Append to request middleware array
withAddedResponseMiddleware()	PendingRequest	Append to response middleware array
flushCache()	PendingRequest	Clear middleware instance cache

Sources: src/ApiClient.php76-107 src/PendingRequest.php67-252

---

Enabling and Disabling Middleware

Default Behavior

Middleware processing is enabled by default in both ApiClient and PendingRequest. When enabled, all requests and responses pass through their respective middleware pipelines.

Sources: src/ApiClient.php26 src/PendingRequest.php31

Disabling at Client Level

Disable middleware for all requests created by an ApiClient:

Disabling at Request Level

Override client-level settings for a specific request:

Re-enabling Middleware

If middleware is disabled at the client level, it can be re-enabled for specific requests:

When to Disable Middleware

Common scenarios for disabling middleware:

• Debugging: Isolate HTTP communication from middleware effects
• Performance: Skip middleware overhead for simple requests
• Testing: Test raw HTTP behavior without middleware transformations

Sources: src/ApiClient.php76-91 src/PendingRequest.php67-82

---

Configuring Middleware Options

Overview

Middleware options are arbitrary data passed to middleware instances via the context system. They are injected into the request or response context before middleware processing begins.

Sources: src/PendingRequest.php33-92

Setting Options

Use withMiddlewareOptions() to provide configuration data to middleware:

How Middleware Accesses Options

Middleware receives options through the context system. In the request pipeline:

Sources: src/PendingRequest.php293-307

Options Lifecycle

Middleware Configuration Flow

Sources: src/PendingRequest.php293-307

---

Managing Middleware Arrays

Setting vs Adding Middleware

Two approaches exist for configuring middleware arrays:

1. Replace the entire array: withRequestMiddleware() / withResponseMiddleware()
2. Append to the existing array: withAddedRequestMiddleware() / withAddedResponseMiddleware()

Replacing Middleware Arrays

Use withRequestMiddleware() or withResponseMiddleware() to completely replace the middleware configuration:

This discards any middleware configured at the ApiClient level for this specific request.

Sources: src/PendingRequest.php107-132

Adding Middleware

Use withAddedRequestMiddleware() or withAddedResponseMiddleware() to append middleware to the existing array:

This preserves middleware from the ApiClient configuration and adds new middleware to the end of the pipeline.

Sources: src/PendingRequest.php117-142

Configuration Inheritance

Middleware Array Inheritance Diagram

Sources: src/PendingRequest.php53-142

Middleware Execution Order

Middleware executes in the order it appears in the array:

The order matters because:

• Earlier middleware can modify data before later middleware sees it
• Later middleware can depend on transformations by earlier middleware
• Short-circuiting middleware (e.g., cache) prevent later middleware from executing

Sources: src/PendingRequest.php293-307

---

Middleware Caching

Caching Mechanism

The PendingRequest class maintains a static cache of middleware instances to avoid repeated instantiation:

When middleware is created via createMiddleware(), the system:

1. Checks if an instance exists in $cachedMiddleware for the given class name
2. If found, reuses the cached instance
3. If not found, creates a new instance and stores it in the cache

Sources: src/PendingRequest.php51-326

Middleware Instantiation Flow

Middleware Creation and Caching

Sources: src/PendingRequest.php309-326

Configuration Injection

Middleware instances are created with the ApiClient's configuration object:

This means:

• All middleware instances share the same configuration object
• The configuration is passed during instantiation, not during execution
• Middleware can access configuration in their constructor or store it as a property

Sources: src/PendingRequest.php322

Cache Lifetime

The middleware cache is static and persists across multiple PendingRequest instances within the same PHP process. This provides performance benefits but requires awareness:

• Middleware state persists between requests
• Middleware should be stateless or carefully manage state
• Cached instances are tied to the configuration they were created with

Flushing the Cache

Clear the middleware cache using flushCache():

This is useful when:

• Testing different middleware configurations
• Releasing resources held by middleware
• Forcing middleware re-initialization with new configuration

Sources: src/PendingRequest.php249-252

---

Configuration Best Practices

Client-Level Configuration

Define default middleware in your ApiClient subclass:

This ensures consistent behavior across all requests.

Sources: src/ApiClient.php31-36

Request-Level Overrides

Use request-level configuration for exceptional cases:

Middleware Options Organization

Structure middleware options with namespaced keys to avoid conflicts:

Each middleware can then access its own configuration namespace.

---

Configuration Reference Table

Property	Type	Default	Location	Description
$enableMiddleware	bool	true	ApiClient, PendingRequest	Controls middleware processing
$middlewareOptions	array	[]	PendingRequest	Options passed to middleware via context
$requestMiddleware	array	[]	ApiClient, PendingRequest	Request middleware class names
$responseMiddleware	array	[]	ApiClient, PendingRequest	Response middleware class names
$cachedMiddleware	array	[]	PendingRequest (static)	Cached middleware instances

Sources: src/ApiClient.php26-36 src/PendingRequest.php31-51