Ip Laravel Package

Getting Started

• Install with composer require josantonius/ip. There are no framework bindings, service providers, or config files — it is a single utility class.
• Read src/IP.php first. It's a tiny, static-only class; 5 minutes of reading tells you everything the README does not. Confirm which $_SERVER keys it inspects and what order it prefers before trusting it.
• First use case is replacing ad-hoc $_SERVER['REMOTE_ADDR'] lookups in a controller, middleware, or logger with IP::get():

use Josantonius\IP\IP;

$ip = IP::get();

• Because it's a static helper, you can drop it into an existing app without touching DI, config, or bootstrapping. That is its main selling point — and essentially its only one.
• If you only ever call it from behind a known proxy, go straight to the "Implementation Patterns" section; the default behavior is the thing you will need to override first.

Implementation Patterns

• Middleware-first. Resolve the IP once in a middleware and attach it to the request (or a request-scoped context object), then read it downstream. Calling IP::get() in ten places means ten places to fix when your proxy topology changes.
• Logging. The most common real use: prefix each log entry with the client IP. Wrap the call so a null becomes '-' instead of an empty string.
• Proxy / CDN setup. If you sit behind Nginx, Cloudflare, an ALB, or any load balancer, REMOTE_ADDR is the proxy, not the client. Configure the class to prefer the header your edge actually sets (X-Forwarded-For, CF-Connecting-IP, True-Client-IP, X-Real-IP). Only trust these when the immediate peer is a known proxy.
• Validation layer. The class returns a string; it does not certify that string is a valid IP. Follow up with filter_var($ip, FILTER_VALIDATE_IP) before persisting, geolocating, or rate-limiting on it.
• Rate limiting / abuse control. Keying a limiter on the resolved IP works, but only after you've enforced the proxy trust boundary above — otherwise a client can spoof X-Forwarded-For and evade the limit trivially.
• Analytics and geo. Feed the validated IP into your GeoIP lookup of choice. Keep the raw value too if the downstream service distinguishes IPv4 from IPv6.
• Testing pattern. Since the class is static, wrap it in your own small interface (e.g. IpResolver with a resolve(): ?string method) so tests can substitute a fake. This also isolates you from the package being archived.
• Fork-and-vendor pattern. Given 0 dependents and an archived repo, the pragmatic long-term pattern is to copy the ~50 lines into app/Support/Ip.php and own it. You get the same behavior, no abandoned dependency, and no lock-file churn.

Gotchas and Tips

• The repo is archived (last release 2022-07-30). No bug fixes, no PHP version bumps, no security patches. It will keep working for the narrow thing it does, but do not expect it to grow. Treat it as a snippet, not a dependency you plan around.
• X-Forwarded-For is a list, not a value. It arrives as client, proxy1, proxy2. If you point the class at this header, you get the whole string back. Parse it yourself and take the left-most entry only after verifying the number of trusted hops.
• Proxy header spoofing. Any client can send X-Forwarded-For: 1.2.3.4. If your app is directly internet-facing, trusting that header is a vulnerability. Only read forwarded headers when REMOTE_ADDR is in your known-proxy CIDR list.
• Null on missing key. When the configured server key isn't set, expect null (or an empty string, depending on the version — verify in source). Always coerce before writing to a VARCHAR IP column or a typed property.
• Static state leaks across tests. If you call the setter to change the source method, the change persists for the rest of the process. There is no reset(). In PHPUnit this can quietly affect other tests in the same process — reset manually in tearDown.
• IPv6. Confirm the returned value isn't truncated or reformatted anywhere in your pipeline. Some downstream GeoIP and rate-limiter libraries only accept IPv4; normalize before handing off.
• No filter_var guard built in. The package does not validate; treat its output as untrusted input until you've validated it.
• Debugging tip. When the result looks wrong, dump $_SERVER['REMOTE_ADDR'] first, then the forwarded header. Nine times out of ten the class is behaving correctly and your proxy chain is the thing you're misreading.
• Extension points. There are effectively none — no events, no interfaces, no config. The extension point is the fork. This is a feature if you want it gone from your dependency graph.