Documentation updates
This commit is contained in:
parent
044ca4d085
commit
b55d42b5cd
91
README.md
91
README.md
|
@ -13,27 +13,22 @@ To provide feedback or get support during the beta, please see the
|
||||||
|
|
||||||
## Description ##
|
## Description ##
|
||||||
|
|
||||||
Currently, this distribution provides an API for the [GeoIP2 web services]
|
This distribution provides an API for the [GeoIP2 web services]
|
||||||
(http://dev.maxmind.com/geoip/geoip2/web-services).
|
(http://dev.maxmind.com/geoip/geoip2/web-services) and the [GeoLite2
|
||||||
|
databases](http://dev.maxmind.com/geoip/geoip2/geolite2/). The commercial
|
||||||
In the future, this distribution will also provide the same API for the
|
GeoIP2 databases have not yet been released as a downloadable product.
|
||||||
GeoIP2 downloadable databases. These databases have not yet been
|
|
||||||
released as a downloadable product.
|
|
||||||
|
|
||||||
See ``GeoIp2\WebService\Client`` for details on the web service client
|
|
||||||
API.
|
|
||||||
|
|
||||||
## Installation ##
|
## Installation ##
|
||||||
|
|
||||||
### Define Your Dependencies ###
|
### Define Your Dependencies ###
|
||||||
|
|
||||||
We recommend installing this package with [Composer](http://getcomposer.org/).
|
We recommend installing this package with [Composer](http://getcomposer.org/).
|
||||||
To do this, add ```geoip2/geoip2``` to your ```composer.json``` file.
|
To do this, add `geoip2/geoip2` to your `composer.json` file.
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"require": {
|
"require": {
|
||||||
"geoip2/geoip2": "0.3.*"
|
"geoip2/geoip2": "0.4.*"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
@ -60,11 +55,43 @@ You can autoload all dependencies by adding this to your code:
|
||||||
```
|
```
|
||||||
require 'vendor/autoload.php';
|
require 'vendor/autoload.php';
|
||||||
```
|
```
|
||||||
|
## Database Reader ##
|
||||||
|
|
||||||
## Usage ##
|
### Usage ###
|
||||||
|
|
||||||
To use this API, you must create a new ``\GeoIp2\WebService\Client``
|
To use this API, you must create a new `\GeoIp2\Database\Reader` object with
|
||||||
object with your ``$userId`` and ``$licenseKey``, then you call the method
|
the path to the database file as the first argument to the constructor. You
|
||||||
|
may then call the method corresponding to the database you are using.
|
||||||
|
|
||||||
|
If the lookup succeeds, the method call will return a model class for the
|
||||||
|
record in the database. This model in turn contains multiple container
|
||||||
|
classes for the different parts of the data such as the city in which the
|
||||||
|
IP address is located.
|
||||||
|
|
||||||
|
If the record is not found, a `\GeoIp2\Exception\AddressNotFoundException`
|
||||||
|
is returned. If the database is invalid or corrupt, a
|
||||||
|
`\MaxMind\Db\InvalidDatabaseException` will be thrown.
|
||||||
|
|
||||||
|
See the API documentation for more details.
|
||||||
|
|
||||||
|
### Example ###
|
||||||
|
|
||||||
|
```php
|
||||||
|
<?php
|
||||||
|
require_once 'vendor/autoload.php';
|
||||||
|
use \GeoIp2\Database\Reader;
|
||||||
|
|
||||||
|
$reader = new Reader('/usr/local/share/GeoIP2/GeoIP2-City.mmdb');
|
||||||
|
$record = $reader->city('24.24.24.24');
|
||||||
|
print($record->country->isoCode);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Web Service Client ##
|
||||||
|
|
||||||
|
### Usage ###
|
||||||
|
|
||||||
|
To use this API, you must create a new `\GeoIp2\WebService\Client`
|
||||||
|
object with your `$userId` and `$licenseKey`, then you call the method
|
||||||
corresponding to a specific end point, passing it the IP address you want to
|
corresponding to a specific end point, passing it the IP address you want to
|
||||||
look up.
|
look up.
|
||||||
|
|
||||||
|
@ -72,9 +99,11 @@ If the request succeeds, the method call will return a model class for the end
|
||||||
point you called. This model in turn contains multiple record classes, each of
|
point you called. This model in turn contains multiple record classes, each of
|
||||||
which represents part of the data returned by the web service.
|
which represents part of the data returned by the web service.
|
||||||
|
|
||||||
|
If there is an error, a structured exception is thrown.
|
||||||
|
|
||||||
See the API documentation for more details.
|
See the API documentation for more details.
|
||||||
|
|
||||||
## Example ##
|
### Example ###
|
||||||
|
|
||||||
```php
|
```php
|
||||||
<?php
|
<?php
|
||||||
|
@ -83,30 +112,10 @@ use \GeoIp2\WebService\Client;
|
||||||
|
|
||||||
$client = new Client(42, 'abcdef123456');
|
$client = new Client(42, 'abcdef123456');
|
||||||
$omni = $client->omni('24.24.24.24');
|
$omni = $client->omni('24.24.24.24');
|
||||||
echo $omni->country->isoCode;
|
print($omni->country->isoCode);
|
||||||
```
|
```
|
||||||
|
|
||||||
## Exceptions ##
|
### What data is returned? ###
|
||||||
|
|
||||||
For details on the possible errors returned by the web service itself, see
|
|
||||||
the
|
|
||||||
[GeoIP2 web service docs](http://dev.maxmind.com/geoip2/geoip/web-service).
|
|
||||||
|
|
||||||
If the web service returns an explicit error document, this is thrown as a
|
|
||||||
```\GeoIp2\Exception\WebServiceException```. If some other sort of transport
|
|
||||||
error occurs, this is thrown as a ```\GeoIp2\Exception\HttpException```.
|
|
||||||
The difference is that the web service error includes an error message and
|
|
||||||
error code delivered by the web service. The latter is thrown when some sort
|
|
||||||
of unanticipated error occurs, such as the web service returning a 500 or an
|
|
||||||
invalid error document.
|
|
||||||
|
|
||||||
If the web service returns any status code besides 200, 4xx, or 5xx, this also
|
|
||||||
becomes a ```\GeoIp2\Exception\HttpException```.
|
|
||||||
|
|
||||||
Finally, if the web service returns a 200 but the body is invalid, the client
|
|
||||||
throws a ```\GeoIp2\Exception\GeoIp2Exception```.
|
|
||||||
|
|
||||||
## What data is returned? ##
|
|
||||||
|
|
||||||
While many of the end points return the same basic records, the attributes
|
While many of the end points return the same basic records, the attributes
|
||||||
which can be populated vary between end points. In addition, while an end
|
which can be populated vary between end points. In addition, while an end
|
||||||
|
@ -120,8 +129,8 @@ See the
|
||||||
[GeoIP2 web service docs](http://dev.maxmind.com/geoip/geoip2/web-services)
|
[GeoIP2 web service docs](http://dev.maxmind.com/geoip/geoip2/web-services)
|
||||||
for details on what data each end point may return.
|
for details on what data each end point may return.
|
||||||
|
|
||||||
The only piece of data which is always returned is the ```ipAddress```
|
The only piece of data which is always returned is the `ipAddress`
|
||||||
attribute in the ``GeoIp2\Record\Traits`` record.
|
attribute in the `GeoIp2\Record\Traits` record.
|
||||||
|
|
||||||
Every record class attribute has a corresponding predicate method so you can
|
Every record class attribute has a corresponding predicate method so you can
|
||||||
check to see if the attribute is set.
|
check to see if the attribute is set.
|
||||||
|
@ -131,10 +140,10 @@ check to see if the attribute is set.
|
||||||
[GeoNames](http://www.geonames.org/) offers web services and downloadable
|
[GeoNames](http://www.geonames.org/) offers web services and downloadable
|
||||||
databases with data on geographical features around the world, including
|
databases with data on geographical features around the world, including
|
||||||
populated places. They offer both free and paid premium data. Each
|
populated places. They offer both free and paid premium data. Each
|
||||||
feature is unique identified by a ```geonameId```, which is an integer.
|
feature is unique identified by a `geonameId`, which is an integer.
|
||||||
|
|
||||||
Many of the records returned by the GeoIP2 web services and databases
|
Many of the records returned by the GeoIP2 web services and databases
|
||||||
include a ```geonameId``` property. This is the ID of a geographical feature
|
include a `geonameId` property. This is the ID of a geographical feature
|
||||||
(city, region, country, etc.) in the GeoNames database.
|
(city, region, country, etc.) in the GeoNames database.
|
||||||
|
|
||||||
Some of the data that MaxMind provides is also sourced from GeoNames. We
|
Some of the data that MaxMind provides is also sourced from GeoNames. We
|
||||||
|
|
|
@ -47,26 +47,6 @@ use Guzzle\Http\Exception\ServerErrorResponseException;
|
||||||
* service.
|
* service.
|
||||||
*
|
*
|
||||||
* If the request fails, the client class throws an exception.
|
* If the request fails, the client class throws an exception.
|
||||||
*
|
|
||||||
* **Exceptions**
|
|
||||||
*
|
|
||||||
* For details on the possible errors returned by the web service itself, see
|
|
||||||
* {@link http://dev.maxmind.com/geoip2/geoip/web-services the GeoIP2 web
|
|
||||||
* service docs}.
|
|
||||||
*
|
|
||||||
* If the web service returns an explicit error document, this is thrown as a
|
|
||||||
* {@link \GeoIp2\Exception\WebServiceException}. If some other sort of
|
|
||||||
* transport error occurs, this is thrown as a {@link
|
|
||||||
* \GeoIp2\Exception\HttpException}. The difference is that the web service
|
|
||||||
* error includes an error message and error code delivered by the web
|
|
||||||
* service. The latter is thrown when some sort of unanticipated error occurs,
|
|
||||||
* such as the web service returning a 500 or an invalid error document.
|
|
||||||
*
|
|
||||||
* If the web service returns any status code besides 200, 4xx, or 5xx, this
|
|
||||||
* also becomes a {@link \GeoIp2\Exception\HttpException}.
|
|
||||||
*
|
|
||||||
* Finally, if the web service returns a 200 but the body is invalid, the
|
|
||||||
* client throws a {@link \GeoIp2\Exception\GeoIp2Exception}.
|
|
||||||
*/
|
*/
|
||||||
class Client
|
class Client
|
||||||
{
|
{
|
||||||
|
@ -111,12 +91,23 @@ class Client
|
||||||
*
|
*
|
||||||
* @return \GeoIp2\Model\City
|
* @return \GeoIp2\Model\City
|
||||||
*
|
*
|
||||||
* @throws \GeoIp2\Exception\GeoIp2Exception if there was a generic
|
* @throws \GeoIp2\Exception\AddressNotFoundException if the address you
|
||||||
* error processing your request.
|
* provided is not in our database (e.g., a private address).
|
||||||
* @throws \GeoIp2\Exception\HttpException if there was an HTTP transport
|
* @throws \GeoIp2\Exception\AuthenticationException if there is a problem
|
||||||
* error.
|
* with the user ID or license key that you provided.
|
||||||
* @throws \GeoIp2\Exception\WebServiceException if an error was returned
|
* @throws \GeoIp2\Exception\QutOfQueriesException if your account is out
|
||||||
* by MaxMind's GeoIP2 web service.
|
* of queries.
|
||||||
|
* @throws \GeoIp2\Exception\InvalidRequestException} if your request was
|
||||||
|
* received by the web service but is invalid for some other reason.
|
||||||
|
* This may indicate an issue with this API. Please report the error to
|
||||||
|
* MaxMind.
|
||||||
|
* @throws \GeoIp2\Exception\HttpException if an unexpected HTTP error
|
||||||
|
* code or message was returned. This could indicate a problem with the
|
||||||
|
* connection between your server and the web service or that the web
|
||||||
|
* service returned an invalid document or 500 error code.
|
||||||
|
* @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
|
||||||
|
* class to the above exceptions. It will be thrown directly if a 200
|
||||||
|
* status code is returned but the body is invalid.
|
||||||
*/
|
*/
|
||||||
public function city($ipAddress = 'me')
|
public function city($ipAddress = 'me')
|
||||||
{
|
{
|
||||||
|
@ -132,12 +123,23 @@ class Client
|
||||||
*
|
*
|
||||||
* @return \GeoIp2\Model\Country
|
* @return \GeoIp2\Model\Country
|
||||||
*
|
*
|
||||||
* @throws \GeoIp2\Exception\GeoIp2Exception if there was a generic
|
* @throws \GeoIp2\Exception\AddressNotFoundException if the address you
|
||||||
* error processing your request.
|
* provided is not in our database (e.g., a private address).
|
||||||
* @throws \GeoIp2\Exception\HttpException if there was an HTTP transport
|
* @throws \GeoIp2\Exception\AuthenticationException if there is a problem
|
||||||
* error.
|
* with the user ID or license key that you provided.
|
||||||
* @throws \GeoIp2\Exception\WebServiceException if an error was returned
|
* @throws \GeoIp2\Exception\QutOfQueriesException if your account is out
|
||||||
* by MaxMind's GeoIP2 web service.
|
* of queries.
|
||||||
|
* @throws \GeoIp2\Exception\InvalidRequestException} if your request was
|
||||||
|
* received by the web service but is invalid for some other reason.
|
||||||
|
* This may indicate an issue with this API. Please report the error to
|
||||||
|
* MaxMind.
|
||||||
|
* @throws \GeoIp2\Exception\HttpException if an unexpected HTTP error
|
||||||
|
* code or message was returned. This could indicate a problem with the
|
||||||
|
* connection between your server and the web service or that the web
|
||||||
|
* service returned an invalid document or 500 error code.
|
||||||
|
* @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
|
||||||
|
* class to the above exceptions. It will be thrown directly if a 200
|
||||||
|
* status code is returned but the body is invalid.
|
||||||
*/
|
*/
|
||||||
public function country($ipAddress = 'me')
|
public function country($ipAddress = 'me')
|
||||||
{
|
{
|
||||||
|
@ -153,12 +155,23 @@ class Client
|
||||||
*
|
*
|
||||||
* @return \GeoIp2\Model\CityIspOrg
|
* @return \GeoIp2\Model\CityIspOrg
|
||||||
*
|
*
|
||||||
* @throws \GeoIp2\Exception\GeoIp2Exception if there was a generic
|
* @throws \GeoIp2\Exception\AddressNotFoundException if the address you
|
||||||
* error processing your request.
|
* provided is not in our database (e.g., a private address).
|
||||||
* @throws \GeoIp2\Exception\HttpException if there was an HTTP transport
|
* @throws \GeoIp2\Exception\AuthenticationException if there is a problem
|
||||||
* error.
|
* with the user ID or license key that you provided.
|
||||||
* @throws \GeoIp2\Exception\WebServiceException if an error was returned
|
* @throws \GeoIp2\Exception\QutOfQueriesException if your account is out
|
||||||
* by MaxMind's GeoIP2 web service.
|
* of queries.
|
||||||
|
* @throws \GeoIp2\Exception\InvalidRequestException} if your request was
|
||||||
|
* received by the web service but is invalid for some other reason.
|
||||||
|
* This may indicate an issue with this API. Please report the error to
|
||||||
|
* MaxMind.
|
||||||
|
* @throws \GeoIp2\Exception\HttpException if an unexpected HTTP error
|
||||||
|
* code or message was returned. This could indicate a problem with the
|
||||||
|
* connection between your server and the web service or that the web
|
||||||
|
* service returned an invalid document or 500 error code.
|
||||||
|
* @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
|
||||||
|
* class to the above exceptions. It will be thrown directly if a 200
|
||||||
|
* status code is returned but the body is invalid.
|
||||||
*/
|
*/
|
||||||
public function cityIspOrg($ipAddress = 'me')
|
public function cityIspOrg($ipAddress = 'me')
|
||||||
{
|
{
|
||||||
|
@ -174,12 +187,23 @@ class Client
|
||||||
*
|
*
|
||||||
* @return \GeoIp2\Model\Omni
|
* @return \GeoIp2\Model\Omni
|
||||||
*
|
*
|
||||||
* @throws \GeoIp2\Exception\GeoIp2Exception if there was a generic
|
* @throws \GeoIp2\Exception\AddressNotFoundException if the address you
|
||||||
* error processing your request.
|
* provided is not in our database (e.g., a private address).
|
||||||
* @throws \GeoIp2\Exception\HttpException if there was an HTTP transport
|
* @throws \GeoIp2\Exception\AuthenticationException if there is a problem
|
||||||
* error.
|
* with the user ID or license key that you provided.
|
||||||
* @throws \GeoIp2\Exception\WebServiceException if an error was returned
|
* @throws \GeoIp2\Exception\QutOfQueriesException if your account is out
|
||||||
* by MaxMind's GeoIP2 web service.
|
* of queries.
|
||||||
|
* @throws \GeoIp2\Exception\InvalidRequestException} if your request was
|
||||||
|
* received by the web service but is invalid for some other reason.
|
||||||
|
* This may indicate an issue with this API. Please report the error to
|
||||||
|
* MaxMind.
|
||||||
|
* @throws \GeoIp2\Exception\HttpException if an unexpected HTTP error
|
||||||
|
* code or message was returned. This could indicate a problem with the
|
||||||
|
* connection between your server and the web service or that the web
|
||||||
|
* service returned an invalid document or 500 error code.
|
||||||
|
* @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
|
||||||
|
* class to the above exceptions. It will be thrown directly if a 200
|
||||||
|
* status code is returned but the body is invalid.
|
||||||
*/
|
*/
|
||||||
public function omni($ipAddress = 'me')
|
public function omni($ipAddress = 'me')
|
||||||
{
|
{
|
||||||
|
@ -194,11 +218,8 @@ class Client
|
||||||
$this->guzzleClient : new GuzzleClient();
|
$this->guzzleClient : new GuzzleClient();
|
||||||
$request = $client->get($uri, array('Accept' => 'application/json'));
|
$request = $client->get($uri, array('Accept' => 'application/json'));
|
||||||
$request->setAuth($this->userId, $this->licenseKey);
|
$request->setAuth($this->userId, $this->licenseKey);
|
||||||
$ua = $request->getHeader('User-Agent');
|
$this->setUserAgent($request);
|
||||||
$ua = "GeoIP2 PHP API ($ua)";
|
|
||||||
$request->setHeader('User-Agent', $ua);
|
|
||||||
|
|
||||||
$response = null;
|
|
||||||
try {
|
try {
|
||||||
$response = $request->send();
|
$response = $request->send();
|
||||||
} catch (ClientErrorResponseException $e) {
|
} catch (ClientErrorResponseException $e) {
|
||||||
|
@ -329,6 +350,13 @@ class Client
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
private function setUserAgent($request)
|
||||||
|
{
|
||||||
|
$userAgent = $request->getHeader('User-Agent');
|
||||||
|
$userAgent = "GeoIP2 PHP API ($userAgent)";
|
||||||
|
$request->setHeader('User-Agent', $userAgent);
|
||||||
|
}
|
||||||
|
|
||||||
private function baseUri()
|
private function baseUri()
|
||||||
{
|
{
|
||||||
return 'https://' . $this->host . '/geoip/v2.0';
|
return 'https://' . $this->host . '/geoip/v2.0';
|
||||||
|
|
|
@ -405,6 +405,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
|
||||||
|
|
||||||
$client->country('1.2.3.18');
|
$client->country('1.2.3.18');
|
||||||
}
|
}
|
||||||
|
|
||||||
public function testParams()
|
public function testParams()
|
||||||
{
|
{
|
||||||
$plugin = new MockPlugin();
|
$plugin = new MockPlugin();
|
||||||
|
|
Loading…
Reference in New Issue
Block a user