Skip to content
PHP Reader for the MaxMind DB Database Format
PHP C Shell M4
Branch: master
Clone or download
Latest commit d47c28b Jun 4, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
dev-bin Fix release script Jan 19, 2017
examples Make benchmark results more repeatable Nov 16, 2018
ext PHP 8 compatibility fixes May 28, 2019
src/MaxMind/Db Tidy long lines Mar 13, 2019
tests Fix extension for large uint32 values on 32 bit machines Jan 3, 2019
.coveralls-phpunit.xml.dist Added separate phpunit config for coveralls Oct 21, 2013
.gitattributes Remove development stuff from releases (#39) Apr 18, 2016
.gitignore Add php-cs-fixer config and run from Travis Jul 6, 2017
.gitmodules Improved error checking in extension. Oct 2, 2013
.php_cs Disable php CS rule disallowing phpdoc on defines Mar 13, 2019
.phpcs-ruleset.xml Ignore side-effect rule in phpcs for Decoder Nov 16, 2018 PHP 8 compatibility fixes May 28, 2019 Remove hhvm support from readme/travis config & scripts Feb 19, 2019
.travis.yml PHP 8 compatibility fixes May 28, 2019 Add change log entry Jun 4, 2019
LICENSE Bump copyright year Mar 13, 2019
autoload.php check for existency before loading any classes Oct 22, 2018
composer.json Use https URLs Mar 13, 2019
phpunit.xml.dist Added separate phpunit config for coveralls Oct 21, 2013

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).

Installation (Composer)

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';

Installation (Standalone)

If you don't want to use Composer for some reason, a custom autoload.php is provided for you in the project root. To use the library, simply include that file,


and then instantiate the reader class normally:

use MaxMind\Db\Reader;
$reader = new Reader('example.mmdb');



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 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.4 or greater.

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-2019 by MaxMind, Inc.

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

You can’t perform that action at this time.