Oauth2 Laravel Package

Technical Evaluation

Architecture fit

• adoy/oauth2 is a client-side OAuth 2.0 wrapper, not a server/framework component. It provides OAuth2\Client plus grant-type classes (authorization code, client credentials, password, refresh token) and a pluggable token-storage interface. It answers exactly one question: "how do I exchange credentials for a bearer token and attach it to a request?"
• It is not Laravel-native. There is no service provider, no facade, no publishable config, no contract binding, and no Laravel-version compatibility metadata. In a Laravel app it becomes a hand-wrapped dependency behind a service provider we author and own.
• Because the package predates RFC 6749 (it targets draft-ietf-oauth-v2-15), its conformance target is a draft, not the standard. Everything we build on it inherits a spec-conformance gap that we — not the vendor — must close. That is acceptable for a trivial authorization-code flow against a permissive IdP; it is not acceptable for anything with a security review attached.

Integration feasibility

• Composer: installable as a normal dependency, but it uses PSR-0-era autoloading and has no version constraints validated against modern PHP. Expect a compatibility spike before any estimate is credible.
• PHP 8.x: this is the gating unknown. A library whose last meaningful activity coincides with the PHP 5.3/5.4 era is a high-probability source of deprecation noise at best and fatal errors at worst. Verify on the actual runtime (8.1/8.2/8.3) with E_ALL before committing.
• Session coupling: the stock storage implementation is PHP-session oriented. In Laravel this must be swapped for an implementation backed by Laravel's session or cache store, or we will fight $_SESSION semantics, multi-node stickiness, and queue/CLI contexts where no session exists.
• HTTP layer: expect a thin cURL wrapper. No PSR-18/PSR-7 interoperability, no retry/backoff, no structured timeout policy, no middleware hook — all of which must be layered on top.
• Legal: LGPL-2.1 is a live procurement question in most enterprises. Dynamic linking via Composer is generally defensible, but any patch we apply to the library itself is arguably a derivative work with source-disclosure obligations. Given we will almost certainly need to patch it for PHP 8, this is not a theoretical concern. Route to legal early; do not let it become a release-week blocker.

Technical risk

• Spec drift (high): draft-15 predates PKCE (RFC 7636), OpenID Connect, token revocation (RFC 7009), introspection (RFC 7662), authorization-server metadata/discovery (RFC 8414), and refresh-token rotation. Most modern IdPs now require PKCE for public clients and many enforce sender-constrained or rotating refresh tokens. Any of these requirements converts the package from "adopt" to "fork and own."
• Security posture (high): there is no active maintainer, therefore no CVE response path. state handling, redirect-URI strictness, and token-endpoint error normalization need to be read line by line rather than assumed.
• Abandonment (high): 0 dependents is the decisive signal. 393 stars is a 2011-era popularity artifact, not evidence of current fitness. No dependents means no downstream bug discovery, no forks carrying fixes, no community to ask.
• Maintenance ceiling (medium): the API surface is small enough that we could vendor and maintain it, but we would be paying a permanent tax to preserve a weaker, non-standard implementation of something the ecosystem already solved.

Key questions

1. Are we consuming an IdP (client role) or exposing one (server role)? Only the former is in scope for this package.
2. Which providers, and do any mandate PKCE, OIDC/ID-token validation, discovery, or refresh-token rotation?
3. What is our committed PHP runtime matrix, and does this package execute cleanly on all of it?
4. Has legal cleared LGPL-2.1 for a distributed or SaaS product, including the patch scenario?
5. Is the actual requirement "OAuth login" (→ Socialite) or "arbitrary provider OAuth client" (→ league/oauth2-client)? Both are maintained and both are cheaper than adopting this.
6. If we proceed, who owns the fork when PHP 8.5 lands?

Integration Approach

Stack fit

• Poor-to-adequate. Laravel already has first-class answers: laravel/socialite (+ socialiteproviders/*) for consumer identity providers, and league/oauth2-client with its provider packages for machine-to-machine and generic OAuth. Both are actively maintained, PSR-compliant, PHP 8-ready, and MIT-licensed.
• adoy/oauth2 only wins on one axis: it is small, dependency-free, and easy to read end to end. That is real value in an air-gapped or dependency-averse environment — and roughly the only environment where I would defend it.

Migration path

• Do not let it leak. Define a narrow internal contract (OAuthClient::redirect(), ::exchangeCode(), ::refresh(), ::withToken()) and bind adoy/oauth2 behind it in a service provider. Config in config/services.php, secrets in the standard Laravel encrypted env path.
• The contract is the migration plan. Swapping to league/oauth2-client then becomes a one-class reimplementation plus a provider-package install, not a refactor of every call site.
• If a PoC is required to de-risk, time-box it to a spike branch against a sandbox tenant and treat it as disposable — never as the foundation.

Compatibility

• Verify: PHP 8.x fatal-error-free execution, Composer 2 resolution, no reliance on removed functions, and no dynamic-property deprecation floods.
• Replace the stock session storage with a Laravel-backed implementation from day one. Do not ship the $_SESSION path.
• Wrap the HTTP calls in a Laravel-configured client (timeouts, TLS verification, proxy, retry) rather than trusting the library's defaults.

Sequencing

1. Requirements lock — provider list, PKCE/OIDC/rotation mandates, PHP matrix. (1 week)
2. License and security review — LGPL opinion plus a manual read of token/state handling. Runs in parallel; it is a gate, not a task.
3. Build-vs-adopt decision — compare league/oauth2-client (+ provider package) against adoy on the same two-week integration spike. Default the recommendation to the maintained option.
4. Wrap or replace — if adoy survives step 3, ship it only behind the internal contract; otherwise land league/oauth2-client directly and skip the abstraction debt.
5. Integration tests against a sandbox IdP covering happy path, expired token, refresh, revoked refresh token, and malformed error responses.

Operational Impact

Maintenance

• The package is effectively unmaintained: no security releases, no roadmap, no responsiveness. Every future PHP upgrade re-opens the compatibility question, and we absorb the cost each time. Budget it as an owned internal component, not a dependency — because that is what it becomes the moment we patch it.

Support

• No vendor support, no current documentation beyond a README written against a draft spec, and no community to escalate to. Internal ramp-up material must be authored by us. Expect ~1 engineer-day to learn the API and considerably more to learn where it silently diverges from the final RFC.

Scaling

• The library is stateless apart from token storage, so throughput scales with our app, not with it. The real scaling concern is state and token handling across horizontally scaled nodes: state values and token caches must live in Redis/shared cache, not local sessions, or users will intermittently fail the callback leg behind a load balancer.
• Refresh concurrency is unhandled. Multiple workers holding the same expiring token will stampede the token endpoint; if the IdP rotates refresh tokens, that stampede invalidates itself and produces intermittent auth failures that are painful to diagnose. We would need a lock around refresh — a thing league/oauth2-client communities have already solved.

Failure modes

• Silent expiry: no proactive refresh, so failures surface as 401s deep in business logic rather than at the boundary.
• Refresh-token rotation: the draft-15 assumption of reusable refresh tokens breaks against modern IdPs and manifests as sporadic, non-reproducible logouts.
• PKCE-required providers: outright handshake failure — a hard blocker, not a degradation.
• Malformed error responses: draft-15 error shapes differ from RFC 6749; parsing may misclassify invalid_grant and mask revocation as a transient error, driving retry storms.
• State/CSRF gaps: if validation is lax, we ship a login-CSRF vulnerability that no scanner will flag as a dependency CVE.
• Unpinned endpoints: no discovery means hardcoded URLs; provider-side endpoint changes become our outage.

Ramp-up

• Trivial to read, hard to trust. A mid-level engineer will be productive in a day; knowing which guarantees are missing requires someone who knows the final OAuth 2.0 spec well enough to compensate. That senior-review requirement is a recurring cost on every change touching auth, and it is the strongest argument for adopting a maintained library instead.

TPM recommendation: Do not adopt. Score 13.2 with 0 dependents, a draft-spec foundation, LGPL-2.1 entanglement on a codebase we will inevitably patch, and no security response path is a clear no for anything customer-facing. Frame the opportunity (41.7) correctly: it signals a genuine niche for a minimal OAuth client, not a mandate to use a fourteen-year-old one. Re-run the spike against league/oauth2-client; only revisit adoy if a hard constraint — air-gapped, no-dependency policy, or a pinned legacy runtime — eliminates the maintained options.