Reader Laravel Package

Getting Started

Start by installing the package via Composer: composer require maxmind-db/reader:^1.13. Then include the autoloader with require 'vendor/autoload.php';. Your first use case is likely IP geolocation—download a MaxMind DB file (e.g., GeoLite2-City.mmdb from MaxMind’s free GeoLite2), and write a quick lookup:

use MaxMind\Db\Reader;

$reader = new Reader('/path/to/GeoIP2-City.mmdb');
$record = $reader->get('8.8.8.8');
print_r($record); // Returns city/country data
$reader->close();

If performance is critical, install the C extension via PIE: pie install maxmind-db/reader-ext—this is a drop-in performance boost with zero code changes.

Implementation Patterns

• Caching/Singleton Pattern: Instantiate the Reader once per request (e.g., via DI container or static lazy loader), since opening large .mmdb files repeatedly is expensive.
• Graceful Fallbacks: Wrap lookups in try/catch for MaxMind\Db\Reader\InvalidDatabaseException and handle missing or malformed DB files gracefully (e.g., fallback to a default locale).
• Batch Lookups: For high-volume systems, cache decoded metadata or use async workers to pre-load popular IPs. Use getWithPrefixLen() when you need to know the exact subnet match (e.g., for fraud scoring logic).
• Integration with Laravel: Create a GeoIpService bound as a singleton, inject it into controllers, and register a ServiceProvider that lazily initializes the reader on first access.
• Testing: Mock the Reader class (it has clear interfaces) and test against a fixture .mmdb file (e.g., GeoLite2-City.mmdb from your test fixtures directory).

Gotchas and Tips

• 32-bit PHP + BCMath/GMP: Large integers (e.g., uint64 field values) may be returned as strings on 32-bit platforms unless gmp or bcmath is installed. On 32-bit systems without these extensions, 1.10.0+ now returns integers up to PHP_INT_MAX—verify behavior with your DB schema.
• open_basedir Restriction: The C extension enforces open_basedir, but the pure PHP reader does not. This can cause inconsistent behavior in shared hosting environments—always test deployment parity.
• 128-bit Integer Format Inconsistency: The pure PHP reader returns 128-bit integers as decimal strings, while the C extension returns them as hex (0x...). Avoid mixing DBs or versions in multi-server setups.
• File Handles & Destructors: Always call $reader->close() (or rely on __destruct() in CLI scripts), but be explicit in FPM to prevent resource leaks in long-lived processes (e.g., Swoole, ReactPHP).
• MMDB Metadata Checks: Call $reader->metadata() to validate DB format and checksums during startup, especially in CI or deployment pipelines.
• Memory Usage: The pure PHP reader loads metadata into memory once, but the actual data is mmap’d or streamed. For huge DBs (>1GB), prefer the C extension for lower memory footprint and predictable latency.