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

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

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

src 6 years ago LICENSE 6 years ago README.md 6 years ago

README.md

157 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 [](http://getcomposer.org/Composer](http://getcomposer.org/](http://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	## Usage ##
61
62	## Example ##
63
64	```php
65	<?php
66	require_once 'vendor/autoload.php';
67
68	use MaxMind\Db\Reader;
69
70	$ipAddress = '24.24.24.24';
71	$databaseFile = 'GeoIP2-City.mmdb';
72
73	$reader = new Reader($databaseFile);
74
75	print_r($reader->get($ipAddress));
76
77	$reader->close();
78	```
79
80	## Optional PHP C Extension ##
81
82	MaxMind provides an optional C extension that is a drop-in replacement for
83	`MaxMind\Db\Reader`. In order to use this extension, you must install the
84	Reader API as described above and install the extension as described below. If
85	you are using an autoloader, no changes to your code should be necessary.
86
87	### Installing Extension ###
88
89	First install [](https://github.com/maxmind/libmaxminddblibmaxminddb](https://github.com/maxmind/libmaxminddb](https://github.com/maxmind/libmaxminddb) as
90	described in its [README.md
91	file](https://github.com/maxmind/libmaxminddb/blob/master/README.md#installing-from-a-tarball).
92	After successfully installing libmaxmindb, run the following commands from the
93	top-level directory of this distribution:
94
95	```
96	cd ext
97	phpize
98	./configure
99	make
100	make test
101	sudo make install
102	```
103
104	You then must load your extension. The recommend method is to add the
105	following to your `php.ini` file:
106
107	```
108	extension=maxminddb.so
109	```
110
111	Note: You may need to install the PHP development package on your OS such as
112	php5-dev for Debian-based systems or php-devel for RedHat/Fedora-based ones.
113
114	## 128-bit Integer Support ##
115
116	The MaxMind DB format includes 128-bit unsigned integer as a type. Although
117	no MaxMind-distributed database currently makes use of this type, both the
118	pure PHP reader and the C extension support this type. The pure PHP reader
119	requires gmp or bcmath to read databases with 128-bit unsigned integers.
120
121	The integer is currently returned as a hexadecimal string (prefixed with "0x")
122	by the C extension and a decimal string (no prefix) by the pure PHP reader.
123	Any change to make the reader implementations always return either a
124	hexadecimal or decimal representation of the integer will NOT be considered a
125	breaking change.
126
127	## Support ##
128
129	Please report all issues with this code using the [GitHub issue tracker]
130	(https://github.com/maxmind/MaxMind-DB-Reader-php/issues).
131
132	If you are having an issue with a MaxMind service that is not specific to the
133	client API, please see [](http://www.maxmind.com/en/supportour support page](http://www.maxmind.com/en/support](http://www.maxmind.com/en/support).
134
135	## Requirements ##
136
137	This library requires PHP 5.4 or greater. The pure PHP reader included is
138	compatible with HHVM.
139
140	The GMP or BCMath extension may be required to read some databases
141	using the pure PHP API.
142
143	## Contributing ##
144
145	Patches and pull requests are encouraged. All code should follow the PSR-1 and
146	PSR-2 style guidelines. Please include unit tests whenever possible.
147
148	## Versioning ##
149
150	The MaxMind DB Reader PHP API uses [](http://semver.org/Semantic Versioning](http://semver.org/](http://semver.org/).
151
152	## Copyright and License ##
153
154	This software is Copyright (c) 2014-2018 by MaxMind, Inc.
155
156	This is free software, licensed under the Apache License, Version 2.0.
157