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

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

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

ext 1 year ago src 1 year ago LICENSE 2 years ago README.md 1 year ago autoload.php 2 years ago package.xml 1 year ago

README.md

186 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 (Composer) ##
9
10	We recommend installing this package with [](https://getcomposer.org/Composer](https://getcomposer.org/](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 [](https://apps.fedoraproject.org/packages/php-maxminddbofficial Fedora repository](https://apps.fedoraproject.org/packages/php-maxminddb](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 [](https://fedoraproject.org/wiki/EPELenable the EPEL repository](https://fedoraproject.org/wiki/EPEL](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 [](https://github.com/maxmind/libmaxminddblibmaxminddb](https://github.com/maxmind/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 [](https://pecl.php.net/package/maxminddbpecl](https://pecl.php.net/package/maxminddb](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 recommended 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 [](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).
161
162	If you are having an issue with a MaxMind service that is not specific to the
163	client API, please see [](https://www.maxmind.com/en/supportour support page](https://www.maxmind.com/en/support](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 [](https://semver.org/Semantic Versioning](https://semver.org/](https://semver.org/).
180
181	## Copyright and License ##
182
183	This software is Copyright (c) 2014-2024 by MaxMind, Inc.
184
185	This is free software, licensed under the Apache License, Version 2.0.
186