Download the PHP package chubbyphp/chubbyphp-trusted-proxy without Composer

chubbyphp-trusted-proxy

Description

A trusted proxy middleware for PSR 15: resolves the client ip, scheme and host from the forwarded headers (X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host) of trusted proxies into request attributes.

Requirements

• php: ^8.3

Suggest

Installation

Through Composer as chubbyphp/chubbyphp-trusted-proxy.

Usage

Behind a reverse proxy (nginx, traefik, a load balancer, ...) the server only sees the proxy, the client data arrives within the forwarded headers, which any client can send as well. The middleware decides which entries of these headers to trust and passes the request on with the clientIp, scheme and host attributes set, so that every other part (rate limiting, logging, access control, url generation, ...) reads them from one place instead of parsing headers.

Register the middleware before any middleware that reads the attributes. Requests without a resolvable client ip (no X-Forwarded-For, only trusted entries, or a first untrusted entry which is not a valid ip like unknown or ip:port) get null attributes. The middleware always sets all three attributes (the unresolved ones as null), so that nothing set before it survives. A subnet matching every ip (0.0.0.0/0, ::/0) gets rejected, as it would trust every entry and never resolve anything, an empty list as well, as it would trust no entry and resolve the nearest proxy as client ip, the entries get trimmed. Ipv4 mapped ipv6 addresses (::ffff:10.0.0.1) match ipv4 subnets.

The clientIp gets canonicalized (lowercased and compressed, 2001:DB8:0:0::1 as 2001:db8::1, ipv4 mapped ipv6 addresses as ipv4, ::ffff:203.0.113.1 as 203.0.113.1), so that the same client always resolves to the same string, no matter how a hop wrote it (rate limit keys, allowlists, logs). An ipv6 address with a zone id (fe80::1%eth0) is not a valid ip.

The scheme and host get only resolved when a client ip was resolved: the entry at the same position, if the header has as many entries as the X-Forwarded-For header (proxies appending to all of them), the last (the one the nearest proxy set) otherwise. The scheme gets lowercased and must be http or https, the host gets lowercased and must be a syntactically valid host (a hostname, an ipv4 or a bracketed ipv6, each with an optional port from 1 to 65535), everything else resolves null.

Security

The trust is anchored at the address of the connection, as remoteAddress attribute (set by the server or a middleware in front, a port gets stripped) or as REMOTE_ADDR server param (as set by php-fpm, apache, ...), the attribute wins over the server param, so nothing else may set it (run the middleware before the router, a route placeholder {remoteAddress} would let the client choose it): a connection from outside the trusted ranges counts as the client itself, its address is the clientIp and the headers get ignored. An address which is not a valid ip (junk, a non string) resolves nothing, the middleware never falls back to the headers. A request without any address of the connection resolves nothing (fail closed), as the middleware cannot verify that the last hop was a trusted proxy. If the server never provides it (some runtimes build the request without server params), disable the check explicitly, the server must then not be reachable except through the proxies:

Either way, the proxies must set (or strip) all the forwarded headers, as any header they do not touch is supplied by the client: a proxy passing the client's X-Forwarded-Proto / X-Forwarded-Host through lets the client choose them, the middleware cannot tell. The clientIp is always a valid ip and the scheme always http or https, but the host is only checked for its syntax: before using it for url generation or redirects, check it against the hosts the application serves (an allowlist), so that a passed through X-Forwarded-Host cannot poison generated urls:

The RFC 7239 Forwarded header (for=...;proto=...;host=...) is not supported, only the de-facto X-Forwarded-* headers (or single value ones like X-Real-IP, see below): if the proxies send Forwarded, configure them to send the X-Forwarded-* headers as well.

Headers

The second argument replaces the header names (each one optional, null disables proto and host, for cannot be disabled, an invalid header name throws an InvalidArgumentException), useful for a proxy setting a single value header like X-Real-IP:

Service factories (chubbyphp-laminas-config-factory)

The package ships service factories (built on chubbyphp-laminas-config-factory) for a PSR 11 container, configured through config.chubbyphp.trustedProxy:

The TrustedProxyMiddlewareFactory uses the service ForwardedResolverInterface::class of the container if registered, and creates it through the shipped ForwardedResolverFactory otherwise. Register it under its name to replace it or to share it with other services.

With names

To serve different parts of an application behind different proxies (a public load balancer, an internal one, ...), the same factories can be registered multiple times with a name: the config is then read from config.chubbyphp.trustedProxy.<name> and the name gets appended to each service id.

Copyright

2026 Dominik Zogg