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).
For significantly faster IP lookups, we recommend installing the C extension via PIE:
pie install maxmind-db/reader-extThe C extension requires the libmaxminddb C library. See the installation instructions for your platform.
If you prefer not to compile a C extension or need maximum portability, you can install the pure PHP implementation with Composer.
To download Composer, run in the root directory of your project:
curl -sS https://getcomposer.org/installer | phpYou should now have the file composer.phar in your project directory.
Run in your project root:
php composer.phar require maxmind-db/reader:^1.13.1
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.
After installing the dependencies, you need to require the Composer autoloader from your code:
require 'vendor/autoload.php';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,
require('/path/to/MaxMind-DB-Reader-php/autoload.php');and then instantiate the reader class normally:
use MaxMind\Db\Reader;
$reader = new Reader('example.mmdb');RPMs are available in the official Fedora repository.
To install on Fedora, run:
dnf install php-maxminddbTo install on CentOS or RHEL 7, first enable the EPEL repository and then run:
yum install php-maxminddbPlease note that these packages are not maintained by MaxMind.
<?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();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.
We recommend installing the extension via PIE:
pie install maxmind-db/reader-extSee the extension repository for prerequisites including libmaxminddb installation instructions.
First install libmaxminddb as described in its README.md file. After successfully installing libmaxmindb, you may install the extension from PECL:
pecl install maxminddb
Alternatively, you may install it from the source. To do so, run the following commands from the top-level directory of this distribution:
cd ext
phpize
./configure
make
make test
sudo make install
You then must load your extension. The recommended method is to add the
following to your php.ini file:
extension=maxminddb.so
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.
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 7.2 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.
This software is Copyright (c) 2014-2025 by MaxMind, Inc.
This is free software, licensed under the Apache License, Version 2.0.