Guzzle OAuth2 Subscriber

Guzzle OAuth2 Subscriber is an OAuth 2.0 client for the Guzzle HTTP library that transparently authenticates outgoing requests. It acquires access tokens via any of the supported grant types, stores and reuses refresh tokens, and automatically fetches new tokens and retries requests when a token expires.

A key design goal is broad compatibility: a single package works across Guzzle 4, 5, 6, and 7, insulating your application from Guzzle’s periodic breaking interface changes. It ships both an OAuth2Subscriber (event emitters for Guzzle 4 and 5) and an OAuth2Middleware (for Guzzle 6+).

What You Get

• Access-token acquisition via client credentials, password credentials, authorization code, and refresh-token grants
• Automatic token refresh and retry of requests that failed due to expiration
• Both OAuth2Subscriber (Guzzle 4/5 emitters) and OAuth2Middleware (Guzzle 6+) integrations
• Pluggable token persistence and lookup through callbacks or persistence classes
• A single package compatible with Guzzle 4, 5, 6, and 7

Common Use Cases

• Calling OAuth 2.0 protected APIs from PHP with automatic token management
• Machine-to-machine API access using the client-credentials grant
• Maintaining OAuth support across projects pinned to different Guzzle versions
• Persisting and reusing access and refresh tokens between requests or processes

Under The Hood

Architecture - The library is organized around grant types (src/GrantType, e.g. ClientCredentials, PasswordCredentials, AuthorizationCode, RefreshToken implementing GrantTypeInterface), signers (src/Signer for AccessToken and ClientCredentials request signing), a Token abstraction, and pluggable Persistence backends. Two integration front-ends, OAuth2Subscriber (Guzzle 4/5 event emitters) and OAuth2Middleware (Guzzle 6+ handler stack), share the same OAuth2Handler that fetches, caches, refreshes, and applies tokens, retrying a request when a 401 indicates an expired token.

Tech Stack - Pure PHP supporting 7.1 through 8.1+ and Guzzle 4-7. Dependencies are kept intentionally loose to span Guzzle major versions, with PHPUnit (plus a namespace-compatibility shim) driving the test suite.

Code Quality - The src tree cleanly separates concerns into Token, Signer, Persistence, GrantType, Exception, and Utils namespaces, and the tests directory mirrors that layout (OAuth2HandlerTest, OAuth2MiddlewareTest, OAuth2SubscriberTest, plus GrantType and Persistence tests), giving solid coverage of the token lifecycle across Guzzle versions.

API Design - Setup is a small, composable sequence: instantiate a grant type with your credentials, wrap it in OAuth2Middleware or OAuth2Subscriber, push/attach it to a client, and set ‘auth’ => ‘oauth’. The interface-driven grant types and callback-based persistence make the extension points explicit, and the README documents each Guzzle version’s integration with runnable examples.