From b55d42b5cdcc6b0e0f219303a977ae1f6c3e5142 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Tue, 16 Jul 2013 09:21:08 -0700 Subject: [PATCH] Documentation updates --- README.md | 91 +++++++------- src/GeoIp2/WebService/Client.php | 124 ++++++++++++-------- tests/GeoIp2/Test/WebService/ClientTest.php | 1 + 3 files changed, 127 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index 00a34cd..d629d61 100644 --- a/README.md +++ b/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 +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 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 diff --git a/src/GeoIp2/WebService/Client.php b/src/GeoIp2/WebService/Client.php index 4f11fcc..55410db 100644 --- a/src/GeoIp2/WebService/Client.php +++ b/src/GeoIp2/WebService/Client.php @@ -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'; diff --git a/tests/GeoIp2/Test/WebService/ClientTest.php b/tests/GeoIp2/Test/WebService/ClientTest.php index e71cae2..8c4fb38 100644 --- a/tests/GeoIp2/Test/WebService/ClientTest.php +++ b/tests/GeoIp2/Test/WebService/ClientTest.php @@ -405,6 +405,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase $client->country('1.2.3.18'); } + public function testParams() { $plugin = new MockPlugin();