1# MaxMind DB Reader PHP API #
2
3## Description ##
4
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).
7
8## Installation (Composer) ##
9
10We recommend installing this package with [Composer](https://getcomposer.org/).
11
12### Download Composer ###
13
14To download Composer, run in the root directory of your project:
15
16```bash
17curl -sS https://getcomposer.org/installer | php
18```
19
20You should now have the file `composer.phar` in your project directory.
21
22### Install Dependencies ###
23
24Run in your project root:
25
26```
27php composer.phar require maxmind-db/reader:~1.0
28```
29
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.
33
34### Require Autoloader ###
35
36After installing the dependencies, you need to require the Composer autoloader
37from your code:
38
39```php
40require 'vendor/autoload.php';
41```
42
43## Installation (Standalone) ##
44
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,
48
49```php
50require('/path/to/MaxMind-DB-Reader-php/autoload.php');
51```
52
53and then instantiate the reader class normally:
54
55```php
56use MaxMind\Db\Reader;
57$reader = new Reader('example.mmdb');
58```
59
60## Installation (RPM)
61
62RPMs are available in the [official Fedora repository](https://apps.fedoraproject.org/packages/php-maxminddb).
63
64To install on Fedora, run:
65
66```bash
67dnf install php-maxminddb
68```
69
70To install on CentOS or RHEL 7, first [enable the EPEL repository](https://fedoraproject.org/wiki/EPEL)
71and then run:
72
73```bash
74yum install php-maxminddb
75```
76
77Please note that these packages are *not* maintained by MaxMind.
78
79## Usage ##
80
81## Example ##
82
83```php
84<?php
85require_once 'vendor/autoload.php';
86
87use 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
95print_r($reader->get($ipAddress));
96
97// getWithPrefixLen returns an array containing the record and the
98// associated prefix length for that record.
99print_r($reader->getWithPrefixLen($ipAddress));
100
101$reader->close();
102```
103
104## Optional PHP C Extension ##
105
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.
110
111### Installing Extension ###
112
113First install [libmaxminddb](https://github.com/maxmind/libmaxminddb) as
114described in its [README.md
115file](https://github.com/maxmind/libmaxminddb/blob/master/README.md#installing-from-a-tarball).
116After successfully installing libmaxmindb, run the following commands from the
117top-level directory of this distribution:
118
119```
120cd ext
121phpize
122./configure
123make
124make test
125sudo make install
126```
127
128You then must load your extension. The recommend method is to add the
129following to your `php.ini` file:
130
131```
132extension=maxminddb.so
133```
134
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.
137
138## 128-bit Integer Support ##
139
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.
144
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
149breaking change.
150
151## Support ##
152
153Please report all issues with this code using the [GitHub issue tracker](https://github.com/maxmind/MaxMind-DB-Reader-php/issues).
154
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).
157
158## Requirements  ##
159
160This library requires PHP 5.6 or greater.
161
162The GMP or BCMath extension may be required to read some databases
163using the pure PHP API.
164
165## Contributing ##
166
167Patches and pull requests are encouraged. All code should follow the PSR-1 and
168PSR-2 style guidelines. Please include unit tests whenever possible.
169
170## Versioning ##
171
172The MaxMind DB Reader PHP API uses [Semantic Versioning](https://semver.org/).
173
174## Copyright and License ##
175
176This software is Copyright (c) 2014-2019 by MaxMind, Inc.
177
178This is free software, licensed under the Apache License, Version 2.0.
179