defender-security / src / extra / maxmind-db / reader / README.md

README.md in Defender Security – Malware Scanner, Login Security & Firewall 6.2.1, at src/extra/maxmind-db/reader/README.md

187 lines 5.0 KB

Raw Download Zip

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
161	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).
162
163	If you are having an issue with a MaxMind service that is not specific to the
164	client API, please see [](https://www.maxmind.com/en/supportour support page](https://www.maxmind.com/en/support](https://www.maxmind.com/en/support).
165
166	## Requirements ##
167
168	This library requires PHP 7.2 or greater.
169
170	The GMP or BCMath extension may be required to read some databases
171	using the pure PHP API.
172
173	## Contributing ##
174
175	Patches and pull requests are encouraged. All code should follow the PSR-1 and
176	PSR-2 style guidelines. Please include unit tests whenever possible.
177
178	## Versioning ##
179
180	The MaxMind DB Reader PHP API uses [](https://semver.org/Semantic Versioning](https://semver.org/](https://semver.org/).
181
182	## Copyright and License ##
183
184	This software is Copyright (c) 2014-2021 by MaxMind, Inc.
185
186	This is free software, licensed under the Apache License, Version 2.0.
187