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 ##
|
||||
|
||||
Currently, this distribution provides an API for the [GeoIP2 web services]
|
||||
(http://dev.maxmind.com/geoip/geoip2/web-services).
|
||||
|
||||
In the future, this distribution will also provide the same API for the
|
||||
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.
|
||||
This distribution provides an API for the [GeoIP2 web services]
|
||||
(http://dev.maxmind.com/geoip/geoip2/web-services) and the [GeoLite2
|
||||
databases](http://dev.maxmind.com/geoip/geoip2/geolite2/). The commercial
|
||||
GeoIP2 databases have not yet been released as a downloadable product.
|
||||
|
||||
## Installation ##
|
||||
|
||||
### Define Your Dependencies ###
|
||||
|
||||
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
|
||||
{
|
||||
"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';
|
||||
```
|
||||
## Database Reader ##
|
||||
|
||||
## Usage ##
|
||||
### Usage ###
|
||||
|
||||
To use this API, you must create a new ``\GeoIp2\WebService\Client``
|
||||
object with your ``$userId`` and ``$licenseKey``, then you call the method
|
||||
To use this API, you must create a new `\GeoIp2\Database\Reader` object with
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
## Example ##
|
||||
### Example ###
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
@ -83,30 +112,10 @@ use \GeoIp2\WebService\Client;
|
|||
|
||||
$client = new Client(42, 'abcdef123456');
|
||||
$omni = $client->omni('24.24.24.24');
|
||||
echo $omni->country->isoCode;
|
||||
print($omni->country->isoCode);
|
||||
```
|
||||
|
||||
## Exceptions ##
|
||||
|
||||
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? ##
|
||||
### What data is returned? ###
|
||||
|
||||
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
|
||||
|
@ -120,8 +129,8 @@ See the
|
|||
[GeoIP2 web service docs](http://dev.maxmind.com/geoip/geoip2/web-services)
|
||||
for details on what data each end point may return.
|
||||
|
||||
The only piece of data which is always returned is the ```ipAddress```
|
||||
attribute in the ``GeoIp2\Record\Traits`` record.
|
||||
The only piece of data which is always returned is the `ipAddress`
|
||||
attribute in the `GeoIp2\Record\Traits` record.
|
||||
|
||||
Every record class attribute has a corresponding predicate method so you can
|
||||
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
|
||||
databases with data on geographical features around the world, including
|
||||
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
|
||||
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.
|
||||
|
||||
Some of the data that MaxMind provides is also sourced from GeoNames. We
|
||||
|
|
|
@ -47,26 +47,6 @@ use Guzzle\Http\Exception\ServerErrorResponseException;
|
|||
* service.
|
||||
*
|
||||
* 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
|
||||
{
|
||||
|
@ -111,12 +91,23 @@ class Client
|
|||
*
|
||||
* @return \GeoIp2\Model\City
|
||||
*
|
||||
* @throws \GeoIp2\Exception\GeoIp2Exception if there was a generic
|
||||
* error processing your request.
|
||||
* @throws \GeoIp2\Exception\HttpException if there was an HTTP transport
|
||||
* error.
|
||||
* @throws \GeoIp2\Exception\WebServiceException if an error was returned
|
||||
* by MaxMind's GeoIP2 web service.
|
||||
* @throws \GeoIp2\Exception\AddressNotFoundException if the address you
|
||||
* provided is not in our database (e.g., a private address).
|
||||
* @throws \GeoIp2\Exception\AuthenticationException if there is a problem
|
||||
* with the user ID or license key that you provided.
|
||||
* @throws \GeoIp2\Exception\QutOfQueriesException if your account is out
|
||||
* 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')
|
||||
{
|
||||
|
@ -132,12 +123,23 @@ class Client
|
|||
*
|
||||
* @return \GeoIp2\Model\Country
|
||||
*
|
||||
* @throws \GeoIp2\Exception\GeoIp2Exception if there was a generic
|
||||
* error processing your request.
|
||||
* @throws \GeoIp2\Exception\HttpException if there was an HTTP transport
|
||||
* error.
|
||||
* @throws \GeoIp2\Exception\WebServiceException if an error was returned
|
||||
* by MaxMind's GeoIP2 web service.
|
||||
* @throws \GeoIp2\Exception\AddressNotFoundException if the address you
|
||||
* provided is not in our database (e.g., a private address).
|
||||
* @throws \GeoIp2\Exception\AuthenticationException if there is a problem
|
||||
* with the user ID or license key that you provided.
|
||||
* @throws \GeoIp2\Exception\QutOfQueriesException if your account is out
|
||||
* 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')
|
||||
{
|
||||
|
@ -153,12 +155,23 @@ class Client
|
|||
*
|
||||
* @return \GeoIp2\Model\CityIspOrg
|
||||
*
|
||||
* @throws \GeoIp2\Exception\GeoIp2Exception if there was a generic
|
||||
* error processing your request.
|
||||
* @throws \GeoIp2\Exception\HttpException if there was an HTTP transport
|
||||
* error.
|
||||
* @throws \GeoIp2\Exception\WebServiceException if an error was returned
|
||||
* by MaxMind's GeoIP2 web service.
|
||||
* @throws \GeoIp2\Exception\AddressNotFoundException if the address you
|
||||
* provided is not in our database (e.g., a private address).
|
||||
* @throws \GeoIp2\Exception\AuthenticationException if there is a problem
|
||||
* with the user ID or license key that you provided.
|
||||
* @throws \GeoIp2\Exception\QutOfQueriesException if your account is out
|
||||
* 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')
|
||||
{
|
||||
|
@ -174,12 +187,23 @@ class Client
|
|||
*
|
||||
* @return \GeoIp2\Model\Omni
|
||||
*
|
||||
* @throws \GeoIp2\Exception\GeoIp2Exception if there was a generic
|
||||
* error processing your request.
|
||||
* @throws \GeoIp2\Exception\HttpException if there was an HTTP transport
|
||||
* error.
|
||||
* @throws \GeoIp2\Exception\WebServiceException if an error was returned
|
||||
* by MaxMind's GeoIP2 web service.
|
||||
* @throws \GeoIp2\Exception\AddressNotFoundException if the address you
|
||||
* provided is not in our database (e.g., a private address).
|
||||
* @throws \GeoIp2\Exception\AuthenticationException if there is a problem
|
||||
* with the user ID or license key that you provided.
|
||||
* @throws \GeoIp2\Exception\QutOfQueriesException if your account is out
|
||||
* 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')
|
||||
{
|
||||
|
@ -194,11 +218,8 @@ class Client
|
|||
$this->guzzleClient : new GuzzleClient();
|
||||
$request = $client->get($uri, array('Accept' => 'application/json'));
|
||||
$request->setAuth($this->userId, $this->licenseKey);
|
||||
$ua = $request->getHeader('User-Agent');
|
||||
$ua = "GeoIP2 PHP API ($ua)";
|
||||
$request->setHeader('User-Agent', $ua);
|
||||
$this->setUserAgent($request);
|
||||
|
||||
$response = null;
|
||||
try {
|
||||
$response = $request->send();
|
||||
} 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()
|
||||
{
|
||||
return 'https://' . $this->host . '/geoip/v2.0';
|
||||
|
|
|
@ -405,6 +405,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
|
|||
|
||||
$client->country('1.2.3.18');
|
||||
}
|
||||
|
||||
public function testParams()
|
||||
{
|
||||
$plugin = new MockPlugin();
|
||||
|
|
Loading…
Reference in New Issue
Block a user