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