Ip Lib Laravel Package

Product Decisions This Supports

• Feature enablement: IP allowlists/denylists for admin panels, API access, partner integrations, and per-tenant network restrictions (enterprise/VPN gating).
• Security roadmap: subnet-based blocking, abuse mitigation, and rate limiting by CIDR rather than single address.
• Webhook and integration trust: verifying inbound requests originate from a provider's published IP ranges (e.g., payment, CI, or messaging vendors) instead of shared secrets alone.
• IPv6 readiness: a credible answer to "can we support IPv6 without a rewrite?" — parse, normalize, and compare v4/v6 and v4-mapped-v6 consistently. The 1.22.1 patch specifically hardened the v4-mapped-v6 path (correct range typing and pattern stringification), so mixed-family behavior is now the best-tested it has been.
• Input hardening: strict parsing that rejects trailing newlines and trailing text after addresses, and rejects malformed IPv6 reverse-DNS names. This matters wherever addresses arrive from headers, config, or user input — lenient parsers are how allowlist checks get bypassed or mislogged.
• Infrastructure hygiene: validating X-Forwarded-For against trusted proxy/load-balancer ranges so audit logs and rate limits aren't spoofable.
• Data quality and compliance: canonical IP storage in audit trails and analytics, avoiding duplicate-identity bugs from mixed notations. The Subnet::asPattern() end-address fix improves fidelity when we persist or export approved ranges.
• Build vs. buy: adopt a maintained, MIT-licensed primitive instead of owning security-sensitive IP arithmetic in-house. The 1.22.1 changelog — seven correctness fixes and a coverage increase in a patch release — is direct evidence of active maintenance on exactly the edge cases we would get wrong ourselves.
• Explicit non-goal: this is not a geolocation, ASN, or threat-intelligence product; those remain separate buy decisions.

When to Consider This Package

Adopt when:

• The stack is PHP/Laravel and you need real CIDR arithmetic — membership tests, intersection, subtraction, range merging — not just string validation.
• Correct IPv6 behavior matters, including mixed v4/v6 environments and 32-bit hosts where ip2long overflows.
• You want a dependency-free, permissively licensed library with no runtime service, external API, or data feed.
• The code path is security-relevant, where a hand-rolled regex or integer comparison is a liability.
• You need deterministic, offline, unit-testable behavior in CI.

Look elsewhere when:

• You need country, city, or ASN lookup — pair a GeoIP database (e.g., MaxMind) or a geo API instead; this library only handles addresses and ranges.
• Blocking should happen at the edge — a WAF, CDN, or load balancer is the right control point, not application code.
• You need to enrich from threat-intelligence feeds; this parses ranges but does not supply them.
• Throughput requirements are extreme (bulk offline processing of billions of records) — consider native extensions or a dedicated service.
• The relevant service is not PHP — choose the equivalent primitive in that ecosystem rather than bridging.

Upgrade note (1.22.0 → 1.22.1): no new API, no deprecations, no breaking changes we rely on. Behavior tightens in two places: strings with trailing newlines or trailing text are now rejected rather than partially parsed, and IPv4-mapped IPv6 ranges/patterns are normalized to IPv4 form. Any stored allowlist entries or config values that previously "worked" only because of lenient parsing should be re-validated — that is a cleanup we want, not a regression.

How to Pitch It (Stakeholders)

For executives: This is a small, free, MIT-licensed building block that lets us ship IP-based access control and webhook verification faster and more safely. It replaces custom, security-sensitive parsing code that historically breaks on IPv6 — a known source of outages and audit findings. Adoption cost is a Composer dependency; switching costs later are low. It reduces risk and unblocks a class of network-aware features without new infrastructure or vendor spend. The project is actively maintained: the latest patch (1.22.1) is entirely correctness fixes on IPv6 and input-parsing edge cases — precisely the bugs we would otherwise inherit and have to debug in production.

For engineering: A mature, dependency-free PHP library for IPv4, IPv6, and IP ranges: parsing and validation, normalization, containment checks, and set operations (intersect, subtract, merge), with correct handling of v4-mapped-v6 addresses. Drop-in via Composer, no services or configuration, straightforward to unit test. It directly replaces ad-hoc ip2long/regex logic and is the correct primitive for trusted-proxy validation, allowlisting, and webhook source checks.

Upgrade to 1.22.1 is recommended and low-risk: no API changes. It fixes Subnet::asPattern() returning the wrong end address, fixes Pattern::toString() for IPv6 patterns with an IPv4-mapped prefix, uses the IPv4 range type for IPv4-mapped IPv6 ranges, and — relevant to our threat model — no longer accepts trailing newlines or trailing text when parsing addresses, nor malformed IPv6 reverse-DNS names. If we log or compare raw parsed values, expect cleaner canonical output; add a regression test asserting rejection of trailing whitespace/newline input in any allowlist code path.

It is deliberately scoped: bring your own geolocation or threat data if the roadmap needs it.