Reader Laravel Package

Product Decisions This Supports

• Build vs. buy for IP intelligence. This package answers "do we own the lookup path or call a vendor API?" It is the low-level, offline reader for the MaxMind DB (.mmdb) binary format — a Reader, a get() and a getWithPrefixLen(), and nothing else. If the decision is on the table, this is the cheapest possible "build" half: no per-lookup fee, no outbound HTTP, no PII leaving your infrastructure, sub-millisecond local reads.
• Feature feasibility for geo-dependent work. Geo-redirect and locale/currency defaulting, VAT and tax jurisdiction, content licensing and rights blackouts, geo-blocking and sanctions screening, fraud and abuse signals (with ISP/anonymizer databases), log enrichment, and country-based rate limiting. Every one of these is a "do we ship it?" question that hinges on whether IP→attribute lookup is cheap and reliable. This package makes it cheap; it does not make it reliable — the data does.
• Performance and infrastructure budget. The pure PHP reader (PHP 7.2+, no compilation) is fine for typical web traffic; v1.14.0 made it roughly 40% faster on City lookups. The optional C extension is a drop-in replacement for the same class — the same code, no refactor — but it adds libmaxminddb/PIE/PECL to your image build. That's an ops cost decision: adopt the extension only when lookup volume or latency SLOs justify it. Note the extension is a runtime swap, so you can defer this decision indefinitely without an architecture change.
• Database freshness as a product commitment. Roadmap item, not a code item. This package reads a file; something must fetch it (GeoIP Update, cron, sidecar). You're choosing a refresh cadence (weekly/monthly), an accuracy SLA, and a fallback path when the file is stale or missing. Budget for this or the feature slowly rots.
• Security and trust posture. v1.14.0 bounded decoder resource use (65,536 values, 512 nesting levels, 2 MiB payload per lookup, InvalidDatabaseException on breach). This is the difference between "we can only read databases we produced" and "we can read a customer- or partner-supplied .mmdb safely." If a "bring your own database" or partner-data-import feature is on the roadmap, that release is your green light.
• Licensing review. Apache-2.0 covers the code. It grants nothing for the data — GeoLite2 and GeoIP2 carry separate terms (attribution, redistribution, storage restrictions). Separate decision, separate approver. Flag it early; it's the most common surprise.

When to Consider This Package

Adopt when:

• You already have, or are buying, .mmdb files — GeoLite2, commercial GeoIP2, or your own custom MMDB built for any IP-keyed dataset (this format is a general-purpose IP-subnet keyed store, not geo-only).
• Lookups happen in-request at volume, or under a latency budget, or on hosts with no outbound network.
• Data residency or PII minimization rules out sending user IPs to a third-party API.
• You want a stable, boring dependency: Apache-2.0, semantic versioning, PHP 7.2+, releases running continuously since 2014 with a current one.

Look elsewhere when:

• You want a product, not a parser. This returns arrays. No country/city/ASN models, no Laravel config, no caching, no facades. geoip2/geoip2 wraps this and gives you typed records; a Laravel wrapper adds the service provider. Most teams should consume that, and take this transitively.
• You want zero data operations. A managed web service removes the update daemon, the file mounting, and the staleness risk — at per-lookup cost and a network hop.
• Your need is coarse. If a CDN already hands you CF-IPCountry or CloudFront-Viewer-Country, you may not need a database at all.
• You need accuracy this format can't give. Residential proxy detection, mobile carrier identity, or firmographic IP→company enrichment is a commercial-vendor problem.
• You're on legacy PHP below 7.2, or can't guarantee gmp/bcmath where 128-bit values might appear (no MaxMind-published database currently uses them).

One caveat on the data: the "0 dependents" figure reflects incomplete registry metadata, not reality — this is a foundational package with substantial transitive reach. Don't let that number drive the decision.

How to Pitch It (Stakeholders)

To executives: A small, permissively licensed library that lets us answer "where is this user?" from our own servers with no per-lookup fees and no user IPs leaving our infrastructure. It is infrastructure, not a feature — the feature value comes from the data subscription and the refresh pipeline we build around it. Low lock-in, low cost, low risk; the two things to fund are the data license and the update job, not the code.

To engineering: composer require maxmind-db/reader, three lines to a working lookup, returns plain arrays, PSR-1/2, semver, actively released. It's a pure-PHP reader with an optional drop-in C extension for hot paths — same class, no code change, so we can defer that tuning. Realistically it's already in the dependency tree via geoip2/geoip2; the decision is whether we call it directly or wrap it. Wrap it: one small service class, config-driven path, a cache in front, getWithPrefixLen() where we care about subnet granularity, and error handling for missing/corrupt files. Keep the Reader out of controllers, and pin the version — recent releases have carried meaningful decoder hardening.