README.md — Matomo Analytics – Powerful, Privacy-First Insights for WordPress 5.8.2

matomo / app / vendor / prefixed / maxmind-db / reader / README.md

matomo / app / vendor / prefixed / maxmind-db / reader Last commit date

ext 4 months ago src 4 months ago LICENSE 2 years ago README.md 4 months ago autoload.php 2 years ago package.xml 4 months ago

README.md

215 lines

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	[](https://github.com/php/piePIE](https://github.com/php/pie](https://github.com/php/pie):
14
15	```bash
16	pie install maxmind-db/reader-ext
17	```
18
19	The C extension requires the [](https://github.com/maxmind/libmaxminddblibmaxminddb](https://github.com/maxmind/libmaxminddb](https://github.com/maxmind/libmaxminddb)
20	C library. See the [](https://github.com/maxmind/MaxMind-DB-Reader-php-ext#prerequisitesinstallation instructions](https://github.com/maxmind/MaxMind-DB-Reader-php-ext#prerequisites](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 [](https://getcomposer.org/Composer](https://getcomposer.org/](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 [](https://apps.fedoraproject.org/packages/php-maxminddbofficial Fedora repository](https://apps.fedoraproject.org/packages/php-maxminddb](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 [](https://fedoraproject.org/wiki/EPELenable the EPEL repository](https://fedoraproject.org/wiki/EPEL](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 [](https://github.com/php/piePIE](https://github.com/php/pie](https://github.com/php/pie):
130
131	```bash
132	pie install maxmind-db/reader-ext
133	```
134
135	See the [](https://github.com/maxmind/MaxMind-DB-Reader-php-ext#prerequisitesextension repository](https://github.com/maxmind/MaxMind-DB-Reader-php-ext#prerequisites](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 [](https://github.com/maxmind/libmaxminddblibmaxminddb](https://github.com/maxmind/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 [](https://pecl.php.net/package/maxminddbPECL](https://pecl.php.net/package/maxminddb](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 [](https://github.com/maxmind/MaxMind-DB-Reader-php/issuesGitHub issue tracker](https://github.com/maxmind/MaxMind-DB-Reader-php/issues](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 [](https://www.maxmind.com/en/supportour support page](https://www.maxmind.com/en/support](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 [](https://semver.org/Semantic Versioning](https://semver.org/](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.
215