1# MaxMind DB Reader PHP API #
3## Description ##
5This is the PHP API for reading MaxMind DB files. MaxMind DB is a binary file
6format that stores data indexed by IP address subnets (IPv4 or IPv6).
8## Installation (Composer) ##
10We recommend installing this package with [Composer](https://getcomposer.org/).
12### Download Composer ###
14To download Composer, run in the root directory of your project:
17curl -sS https://getcomposer.org/installer | php
20You should now have the file `composer.phar` in your project directory.
22### Install Dependencies ###
24Run in your project root:
27php composer.phar require maxmind-db/reader:~1.0
30You should now have the files `composer.json` and `composer.lock` as well as
31the directory `vendor` in your project directory. If you use a version control
32system, `composer.json` should be added to it.
34### Require Autoloader ###
36After installing the dependencies, you need to require the Composer autoloader
37from your code:
43## Installation (Standalone) ##
45If 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
47library, simply include that file,
53and then instantiate the reader class normally:
57$reader = new Reader('example.mmdb');
60## Installation (RPM)
62RPMs are available in the [official Fedora repository](https://apps.fedoraproject.org/packages/php-maxminddb).
64To install on Fedora, run:
67dnf install php-maxminddb
70To install on CentOS or RHEL 7, first [enable the EPEL repository](https://fedoraproject.org/wiki/EPEL)
71and then run:
74yum install php-maxminddb
77Please note that these packages are *not* maintained by MaxMind.
79## Usage ##
81## Example ##
89$ipAddress = '22.214.171.124';
90$databaseFile = 'GeoIP2-City.mmdb';
92$reader = new Reader($databaseFile);
94// get returns just the record for the IP address
97// getWithPrefixLen returns an array containing the record and the
98// associated prefix length for that record.
104## Optional PHP C Extension ##
106MaxMind 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
108Reader API as described above and install the extension as described below. If
109you are using an autoloader, no changes to your code should be necessary.
111### Installing Extension ###
113First install [libmaxminddb](https://github.com/maxmind/libmaxminddb) as
114described in its [README.md
116After successfully installing libmaxmindb, run the following commands from the
117top-level directory of this distribution:
125sudo make install
128You then must load your extension. The recommend method is to add the
129following to your `php.ini` file:
135Note: You may need to install the PHP development package on your OS such as
136php5-dev for Debian-based systems or php-devel for RedHat/Fedora-based ones.
138## 128-bit Integer Support ##
140The MaxMind DB format includes 128-bit unsigned integer as a type. Although
141no MaxMind-distributed database currently makes use of this type, both the
142pure PHP reader and the C extension support this type. The pure PHP reader
143requires gmp or bcmath to read databases with 128-bit unsigned integers.
145The integer is currently returned as a hexadecimal string (prefixed with "0x")
146by the C extension and a decimal string (no prefix) by the pure PHP reader.
147Any change to make the reader implementations always return either a
148hexadecimal or decimal representation of the integer will NOT be considered a
151## Support ##
153Please report all issues with this code using the [GitHub issue tracker](https://github.com/maxmind/MaxMind-DB-Reader-php/issues).
155If you are having an issue with a MaxMind service that is not specific to the
156client API, please see [our support page](https://www.maxmind.com/en/support).
158## Requirements ##
160This library requires PHP 5.6 or greater.
162The GMP or BCMath extension may be required to read some databases
163using the pure PHP API.
165## Contributing ##
167Patches and pull requests are encouraged. All code should follow the PSR-1 and
168PSR-2 style guidelines. Please include unit tests whenever possible.
170## Versioning ##
172The MaxMind DB Reader PHP API uses [Semantic Versioning](https://semver.org/).
174## Copyright and License ##
176This software is Copyright (c) 2014-2019 by MaxMind, Inc.
178This is free software, licensed under the Apache License, Version 2.0.