PHP Reader for the MaxMind DB Database Format

Clone this repo:
  1. 7584843 Remove development stuff from releases (#39) by Michele Locati · 7 years ago master
  2. 297666a Merge pull request #35 from gquemener/patch-1 by Gregory Oschwald · 7 years ago
  3. 3edb951 Fixed syntax error in example by Gildas Quéméner · 7 years ago
  4. a21996f Update email & slack notifications by Dave Rolsky · 7 years ago
  5. b1b04dc Use 1.0.x version of Coveralls for PHP 5.3 support by Gregory Oschwald · 7 years ago

MaxMind DB Reader PHP API


This is the PHP API for reading MaxMind DB files. MaxMind DB is a binary file format that stores data indexed by IP address subnets (IPv4 or IPv6).


We recommend installing this package with Composer.

Download Composer

To download Composer, run in the root directory of your project:

curl -sS | php

You should now have the file composer.phar in your project directory.

Install Dependencies

Run in your project root:

php composer.phar require maxmind-db/reader:~1.0

You should now have the files composer.json and composer.lock as well as the directory vendor in your project directory. If you use a version control system, composer.json should be added to it.

Require Autoloader

After installing the dependencies, you need to require the Composer autoloader from your code:

require 'vendor/autoload.php';



require_once 'vendor/autoload.php';

use MaxMind\Db\Reader;

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

$reader = new Reader($databaseFile);



Optional PHP C Extension

MaxMind provides an optional C extension that is a drop-in replacement for for MaxMind\Db\Reader. In order to use this extension, you must install the Reader API as described above and install the extension as described below. If you are using an autoloader, no changes to your code should be necessary.

Installing Extension

First install libmaxminddb as described in its file. After successfully installing libmaxmindb, run the following commands from the top-level directory of this distribution:

cd ext
make test
sudo make install

You then must load your extension. The recommend method is to add the following to your php.ini file:

Note: You may need to install the PHP development package on your OS such as php5-dev for Debian-based systems or php-devel for RedHat/Fedora-based ones.

128-bit Integer Support

The MaxMind DB format includes 128-bit unsigned integer as a type. Although no MaxMind-distributed database currently makes use of this type, both the pure PHP reader and the C extension support this type. The pure PHP reader requires gmp or bcmath to read databases with 128-bit unsigned integers.

The integer is currently returned as a hexadecimal string (prefixed with "0x") by the C extension and a decimal string (no prefix) by the pure PHP reader. Any change to make the reader implementations always return either a hexadecimal or decimal representation of the integer will NOT be considered a breaking change.


Please report all issues with this code using the [GitHub issue tracker] (

If you are having an issue with a MaxMind service that is not specific to the client API, please see our support page.


This library requires PHP 5.3 or greater. Older versions of PHP are not supported. The pure PHP reader included with this library is works and is tested with HHVM.

The GMP or BCMath extension may be required to read some databases using the pure PHP API.


Patches and pull requests are encouraged. All code should follow the PSR-1 and PSR-2 style guidelines. Please include unit tests whenever possible.


The MaxMind DB Reader PHP API uses Semantic Versioning.

Copyright and License

This software is Copyright (c) 2014 by MaxMind, Inc.

This is free software, licensed under the Apache License, Version 2.0.