Ip Utils Laravel Package

Technical Evaluation

Architecture fit. wikimedia/ip-utils is a framework-agnostic, dependency-light PHP library for IPv4/IPv6 parsing, validation, CIDR handling, range containment, and hex/normalized representations. It slots into Laravel as a plain Composer dependency with no service provider, config, or bootstrap ceremony. The classes are largely static/stateless, so they are safe to call from middleware, form requests, policies, jobs, and Artisan commands. The important caveat is overlap: Laravel already ships Symfony\Component\HttpFoundation\IpUtils via illuminate/http, which covers checkIp, checkIp4, and checkIp6. A TPM should position wikimedia/ip-utils as a specialist dependency for capabilities Symfony does not provide — IP range parsing (start - end syntax), range-to-CIDR decomposition, IPBlock/IPRange objects, and hex normalization for storage/comparison — rather than as a general replacement for Symfony's IP checks.

Integration feasibility. High effort-to-value ratio is favorable on the technical side: composer require wikimedia/ip-utils, wrap it behind a thin application-level adapter (e.g., App\Support\Ip\IpService), and inject where needed. No native Laravel integration exists, but none is required. The main feasibility gate is not technical — it is legal and sourcing (see risks).

Technical risk.

• License (highest risk). GPL-2.0 is a strong copyleft license. Internal/SaaS use where the code is not distributed is generally defensible, but distributing the application, shipping it to on-prem customers, or embedding it in a commercial SDK triggers obligations that may be incompatible with the product's licensing model. This needs legal sign-off before adoption, not after.
• Ecosystem signals are misleading. 7 stars and 0 dependents reflect that this is a read-only mirror of a Gerrit-hosted Wikimedia library, not an abandoned package. It is used in production by MediaWiki (CheckUser, block ranges, trusted proxy handling). A TPM should not treat the low score as a quality signal, but should also not treat the mirror as the support channel.
• Contribution/support path is non-standard. Issues and PRs on GitHub are not the workflow; contribution requires Wikimedia developer access and Gerrit. Bug turnaround depends on Wikimedia Foundation priorities, not on our roadmap.
• API stability. It is an internal library extracted for MediaWiki's needs. Versioning and BC guarantees are not oriented around third-party consumers; pin versions and cover with tests.
• Competing, better-licensed alternatives. mlocati/ip-lib (MIT) offers comparable or richer range/CIDR functionality with far broader adoption, and Symfony's IpUtils is already in the dependency tree. The justification for accepting GPL-2.0 must be a capability gap that alternatives cannot fill.

Key questions.

1. Which specific capabilities do we need that Symfony IpUtils and mlocati/ip-lib do not provide? If none, this evaluation ends here.
2. What is our distribution model — SaaS only, or shipped/on-prem/embedded? This determines whether GPL-2.0 is a blocker or a manageable internal-only risk.
3. Has legal reviewed GPL-2.0 for our product and dependency policy?
4. Do we need MediaWiki-compatible semantics (e.g., how it treats IPv6 ranges, hex storage, invalid input) specifically, or just "correct IP math"?
5. Who owns upgrades and security patching if upstream Gerrit slows down?

Integration Approach

Stack fit. Framework-agnostic PHP with minimal runtime dependencies; compatible with Laravel 8–11 subject to the package's composer.json PHP constraint (verify before pinning). It has no facades, no config, and no global state, so it composes cleanly with Laravel's container. Recommended shape: a single IpService adapter exposing the handful of operations we actually use (isValid, inRange, parseRange, rangeToCidr, toHex), with the third-party library confined behind it.

Migration path. Do not rip out Symfony IpUtils where it already works. Sequence: (1) inventory current IP logic and classify each use as CIDR containment (keep Symfony) or range/hex/block semantics (candidate for wikimedia); (2) introduce the IpService adapter with the existing Symfony implementation behind it; (3) add wikimedia/ip-utils as a second backend only for the gap capabilities; (4) A/B the two implementations against a shared test corpus; (5) consolidate to one backend once behavior is proven equivalent or intentionally divergent. This keeps the migration reversible and prevents a library choice from leaking into domain code.

Compatibility. Verify PHP constraint against our runtime, confirm behavior for IPv4-mapped IPv6, compressed vs. expanded IPv6, leading zeros, and invalid input (exception vs. false). These semantics differ across libraries and are the likeliest source of production surprises. Also confirm no conflicting transitive constraints with symfony/http-foundation.

Sequencing.

1. Capability gap analysis vs. Symfony IpUtils and mlocati/ip-lib.
2. Legal/licensing review of GPL-2.0 against distribution model.
3. Decision: adopt, adopt-with-adapter, or reject in favor of MIT alternative.
4. Spike (1–2 days): adapter + parity test suite over a representative IP corpus.
5. Rollout behind the adapter; no direct library references in domain code.
6. Document the swap point so the backend can be replaced without touching call sites.

Operational Impact

Maintenance. Low runtime maintenance, moderate governance maintenance. The library is stable and small, but it is a mirror: pin an exact version, monitor the Gerrit repository (not GitHub) for releases and security notes, and track PHP version support. Because it is maintained for MediaWiki, expect it to remain functional but not to prioritize third-party feature requests.

Support. No commercial support and no vendor SLA. Community support routes through Wikimedia Phabricator/Gerrit, which is appropriate for a Wikimedia-shaped problem and awkward for a product team with deadlines. Mitigation: the adapter boundary plus a parity test suite means we can fork, patch, or replace with mlocati/ip-lib in hours rather than weeks.

Scaling. Effectively a non-issue. Operations are CPU-bound string/bit manipulation with no I/O and no state; per-request cost is microseconds. The real scaling consideration is volume of call sites — if IP checks appear in hot middleware paths, precompute parsed range objects or cache them rather than re-parsing CIDR lists per request. No horizontal scaling or infrastructure implications.

Failure modes.

• License contamination — the one failure mode with lasting business impact; requires a legal gate before merge.
• Semantic mismatch — a range that Symfony treats as valid but wikimedia rejects (or vice versa), producing silent allow/deny errors in security-sensitive paths. Mitigate with a shared parity corpus and explicit tests around IPv6 edge cases.
• Unvalidated input reaching the parser — confirm whether the library throws or returns false on malformed input and handle both at the adapter boundary.
• Abandoned-pin drift — a pinned version that never gets updated because nobody watches Gerrit. Assign an owner and a quarterly review.
• Upstream divergence — MediaWiki-specific semantics changing in a minor release; pin and review changelogs.

Ramp-up. Low for engineers (small, readable API; a half-day to productive), but non-trivial for process: the team must learn that GitHub is a mirror, that contributions go through Gerrit, and that upstream priorities are not ours. Budget 1–2 days for the adapter and parity suite, plus legal review lead time — which, in practice, is the critical path.

TPM recommendation. Treat this as a conditional dependency. The technical fit for specialist IP range/hex operations is good, and the low star count is an artifact of the Gerrit mirror rather than a quality signal. However, GPL-2.0 is a material constraint for any distributed or embedded product, and mlocati/ip-lib (MIT) covers most of the same ground with better third-party ergonomics. Proceed only if (a) a concrete capability gap is documented, (b) legal clears GPL-2.0 for our distribution model, and (c) the work is delivered behind an adapter that keeps the backend swappable.