MaxMind DB Reader for PHP: reading GeoIP databases from your code

What a MaxMind DB file is and why you would read it locally

The README describes the format in a sentence: MaxMind DB is a binary file format that stores data indexed by IP address subnets, either IPv4 or IPv6. This library is the PHP API for reading those files, and the project is the PHP reader for that format. The use case is straightforward. An application that needs to know something about an IP address, its country, its city, its network or its connection type, can either call a hosted geolocation service on every request or keep a database file locally and look the address up. The local route has obvious advantages: no per-request latency to a third party, no per-request cost, and no data about your users leaving your server. The cost is that you have to obtain and update the database file yourself, and this library will not do that for you. It is a reader, and nothing more.

Two implementations, one API surface

The library is available in two forms and they are interchangeable. The pure PHP implementation needs no compilation, which the README presents as the option if you prefer not to compile a C extension or need maximum portability. The C extension is the performance option, and the README calls it a drop-in replacement for MaxMind\Db\Reader: you install the Reader API as described, install the extension, and if you use an autoloader no changes to your code are necessary. Under the hood the extension links against libmaxminddb, the C library from the same organisation, and the extension repository is linked for prerequisites. The pure PHP side depends on nothing outside PHP itself, apart from one optional extension for a specific data type discussed later. For most applications the decision is a deployment question rather than an API question, and the two are the same code to the caller.

Installing the pure PHP version with Composer

The Composer path is the standard one. If you do not already have Composer, the README tells you to download it by running the installer in the root directory of your project.

curl -sS https://getcomposer.org/installer | php

That leaves a composer.phar file in your project directory, and the next step is to require the package.

php composer.phar require maxmind-db/reader:^1.14.0

After that you have composer.json, composer.lock and a vendor directory, and the README notes that composer.json should be committed if you use a version control system. Your own code then loads the Composer autoloader.

require 'vendor/autoload.php';

If you would rather not use Composer at all, the project ships a custom autoload.php in its root, which you include by path instead.

Reading a record, and getting the prefix length with it

The usage example in the README is the whole API in twenty lines. You construct a Reader with the path to the database file, then call get for the record and getWithPrefixLen for the record together with the prefix length that matched it, and close the reader when you are done.

<?php
require_once 'vendor/autoload.php';

use MaxMind\Db\Reader;

$ipAddress = '24.24.24.24';
$databaseFile = 'GeoIP2-City.mmdb';

$reader = new Reader($databaseFile);

// get returns just the record for the IP address
print_r($reader->get($ipAddress));

// getWithPrefixLen returns an array containing the record and the
// associated prefix length for that record.
print_r($reader->getWithPrefixLen($ipAddress));

$reader->close();

The distinction between get and getWithPrefixLen matters more than it looks. A MaxMind DB is indexed by network, so a single lookup answers with the record of the network the address falls into, and that network has a size. Code that logs or analyses traffic often needs the prefix length as much as the record, because the prefix length is what tells you how specific the answer was. The repository also carries examples/benchmark.php and an examples/README.example.php, so there is a benchmark to point at if you are comparing the two implementations.

Building the C extension three ways

The extension has three documented install routes and the choice is about what your build environment allows. PIE is the recommended one and is a single command.

pie install maxmind-db/reader-ext

PECL is described as the legacy route. You install libmaxminddb first, then the extension from PECL.

pecl install maxminddb

Building from source is the third option, and it runs from the top level directory of the distribution.

cd ext
phpize
./configure --with-maxminddb
make
make test
sudo make install

There is a fourth variant worth knowing about. Passing --with-maxminddb-bundled compiles a bundled copy of libmaxminddb into the extension so the result depends on nothing but the C runtime, and the README says this is what the precompiled builds use. The bundled sources are a git submodule, so they have to be checked out first with git submodule update --init before the configure step, and the same flag works on Windows passed to configure.bat. Once installed, the extension is loaded by adding extension=maxminddb.so to your php.ini. The README also warns that you may need the PHP development package for your system, such as php5-dev on Debian based systems or php-devel on RedHat and Fedora based ones.

RPM packages, and the note about who maintains them

For Fedora there is a package in the official repository, installed with dnf. For CentOS or RHEL 7 the README asks you to enable the EPEL repository first, and then use yum with the same package name. The important detail comes after the commands: these packages are not maintained by MaxMind. That distinction matters for a production deployment, because the person who ships security fixes for the package is not the same organisation that ships the library. The repository also carries package.xml for PEAR style packaging, a mise.toml and mise.lock for tool version management, phpstan.neon for static analysis, phpunit.xml.dist for the test configuration and a .php-cs-fixer.php plus .phpcs-ruleset.xml for style enforcement, which matches the contributing guidance that code should follow the PSR-1 and PSR-2 style guidelines and include unit tests whenever possible.

The 128-bit integer difference that will surprise you

There is one behavioural difference between the two implementations, and the README devotes a section to it. The MaxMind DB format includes a 128-bit unsigned integer type. No database that MaxMind distributes currently uses it, but both the pure PHP reader and the C extension support it. The pure PHP reader requires gmp or bcmath to read databases that contain such integers. The catch is the return format: the C extension returns the integer as a hexadecimal string prefixed with 0x, while the pure PHP reader returns a decimal string with no prefix. The README goes further and says that a change to make the reader implementations always return either a hexadecimal or decimal representation will not be considered a breaking change, which tells you the format is not a stable contract. If your code path might ever touch a 128-bit value, normalise the representation yourself rather than relying on either.

Licensing, versioning and what the library does not do

The copyright and licence section is short and clear: the software is Copyright 2014 to 2026 by MaxMind, Inc., and it is free software licensed under the Apache License, Version 2.0. That is a permissive licence with an explicit patent grant, which matters if you are embedding it in a commercial product. The library uses Semantic Versioning, and the recent tags follow it: 1.14.0 from 2026-09-10, 1.13.1 from 2025-11-21 and 1.13.0 from 2025-11-20. The repository is not archived and the last push was on 2026-10-19. The requirement is PHP 7.2 or greater, with GMP or BCMath possibly required for some databases when using the pure PHP API. What this library deliberately does not do is fetch or update the database file, resolve the IP address for you, or tell you what the fields mean. Those live in the GeoIP2 or GeoLite2 database products and their documentation, and the README's support section draws that line explicitly, pointing to the MaxMind support page for issues with a MaxMind service that are not specific to the client API. The alternative approach, and the one to weigh, is calling the hosted GeoIP web service over HTTP instead of maintaining a local file. That trades file updates and server storage for per-request latency, a per-request price and a network dependency, and it also sends the address you are looking up to a third party.

Editorial conclusion

Adopt the MaxMind DB Reader for PHP when your application needs to look up IP address data from a local MaxMind DB file and you want to keep that lookup off the network, since the reader works entirely against a file on disk. Do not adopt it if you need live geolocation or ISP data that a local file cannot provide, and expect to install a system library if you choose the extension route. Before you commit, read the 128-bit integer section, because the C extension and the pure PHP reader return that type in different formats, and confirm whether your platform lets you install libmaxminddb or whether the bundled build is the practical option.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. maxmind/MaxMind-DB-Reader-php on GitHub
4. README
5. Releases