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

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

179 lines 4.8 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/master/README.md#installing-from-a-tarball).
116	After successfully installing libmaxmindb, run the following commands from the
117	top-level directory of this distribution:
118
119	```
120	cd ext
121	phpize
122	./configure
123	make
124	make test
125	sudo make install
126	```
127
128	You then must load your extension. The recommend method is to add the
129	following to your `php.ini` file:
130
131	```
132	extension=maxminddb.so
133	```
134
135	Note: You may need to install the PHP development package on your OS such as
136	php5-dev for Debian-based systems or php-devel for RedHat/Fedora-based ones.
137
138	## 128-bit Integer Support ##
139
140	The MaxMind DB format includes 128-bit unsigned integer as a type. Although
141	no MaxMind-distributed database currently makes use of this type, both the
142	pure PHP reader and the C extension support this type. The pure PHP reader
143	requires gmp or bcmath to read databases with 128-bit unsigned integers.
144
145	The integer is currently returned as a hexadecimal string (prefixed with "0x")
146	by the C extension and a decimal string (no prefix) by the pure PHP reader.
147	Any change to make the reader implementations always return either a
148	hexadecimal or decimal representation of the integer will NOT be considered a
149	breaking change.
150
151	## Support ##
152
153	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).
154
155	If you are having an issue with a MaxMind service that is not specific to the
156	client API, please see [](https://www.maxmind.com/en/supportour support page](https://www.maxmind.com/en/support](https://www.maxmind.com/en/support).
157
158	## Requirements ##
159
160	This library requires PHP 5.6 or greater.
161
162	The GMP or BCMath extension may be required to read some databases
163	using the pure PHP API.
164
165	## Contributing ##
166
167	Patches and pull requests are encouraged. All code should follow the PSR-1 and
168	PSR-2 style guidelines. Please include unit tests whenever possible.
169
170	## Versioning ##
171
172	The MaxMind DB Reader PHP API uses [](https://semver.org/Semantic Versioning](https://semver.org/](https://semver.org/).
173
174	## Copyright and License ##
175
176	This software is Copyright (c) 2014-2019 by MaxMind, Inc.
177
178	This is free software, licensed under the Apache License, Version 2.0.
179