fideloper/proxy (Laravel Trusted Proxies)

fideloper/proxy (published on Packagist as fideloper/proxy, the repo is named TrustedProxy) is a small Laravel middleware package that tells the framework which reverse proxies or load balancers to trust and which forwarded headers to read from them. Without it, an app running behind a load balancer, CDN, or reverse proxy sees the proxy’s IP address and scheme instead of the real client’s, breaking URL generation, HTTPS redirects, session cookies, and IP-based logging.

The package registers a TrustProxies middleware and a trustedproxy.php config file where developers list trusted proxy IPs (or * to trust the calling IP) and choose which X-Forwarded-* / RFC 7239 Forwarded headers to honor. It became so central to Laravel deployments that Laravel 5.5+ bundles equivalent functionality directly in the framework, and this package remains available for older Laravel versions or standalone use.

What You Get

• A TrustProxies middleware that resets and re-applies trusted proxy settings on every incoming request
• A publishable config/trustedproxy.php file for listing trusted proxy IPs/CIDR ranges or trusting * (the calling IP)
• Configurable selection of which forwarded headers to honor (X-Forwarded-For, -Host, -Port, -Proto, AWS ELB, or RFC 7239 Forwarded)
• A Laravel service provider (TrustedProxyServiceProvider) for automatic package discovery and registration
• Compatibility shims spanning Laravel 5.x through 9.x via flexible illuminate/contracts version constraints

Common Use Cases

• Running a Laravel app behind AWS ELB/ALB, Nginx, or Cloudflare so HTTPS redirects and url() helpers resolve correctly
• Fixing session/cookie issues caused by the app seeing the load balancer’s IP instead of the visitor’s
• Enabling accurate IP-based rate limiting or logging when traffic passes through a reverse proxy
• Supporting older Laravel versions (pre-5.5) that don’t ship trusted-proxy handling natively

Under The Hood

Architecture — The entire package is three files: a service provider that merges and publishes trustedproxy.php config, and the TrustProxies middleware whose handle() method resets Laravel’s static trusted-proxy state on every request (important because it’s otherwise cached process-wide) and then re-applies either a specific IP list or the calling REMOTE_ADDR, before delegating header-name resolution to a small switch over Request::HEADER_* constants. Tech Stack — Plain PHP 5.4+/8-compatible code with a single real dependency, illuminate/contracts, kept intentionally broad (^5.0 through ^9.0) so the package works across many Laravel major versions without forcing upgrades. Code Quality — The middleware is short, single-responsibility, and documented with full docblocks on every method; test coverage exists via PHPUnit/Mockery against illuminate/http, though the project’s low commit velocity (last pushed January 2024) means it functions mainly as a stable, feature-frozen compatibility shim rather than actively evolving code. API Design — Zero-config by default beyond registering the middleware and setting one config value (proxies), making adoption a two-line change; the */** wildcard for “trust the calling IP” is a pragmatic shortcut for local/staging environments, clearly flagged in code as legacy-compatible.