IP Address Middleware

akrabat/ip-address-middleware is a PSR-15 middleware component for PHP that inspects an incoming ServerRequest, optionally checks a configurable list of trusted-proxy headers (X-Forwarded-For, Forwarded, CloudFlare’s CF-Connecting-IP, etc.), and stores the resolved client IP address as a request attribute (ip_address by default) for downstream middleware and route handlers to read. It integrates directly with Slim, Laminas, and Mezzio applications, including a bundled Mezzio ConfigProvider for zero-config wiring.

What You Get

• A single IpAddress PSR-15 middleware class configurable via 5 constructor parameters (proxy-header checking, trusted proxies, attribute name, headers to inspect, hop count)
• Built-in support for common proxy headers plus documented presets for nginx (X-Real-IP) and CloudFlare (CF-Connecting-IP) deployments
• A bundled Mezzio ConfigProvider (src/Mezzio/) for drop-in configuration in Laminas/Mezzio pipelines
• CIDR and wildcard support for specifying trusted-proxy IP ranges

Common Use Cases

• Recording the real client IP for audit logs or rate limiting when an app runs behind a load balancer or reverse proxy
• Extracting the correct visitor IP behind CloudFlare or another CDN using the documented header presets
• Wiring IP detection into a Slim, Laminas, or Mezzio application with a single middleware registration
• Restricting which upstream proxies are trusted before honoring any forwarded-IP header, to reduce spoofing risk

Under The Hood

Architecture - The entire library is a single class, src/IpAddress.php (~377 lines), implementing PSR-15’s MiddlewareInterface; it resolves the IP by walking the configured list of headers only when the request’s REMOTE_ADDR matches an entry in the trusted-proxies list, falling back to REMOTE_ADDR otherwise, then attaches the result via ServerRequest::withAttribute(). A small src/Mezzio/ConfigProvider.php supplies framework-specific wiring for Laminas/Mezzio’s config-driven pipeline. Tech Stack - Plain PHP (^7.2 || ^8.0) with no runtime dependencies beyond PSR interfaces (psr/http-message, psr/http-server-middleware, psr/container), managed via Composer with laminas/laminas-diactoros and PHPUnit as dev-only dependencies for testing against real PSR-7 request objects. Code Quality - tests/IpAddressTest.php is a substantial single-file test suite (~488 lines, larger than the source file itself) covering proxy-header parsing, trusted-proxy matching, CIDR/wildcard behavior, and hop-count logic, run via composer test/phpunit with PHP_CodeSniffer enforcing style via composer cs. API Design - The middleware favors explicit, positional constructor configuration over magic defaults, and documents concrete header-list presets for the two most common deployment scenarios (nginx, CloudFlare) directly in the README, minimizing the trial-and-error typically involved in getting proxy-header handling right.