Weave Code
Client Ip Laravel Package
middlewares/client-ip
A Laravel middleware for reliably resolving the client's real IP address, including requests passing through proxies, load balancers, and CDNs. Supports forwarded headers and configurable trusted proxies for accurate IP detection.
middlewares/client-ip is a Laravel middleware that reliably resolves the real client IP behind proxies, load balancers, and CDNs. It reads forwarded headers, sets the request’s client IP, and restores the original value afterwards—keeping your app’s state clean.
- Trusted proxy and header configuration
- Correct handling of
X-Forwarded-Forchains - Automatic IP restoration after each request
- Simple integration with Laravel’s middleware stack
Frequently asked questions about Client Ip
- What does the middlewares/client-ip package do?
- It is a single-responsibility PSR-15 middleware that resolves the client IP address from an incoming request and saves it as a request attribute so later middleware and handlers can read it without recomputing. Because it implements the PSR-15 middleware contract, it composes into any PSR-15 pipeline such as Slim, Mezzio, or Laminas. It has no database, queue, or other heavyweight dependencies.
- Is middlewares/client-ip compatible with Laravel?
- Not natively. Laravel's HTTP kernel uses its own handle($request, Closure $next) contract rather than PSR-15, so you need an adapter or a thin wrapper middleware that converts the Laravel request to PSR-7, delegates to the PSR-15 instance, and copies the attribute back. For most Laravel applications the built-in TrustProxies middleware plus $request->ip() already covers the same use case without an extra dependency.
- How do I install middlewares/client-ip with Composer?
- Run composer require middlewares/client-ip, then register the middleware in your PSR-15 pipeline, typically right after error-handling middleware so the resolved IP is available to everything downstream. In a Laravel app you also need a PSR-15 bridge registered before this line does anything useful. Confirm the supported PHP and PSR-15 versions in composer.json before installing.
- Does it honor a trusted-proxy list when reading X-Forwarded-For?
- That is the most important thing to verify before adoption: a correct implementation only trusts forwarded headers when the immediate peer is in a configured trusted-proxy allowlist. If it trusts X-Forwarded-For unconditionally, any client can spoof their address with a header. Read the source and test against a known set of header cases behind your actual CDN or load balancer.
- Which request attribute does it set, and is the attribute key configurable?
- The middleware writes the resolved address to a request attribute that downstream code reads with $request->getAttribute(). Whether that key is configurable or hard-coded needs to be confirmed in the source. If it is fixed, wrap the lookup in a small internal accessor so the stringly-typed name does not spread across your codebase, and check it does not collide with attributes your framework already sets.
- Which PHP and PSR-15 versions does it support?
- Because it is a PSR-15 middleware, check whether it implements v1 or v2 of the psr/http-server-middleware interface and match that to your runtime. Look at composer.json for the supported PHP range and which PSR-7 implementation it is tested against, such as Nyholm, Laminas Diactoros, or Guzzle. A CI matrix covering those combinations is the best signal that the compatibility claims are maintained.
- How does middlewares/client-ip compare to Laravel's TrustProxies and Request::ip()?
- Laravel already ships mature trusted-proxy handling in App\Http\Middleware\TrustProxies, and $request->ip() returns the resolved client address anywhere in the framework. For a Laravel-only application this package duplicates that behavior and adds a PSR-15 bridge on top. It makes more sense when you maintain a shared middleware library that must run across several frameworks, including PSR-15-native ones like Slim or Mezzio.
- Is it safe to use behind Cloudflare or an AWS load balancer?
- Only if the middleware restricts forwarded-header parsing to known proxy addresses, since CDNs and load balancers add their own headers and hop chains. Deploy to staging behind the real edge and assert the resolved IP for X-Forwarded-For chains, CDN-specific headers, IPv4-mapped IPv6, and requests carrying spoofed headers. Do not trust the resolved value for authorization or rate limiting until that verification passes.
- How do I test that the correct client IP is being resolved?
- Write unit tests that build PSR-7 requests with synthetic forwarded headers and assert the resulting attribute, covering single-hop, multi-hop, untrusted peer, and missing-header cases. Then run an integration check in staging behind the actual proxy so real header behavior is exercised. Also verify how IPv4 and IPv6 addresses with ports or zone identifiers are normalized.
- Is middlewares/client-ip actively maintained and safe to depend on?
- The signals are thin: a small star count, a single release around March 2025, and an unresolved repository location that prevents reviewing commit history, CI status, or maintainer responsiveness. MIT licensing keeps it low friction, but that provenance gap is a supply-chain consideration worth weighing. If you adopt it, pin the version and review the IP-resolution logic yourself.
Weaver
How can I help you explore Laravel packages today?