[Summary view] [Print] [Text view]

   1  # MaxMind DB Reader PHP API #
   2  
   3  ## Description ##
   4  
   5  This is the PHP API for reading MaxMind DB files. MaxMind DB is a binary file
   6  format that stores data indexed by IP address subnets (IPv4 or IPv6).
   7  
   8  ## Installation ##
   9  
  10  ### C Extension (Recommended for Performance) ###
  11  
  12  For significantly faster IP lookups, we recommend installing the C extension via
  13  [PIE](https://github.com/php/pie):
  14  
  15  ```bash
  16  pie install maxmind-db/reader-ext
  17  ```
  18  
  19  The C extension requires the [libmaxminddb](https://github.com/maxmind/libmaxminddb)
  20  C library. See the [installation instructions](https://github.com/maxmind/MaxMind-DB-Reader-php-ext#prerequisites)
  21  for your platform.
  22  
  23  ### Pure PHP (No Compilation Required) ###
  24  
  25  If you prefer not to compile a C extension or need maximum portability, you can
  26  install the pure PHP implementation with [Composer](https://getcomposer.org/).
  27  
  28  ### Download Composer ###
  29  
  30  To download Composer, run in the root directory of your project:
  31  
  32  ```bash
  33  curl -sS https://getcomposer.org/installer | php
  34  ```
  35  
  36  You should now have the file `composer.phar` in your project directory.
  37  
  38  ### Install Dependencies ###
  39  
  40  Run in your project root:
  41  
  42  ```
  43  php composer.phar require maxmind-db/reader:^1.13.1
  44  ```
  45  
  46  You should now have the files `composer.json` and `composer.lock` as well as
  47  the directory `vendor` in your project directory. If you use a version control
  48  system, `composer.json` should be added to it.
  49  
  50  ### Require Autoloader ###
  51  
  52  After installing the dependencies, you need to require the Composer autoloader
  53  from your code:
  54  
  55  ```php
  56  require 'vendor/autoload.php';
  57  ```
  58  
  59  ## Installation (Standalone) ##
  60  
  61  If you don't want to use Composer for some reason, a custom
  62  `autoload.php` is provided for you in the project root. To use the
  63  library, simply include that file,
  64  
  65  ```php
  66  require('/path/to/MaxMind-DB-Reader-php/autoload.php');
  67  ```
  68  
  69  and then instantiate the reader class normally:
  70  
  71  ```php
  72  use MaxMind\Db\Reader;
  73  $reader = new Reader('example.mmdb');
  74  ```
  75  
  76  ## Installation (RPM)
  77  
  78  RPMs are available in the [official Fedora repository](https://apps.fedoraproject.org/packages/php-maxminddb).
  79  
  80  To install on Fedora, run:
  81  
  82  ```bash
  83  dnf install php-maxminddb
  84  ```
  85  
  86  To install on CentOS or RHEL 7, first [enable the EPEL repository](https://fedoraproject.org/wiki/EPEL)
  87  and then run:
  88  
  89  ```bash
  90  yum install php-maxminddb
  91  ```
  92  
  93  Please note that these packages are *not* maintained by MaxMind.
  94  
  95  ## Usage ##
  96  
  97  ## Example ##
  98  
  99  ```php
 100  <?php
 101  require_once 'vendor/autoload.php';
 102  
 103  use MaxMind\Db\Reader;
 104  
 105  $ipAddress = '24.24.24.24';
 106  $databaseFile = 'GeoIP2-City.mmdb';
 107  
 108  $reader = new Reader($databaseFile);
 109  
 110  // get returns just the record for the IP address
 111  print_r($reader->get($ipAddress));
 112  
 113  // getWithPrefixLen returns an array containing the record and the
 114  // associated prefix length for that record.
 115  print_r($reader->getWithPrefixLen($ipAddress));
 116  
 117  $reader->close();
 118  ```
 119  
 120  ## Optional PHP C Extension ##
 121  
 122  MaxMind provides an optional C extension that is a drop-in replacement for
 123  `MaxMind\Db\Reader`. In order to use this extension, you must install the
 124  Reader API as described above and install the extension as described below. If
 125  you are using an autoloader, no changes to your code should be necessary.
 126  
 127  ### Installing Extension via PIE (Recommended) ###
 128  
 129  We recommend installing the extension via [PIE](https://github.com/php/pie):
 130  
 131  ```bash
 132  pie install maxmind-db/reader-ext
 133  ```
 134  
 135  See the [extension repository](https://github.com/maxmind/MaxMind-DB-Reader-php-ext#prerequisites)
 136  for prerequisites including libmaxminddb installation instructions.
 137  
 138  ### Installing Extension via PECL (Legacy) ###
 139  
 140  First install [libmaxminddb](https://github.com/maxmind/libmaxminddb) as
 141  described in its [README.md
 142  file](https://github.com/maxmind/libmaxminddb/blob/main/README.md#installing-from-a-tarball).
 143  After successfully installing libmaxmindb, you may install the extension
 144  from [PECL](https://pecl.php.net/package/maxminddb):
 145  
 146  ```
 147  pecl install maxminddb
 148  ```
 149  
 150  ### Installing Extension from Source ###
 151  
 152  Alternatively, you may install it from the source. To do so, run the following
 153  commands from the top-level directory of this distribution:
 154  
 155  ```
 156  cd ext
 157  phpize
 158  ./configure
 159  make
 160  make test
 161  sudo make install
 162  ```
 163  
 164  You then must load your extension. The recommended method is to add the
 165  following to your `php.ini` file:
 166  
 167  ```
 168  extension=maxminddb.so
 169  ```
 170  
 171  Note: You may need to install the PHP development package on your OS such as
 172  php5-dev for Debian-based systems or php-devel for RedHat/Fedora-based ones.
 173  
 174  ## 128-bit Integer Support ##
 175  
 176  The MaxMind DB format includes 128-bit unsigned integer as a type. Although
 177  no MaxMind-distributed database currently makes use of this type, both the
 178  pure PHP reader and the C extension support this type. The pure PHP reader
 179  requires gmp or bcmath to read databases with 128-bit unsigned integers.
 180  
 181  The integer is currently returned as a hexadecimal string (prefixed with "0x")
 182  by the C extension and a decimal string (no prefix) by the pure PHP reader.
 183  Any change to make the reader implementations always return either a
 184  hexadecimal or decimal representation of the integer will NOT be considered a
 185  breaking change.
 186  
 187  ## Support ##
 188  
 189  Please report all issues with this code using the [GitHub issue tracker](https://github.com/maxmind/MaxMind-DB-Reader-php/issues).
 190  
 191  If you are having an issue with a MaxMind service that is not specific to the
 192  client API, please see [our support page](https://www.maxmind.com/en/support).
 193  
 194  ## Requirements  ##
 195  
 196  This library requires PHP 7.2 or greater.
 197  
 198  The GMP or BCMath extension may be required to read some databases
 199  using the pure PHP API.
 200  
 201  ## Contributing ##
 202  
 203  Patches and pull requests are encouraged. All code should follow the PSR-1 and
 204  PSR-2 style guidelines. Please include unit tests whenever possible.
 205  
 206  ## Versioning ##
 207  
 208  The MaxMind DB Reader PHP API uses [Semantic Versioning](https://semver.org/).
 209  
 210  ## Copyright and License ##
 211  
 212  This software is Copyright (c) 2014-2025 by MaxMind, Inc.
 213  
 214  This is free software, licensed under the Apache License, Version 2.0.