Proxy Laravel Package

Technical Evaluation

Architecture fit. jenssegers/proxy is a tactical integration enabler, not a platform capability, and should be classified that way on the roadmap. Functionally it is a thin Guzzle wrapper that forwards get/post/put/delete calls to a configured upstream and returns the response — enough to support a narrow server-side BFF route that injects credentials or hides a fixed upstream from the browser. It provides no TLS termination, connection pooling, caching, access control, rate limiting, or policy enforcement, so it must not be positioned to stakeholders as "reverse proxy infrastructure." It is a reasonable fit only when the requirement is a fixed, allowlisted upstream at low volume; if the organization already standardizes on an API gateway, nginx proxy_pass, Envoy, or a shared Guzzle/PSR-18 client, the package adds dependency surface without adding capability.

Integration feasibility. Time-to-first-working-call is cheap — an afternoon to a day — but the durable cost is ownership, not integration. The package is effectively unmaintained: v3.1.0 bumped the floor to PHP 7.1, there are zero dependents, and there is no visible release cadence. Compatibility with PHP 8.x and Laravel 9/10/11 must be executed and evidenced in CI, not inferred from the README. The Laravel service provider and session-backed cookie store live in a separate jenssegers/proxy-laravel package, which doubles the surface to assess. A TPM should scope this as a 1–2 day time-boxed feasibility spike with a written go/no-go outcome, not an open-ended integration story.

Technical risk. Register these with named owners and acceptance criteria before any build starts:

• SSRF / open-proxy exposure — critical if the target URL is caller-influenced. The library enforces no allowlist; that control lives entirely in an owned wrapper. A "no" on fixed-or-allowlisted upstream closes the evaluation.
• Header and cookie passthrough — high. Inbound cookies can leak upstream, and upstream Set-Cookie/Location can leak into the origin. Default behavior is unsafe for anything user-facing.
• Resource exhaustion — high. Blocking calls without enforced connect/total timeouts, redirect caps, or response-size ceilings pin PHP-FPM workers and buffer full payloads in memory.
• Silent misconfiguration — medium. Missing Host/Content-Length handling produces hard-to-trace upstream failures with no diagnostics from the package.
• Dependency abandonment — medium/high. Adoption without forking means shipping a component nobody patches.

All mitigation belongs in your wrapper. Any acceptance of an unpatched component should be time-boxed and explicitly signed off, not implicit.

Key questions — decision-gating, each with a named owner.

1. Is the upstream URL fixed/configured, or user-influenced? If user-influenced, close the evaluation.
2. Is this a forward proxy (client chooses destination) or a reverse proxy (we choose)? Only the latter is defensible here.
3. Which PHP/Laravel versions must run, and has anyone executed the package and its companion against them in CI?
4. What data crosses the boundary, and does forwarding it create GDPR, data-residency, or contractual obligations?
5. Do large payloads, streaming, or sub-second latency matter? If yes, disqualify.
6. Would a small internal UpstreamClient on Guzzle meet the requirement at lower total risk? Usually yes — treat this package as a reference implementation and spec, not a dependency.

Integration Approach

Stack fit. Acceptable only for a Laravel 5.x–8.x application already comfortable with Guzzle, where a small fixed set of upstreams sits behind a BFF route. Poor fit for PSR-18-normalized codebases, queue workers, serverless runtimes billed on blocking I/O, high-volume paths, or organizations where a gateway route already owns the concern. Adopting it also bypasses the retry, instrumentation, and middleware layers a shared HTTP client would otherwise supply — the program must budget to recreate those around the wrapper.

Migration path. Frame this as vendoring a component, not taking a dependency. Because the surface is small — one primary class plus a cookie-store contract — the cheapest durable path is to copy the relevant logic into app/Support/Proxy, re-implement client wiring against your hardening rules, and bind it behind an internal interface such as UpstreamFetcher. That converts an abandoned dependency into an owned internal component with a stable API and a real upgrade path. If the team already runs Guzzle, a ProxyController plus middleware for auth and base URI is functionally equivalent and better instrumented; the package's only genuine value-add is cookie-jar plumbing and token injection you would otherwise hand-roll. Either way, define the exit plan before the first commit.

Compatibility. Require evidence, not vendor claims. Validate a matrix covering PHP versions in use, ext-curl presence, Laravel package auto-discovery on supported versions, behavior under declare(strict_types=1) and PHP 8.1+ deprecation notices, and composer.json platform bounds. Confirm separately whether the companion jenssegers/proxy-laravel package is required and whether its freshness is acceptable — one abandoned dependency is a line item; two is a pattern. Treat --ignore-platform-reqs as a red flag and reject it as a workaround.

Sequencing — with gates and owners.

1. Scope confirmation (Gate 0). Fixed/allowlisted upstreams and reverse-proxy direction confirmed. Owner: TPM/product. Exit: signed scope statement or evaluation closes.
2. Feasibility spike (1–2 days). Standalone script on the exact PHP/Laravel target; measure latency overhead and memory on realistic payloads. Owner: feature engineer. Exit: metrics + compatibility evidence.
3. Security review as a blocking gate (Gate 1). SSRF, header allow/deny policy, cookie scoping, redirect policy, TLS verification, response header sanitization. Owner: security. No go-live without sign-off.
4. Wrap and harden (Gate 2). Internal UpstreamFetcher interface, one proxy instance per upstream, allowlist with URL normalization, connect/total timeouts, redirect caps, max body size, explicit forwarded-header allowlist, stripping of upstream Set-Cookie/Location. Owner: feature team.
5. Instrument. Upstream status, latency, error rate — the package emits nothing on its own. Owner: platform/SRE.
6. Build-vs-adopt decision (Gate 3). Compare risk-adjusted cost of fork-and-own versus Guzzle middleware or a gateway route. Owner: TPM with engineering and security. Default expectation: the build/gateway option wins.

Operational Impact

Maintenance. Upstream maintenance is effectively zero, so ownership transfers to the adopting team on day one. The absolute cost is low — an engineer can read the whole codebase in an hour — but it recurs: budget a recurring line item to re-review the fork on each PHP minor upgrade and for Guzzle/cURL behavior changes. If adopted without forking, the program is carrying a component nobody patches, which must be recorded as an accepted risk with an expiry date.

Support. Community-only: no SLA, no security contact, no release notes to track. Internal support lands on whichever team owns the wrapper. Require an in-repo decision record documenting the allowlist, header policy, and timeout settings, or the next developer will "simplify" the controller and quietly remove the protections.

Scaling. Linear and pessimistic. Every proxied call doubles bandwidth through the application tier and pins one PHP-FPM worker for the full upstream duration, so the throughput ceiling is roughly worker pool ÷ upstream latency. For capacity planning, forecast expected volume against available workers and set an explicit volume threshold at which the route moves to the edge — nginx proxy_pass, a gateway route, or an edge worker — leaving the PHP wrapper only for low-volume, high-control cases.

Failure modes to instrument and alert on. Upstream timeout cascading into worker exhaustion; unbounded response body causing OOM kills; redirect chains resolving to internal IPs (SSRF); upstream Set-Cookie/Location leaking into the origin's cookie jar and redirect flow; allowlist bypass via URL-parsing edge cases (encoded dots, userinfo, trailing-dot hosts, IPv6 literals); TLS verification disabled "temporarily" and never restored; per-request cookie jars silently making every call look like a new visitor and breaking upstream session flows; and open-proxy abuse where the allowlist is missing or request-configurable. Assign an owner, dashboard, and runbook to each before go-live.

Ramp-up. Low but non-zero and concentrated in the wrapper, not the library. Expect roughly a half-day for a mid-level Laravel engineer to reproduce forwarding behavior, plus one to two days to build the hardened layer that actually makes it safe — allowlisting, timeout policy, header hygiene, observability. Plan a short handover artifact (ADR plus runbook) so on-call can diagnose upstream failures without reading third-party source. If the team cannot name an owner for that wrapper, the correct roadmap decision is to route the concern to the gateway and not adopt the package at all.