From a5fe44c3d3d406f8e6cdda0401ba9238b45a650e Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Tue, 15 Jul 2014 14:19:30 -0700 Subject: [PATCH 1/3] Update for GeoIP2 web services v2.1 --- CHANGELOG.md | 10 +++ README.md | 4 +- src/GeoIp2/Database/Reader.php | 16 +++-- src/GeoIp2/Model/City.php | 7 +- src/GeoIp2/Model/CityIspOrg.php | 57 ---------------- src/GeoIp2/Model/Country.php | 6 +- src/GeoIp2/Model/{Omni.php => Insights.php} | 9 ++- src/GeoIp2/ProviderInterface.php | 8 ++- src/GeoIp2/Record/City.php | 2 +- src/GeoIp2/Record/Location.php | 2 +- src/GeoIp2/Record/Postal.php | 2 +- src/GeoIp2/Record/RepresentedCountry.php | 2 +- src/GeoIp2/Record/Subdivision.php | 2 +- src/GeoIp2/Record/Traits.php | 17 +++-- src/GeoIp2/WebService/Client.php | 66 +++++++++++++++---- .../Model/{OmniTest.php => InsightsTest.php} | 22 +++---- tests/GeoIp2/Test/WebService/ClientTest.php | 32 +++++---- 17 files changed, 134 insertions(+), 130 deletions(-) delete mode 100644 src/GeoIp2/Model/CityIspOrg.php rename src/GeoIp2/Model/{Omni.php => Insights.php} (88%) rename tests/GeoIp2/Test/Model/{OmniTest.php => InsightsTest.php} (92%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ecb065..829ac24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,16 @@ CHANGELOG ========= +0.7.0 (2014-07-XX) +------------------ + +* The web service client API has been updated for the v2.1 release of the web + service. In particular, the `cityIspOrg` and `omni` methods on + `GeoIP2\WebService\Client` should be considered deprecated. The `city` + method now provides all of the data formerly provided by `cityIspOrg`, and + the `omni` method has been replaced by the `insights` method. + + 0.6.3 (2014-05-12) ------------------ diff --git a/README.md b/README.md index 239bd86..bb2cbea 100644 --- a/README.md +++ b/README.md @@ -202,7 +202,7 @@ use GeoIp2\WebService\Client; $client = new Client(42, 'abcdef123456'); // Replace "city" with the method corresponding to the web service that -// you are using, e.g., "country", "cityIspOrg", "omni". +// you are using, e.g., "country", "insights". $record = $client->city('128.101.101.101'); print($record->country->isoCode . "\n"); // 'US' @@ -232,7 +232,7 @@ Because of these factors, it is possible for any end point to return a record where some or all of the attributes are unpopulated. See the -[GeoIP2 web service docs](http://dev.maxmind.com/geoip/geoip2/web-services) +[GeoIP2 Precision 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` diff --git a/src/GeoIp2/Database/Reader.php b/src/GeoIp2/Database/Reader.php index edcca79..88d3c59 100644 --- a/src/GeoIp2/Database/Reader.php +++ b/src/GeoIp2/Database/Reader.php @@ -92,37 +92,41 @@ class Reader implements ProviderInterface } /** - * This method returns a GeoIP2 City/ISP/Org model. + * This method returns a GeoIP2 City model. * * @param string $ipAddress IPv4 or IPv6 address as a string. * - * @return \GeoIp2\Model\CityIspOrg + * @return \GeoIp2\Model\City * * @throws \GeoIp2\Exception\AddressNotFoundException if the address is * not in the database. * @throws \MaxMind\Db\Reader\InvalidDatabaseException if the database * is corrupt or invalid + * + * @deprecated deprecated since version 0.7.0 */ public function cityIspOrg($ipAddress) { - return $this->modelFor('CityIspOrg', $ipAddress); + return $this->modelFor('City', $ipAddress); } /** - * This method returns a GeoIP2 Omni model. + * This method returns a GeoIP2 Insights model. * * @param string $ipAddress IPv4 or IPv6 address as a string. * - * @return \GeoIp2\Model\Omni + * @return \GeoIp2\Model\Insights * * @throws \GeoIp2\Exception\AddressNotFoundException if the address is * not in the database. * @throws \MaxMind\Db\Reader\InvalidDatabaseException if the database * is corrupt or invalid + * + * @deprecated deprecated since version 0.7.0 */ public function omni($ipAddress) { - return $this->modelFor('Omni', $ipAddress); + return $this->modelFor('Insights', $ipAddress); } public function connectionType($ipAddress) diff --git a/src/GeoIp2/Model/City.php b/src/GeoIp2/Model/City.php index eca01a5..216e9ac 100644 --- a/src/GeoIp2/Model/City.php +++ b/src/GeoIp2/Model/City.php @@ -3,11 +3,10 @@ namespace GeoIp2\Model; /** - * This class provides a model for the data returned by the GeoIP2 - * City end point. + * Model class for the data returned by GeoIP2 City web service and database. * - * The only difference between the City, City/ISP/Org, and Omni model - * classes is which fields in each record may be populated. See + * The only difference between the City and Insights model classes is which + * fields in each record may be populated. See * http://dev.maxmind.com/geoip/geoip2/web-services more details. * * @property \GeoIp2\Record\City $city City data for the requested IP diff --git a/src/GeoIp2/Model/CityIspOrg.php b/src/GeoIp2/Model/CityIspOrg.php deleted file mode 100644 index 79ead9d..0000000 --- a/src/GeoIp2/Model/CityIspOrg.php +++ /dev/null @@ -1,57 +0,0 @@ -The user type associated with the IP * address. This can be one of the following values:

@@ -66,7 +66,10 @@ namespace GeoIp2\Record; *
  • search_engine_spider *
  • traveler * - *

    This attribute is only available from the Omni end point.

    + *

    + * This attribute is only available from the Insight web service end + * point. + *

    */ class Traits extends AbstractRecord { diff --git a/src/GeoIp2/WebService/Client.php b/src/GeoIp2/WebService/Client.php index 61d5004..7b6bdc2 100644 --- a/src/GeoIp2/WebService/Client.php +++ b/src/GeoIp2/WebService/Client.php @@ -15,10 +15,10 @@ use Guzzle\Http\Exception\ClientErrorResponseException; use Guzzle\Http\Exception\ServerErrorResponseException; /** - * This class provides a client API for all the GeoIP2 web service's - * end points. The end points are Country, City, City/ISP/Org, and Omni. Each - * end point returns a different set of data about an IP address, with Country - * returning the least data and Omni the most. + * This class provides a client API for all the GeoIP2 Precision web service + * end points. The end points are Country, City, and Insights. Each end point + * returns a different set of data about an IP address, with Country returning + * the least data and Insights the most. * * Each web service end point is represented by a different model class, and * these model classes in turn contain multiple Record classes. The record @@ -80,7 +80,7 @@ class Client implements ProviderInterface } /** - * This method calls the GeoIP2 City endpoint. + * This method calls the GeoIP2 Precision: City endpoint. * * @param string $ipAddress IPv4 or IPv6 address as a string. If no * address is provided, the address that the web service is called @@ -112,7 +112,41 @@ class Client implements ProviderInterface } /** - * This method calls the GeoIP2 Country endpoint. + * This method calls the GeoIP2 Precision: City endpoint. + * + * @param string $ipAddress IPv4 or IPv6 address as a string. If no + * address is provided, the address that the web service is called + * from will be used. + * + * @return \GeoIp2\Model\City + * + * @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\OutOfQueriesException 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. + * + * @deprecated deprecated since version 0.7.0 + */ + public function cityIspOrg($ipAddress = 'me') + { + return $this->city($ipAddress); + } + + /** + * This method calls the GeoIP2 Precision: Country endpoint. * * @param string $ipAddress IPv4 or IPv6 address as a string. If no * address is provided, the address that the web service is called @@ -144,13 +178,13 @@ class Client implements ProviderInterface } /** - * This method calls the GeoIP2 City/ISP/Org endpoint. + * This method calls the GeoIP2 Precision: Insights endpoint. * * @param string $ipAddress IPv4 or IPv6 address as a string. If no * address is provided, the address that the web service is called * from will be used. * - * @return \GeoIp2\Model\CityIspOrg + * @return \GeoIp2\Model\Insights * * @throws \GeoIp2\Exception\AddressNotFoundException if the address you * provided is not in our database (e.g., a private address). @@ -169,20 +203,22 @@ class Client implements ProviderInterface * @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. + * + * @deprecated deprecated since version 0.7.0 */ - public function cityIspOrg($ipAddress = 'me') + public function insights($ipAddress = 'me') { - return $this->responseFor('city_isp_org', 'CityIspOrg', $ipAddress); + return $this->responseFor('insights', 'Insights', $ipAddress); } /** - * This method calls the GeoIP2 Omni endpoint. + * This method calls the GeoIP2 Precision: Insights (prev. Omni) endpoint. * * @param string $ipAddress IPv4 or IPv6 address as a string. If no * address is provided, the address that the web service is called * from will be used. * - * @return \GeoIp2\Model\Omni + * @return \GeoIp2\Model\Insights * * @throws \GeoIp2\Exception\AddressNotFoundException if the address you * provided is not in our database (e.g., a private address). @@ -201,10 +237,12 @@ class Client implements ProviderInterface * @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. + * + * @deprecated deprecated since version 0.7.0 */ public function omni($ipAddress = 'me') { - return $this->responseFor('omni', 'Omni', $ipAddress); + return $this->insights($ipAddress); } private function responseFor($endpoint, $class, $ipAddress) @@ -354,6 +392,6 @@ class Client implements ProviderInterface private function baseUri() { - return 'https://' . $this->host . '/geoip/v2.0'; + return 'https://' . $this->host . '/geoip/v2.1'; } } diff --git a/tests/GeoIp2/Test/Model/OmniTest.php b/tests/GeoIp2/Test/Model/InsightsTest.php similarity index 92% rename from tests/GeoIp2/Test/Model/OmniTest.php rename to tests/GeoIp2/Test/Model/InsightsTest.php index 0f4ae7a..9bbb49d 100644 --- a/tests/GeoIp2/Test/Model/OmniTest.php +++ b/tests/GeoIp2/Test/Model/InsightsTest.php @@ -2,9 +2,9 @@ namespace GeoIp2\Test\Model; -use GeoIp2\Model\Omni; +use GeoIp2\Model\Insights; -class OmniTest extends \PHPUnit_Framework_TestCase +class InsightsTest extends \PHPUnit_Framework_TestCase { public function testFull() @@ -69,12 +69,12 @@ class OmniTest extends \PHPUnit_Framework_TestCase ), ); - $model = new Omni($raw, array('en')); + $model = new Insights($raw, array('en')); $this->assertInstanceOf( - 'GeoIp2\Model\Omni', + 'GeoIp2\Model\Insights', $model, - 'GeoIp2\Model\Omni object' + 'GeoIp2\Model\Insights object' ); $this->assertInstanceOf( @@ -147,12 +147,12 @@ class OmniTest extends \PHPUnit_Framework_TestCase { $raw = array('traits' => array('ip_address' => '5.6.7.8')); - $model = new Omni($raw, array('en')); + $model = new Insights($raw, array('en')); $this->assertInstanceOf( - 'GeoIp2\Model\Omni', + 'GeoIp2\Model\Insights', $model, - 'GeoIp2\Model\Omni object with no data except traits.ipAddress' + 'GeoIp2\Model\Insights object with no data except traits.ipAddress' ); $this->assertInstanceOf( @@ -231,12 +231,12 @@ class OmniTest extends \PHPUnit_Framework_TestCase ); // checking whether there are exceptions with unknown keys - $model = new Omni($raw, array('en')); + $model = new Insights($raw, array('en')); $this->assertInstanceOf( - 'GeoIp2\Model\Omni', + 'GeoIp2\Model\Insights', $model, - 'no exception when Omni model gets raw data with unknown keys' + 'no exception when Insights model gets raw data with unknown keys' ); $this->assertEquals( diff --git a/tests/GeoIp2/Test/WebService/ClientTest.php b/tests/GeoIp2/Test/WebService/ClientTest.php index 21a55bf..ae0f1a2 100644 --- a/tests/GeoIp2/Test/WebService/ClientTest.php +++ b/tests/GeoIp2/Test/WebService/ClientTest.php @@ -198,18 +198,22 @@ class ClientTest extends \PHPUnit_Framework_TestCase } - public function testOmni() + public function testInsights() { - $omni = $this->client($this->getResponse('1.2.3.4')) - ->omni('1.2.3.4'); - $this->assertInstanceOf('GeoIp2\Model\Omni', $omni); + $methods = array('omni', 'insights'); + foreach ($methods as $method) { + $record = $this->client($this->getResponse('1.2.3.4')) + ->$method('1.2.3.4'); - $this->assertEquals( - 42, - $omni->continent->geonameId, - 'continent geoname_id is 42' - ); + $this->assertInstanceOf('GeoIp2\Model\Insights', $record); + + $this->assertEquals( + 42, + $record->continent->geonameId, + 'continent geoname_id is 42' + ); + } } public function testCity() @@ -225,7 +229,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase $client = $this->client($this->getResponse('me')); $this->assertInstanceOf( - 'GeoIp2\Model\CityIspOrg', + 'GeoIp2\Model\City', $client->cityIspOrg('me'), 'can set ip parameter to me' ); @@ -233,7 +237,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase /** * @expectedException GeoIp2\Exception\GeoIp2Exception - * @expectedExceptionMessage Received a 200 response for https://geoip.maxmind.com/geoip/v2.0/country/1.2.3.5 but did not receive a HTTP body. + * @expectedExceptionMessage Received a 200 response for https://geoip.maxmind.com/geoip/v2.1/country/1.2.3.5 but did not receive a HTTP body. */ public function testNoBodyException() { @@ -244,7 +248,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase /** * @expectedException GeoIp2\Exception\GeoIp2Exception - * @expectedExceptionMessage Received a 200 response for https://geoip.maxmind.com/geoip/v2.0/country/2.2.3.5 but could not decode the response as JSON: + * @expectedExceptionMessage Received a 200 response for https://geoip.maxmind.com/geoip/v2.1/country/2.2.3.5 but could not decode the response as JSON: */ public function testBadBodyException() { @@ -332,7 +336,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase /** * @expectedException GeoIp2\Exception\HttpException * @expectedExceptionCode 406 - * @expectedExceptionMessage Received a 406 error for https://geoip.maxmind.com/geoip/v2.0/country/1.2.3.12 with the following body: Cannot satisfy your Accept-Charset requirements + * @expectedExceptionMessage Received a 406 error for https://geoip.maxmind.com/geoip/v2.1/country/1.2.3.12 with the following body: Cannot satisfy your Accept-Charset requirements */ public function test406Exception() { @@ -426,7 +430,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase $request = $all_requests[0]; $this->assertEquals( - 'https://geoip.maxmind.com/geoip/v2.0/country/1.2.3.4', + 'https://geoip.maxmind.com/geoip/v2.1/country/1.2.3.4', $request->getUrl(), 'got expected URI for Country request' ); From 6cf9b98993e0ec77edb8b5bffa1d6ed6ff111a4b Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Mon, 21 Jul 2014 07:59:20 -0700 Subject: [PATCH 2/3] Removed mention of embassies --- src/GeoIp2/Model/City.php | 4 ++-- src/GeoIp2/Model/Country.php | 4 ++-- src/GeoIp2/Model/Insights.php | 4 ++-- src/GeoIp2/Record/RepresentedCountry.php | 17 ++++++----------- 4 files changed, 12 insertions(+), 17 deletions(-) diff --git a/src/GeoIp2/Model/City.php b/src/GeoIp2/Model/City.php index 216e9ac..adb61c8 100644 --- a/src/GeoIp2/Model/City.php +++ b/src/GeoIp2/Model/City.php @@ -32,8 +32,8 @@ namespace GeoIp2\Model; * * @property \GeoIp2\Record\RepresentedCountry $representedCountry * Represented country data for the requested IP address. The represented - * country is used for things like military bases or embassies. It is only - * present when the represented country differs from the country. + * country is used for things like military bases. It is only present when + * the represented country differs from the country. * * @property array $subdivisions An array of {@link \GeoIp2\Record\Subdivision} * objects representing the country subdivisions for the requested IP diff --git a/src/GeoIp2/Model/Country.php b/src/GeoIp2/Model/Country.php index 73a1f57..5d8e130 100644 --- a/src/GeoIp2/Model/Country.php +++ b/src/GeoIp2/Model/Country.php @@ -26,8 +26,8 @@ namespace GeoIp2\Model; * * @property \GeoIp2\Record\RepresentedCountry $representedCountry * Represented country data for the requested IP address. The represented - * country is used for things like military bases or embassies. It is only - * present when the represented country differs from the country. + * country is used for things like military bases. It is only present when + * the represented country differs from the country. * * @property \GeoIp2\Record\Traits $traits Data for the traits of the * requested IP address. diff --git a/src/GeoIp2/Model/Insights.php b/src/GeoIp2/Model/Insights.php index e769c6a..a738a99 100644 --- a/src/GeoIp2/Model/Insights.php +++ b/src/GeoIp2/Model/Insights.php @@ -32,8 +32,8 @@ namespace GeoIp2\Model; * * @property \GeoIp2\Record\RepresentedCountry $representedCountry * Represented country data for the requested IP address. The represented - * country is used for things like military bases or embassies. It is only - * present when the represented country differs from the country. + * country is used for things like military bases. It is only present when + * the represented country differs from the country. * * @property array $subdivisions An array of {@link \GeoIp2\Record\Subdivision} * objects representing the country subdivisions for the requested IP diff --git a/src/GeoIp2/Record/RepresentedCountry.php b/src/GeoIp2/Record/RepresentedCountry.php index 620bef9..ed6e35e 100644 --- a/src/GeoIp2/Record/RepresentedCountry.php +++ b/src/GeoIp2/Record/RepresentedCountry.php @@ -7,31 +7,26 @@ namespace GeoIp2\Record; * * This class contains the country-level data associated with an IP address * for the IP's represented country. The represented country is the country - * represented by something like a military base or embassy. - * - * This record is returned by all the end points. + * represented by something like a military base. * * @property int $confidence A value from 0-100 indicating MaxMind's * confidence that the country is correct. This attribute is only available * from the Insights end point. * - * @property int $geonameId The GeoName ID for the country. This attribute is - * returned by all end points. + * @property int $geonameId The GeoName ID for the country. * * @property string $isoCode The {@link http://en.wikipedia.org/wiki/ISO_3166-1 - * two-character ISO 3166-1 alpha code} for the country. This attribute is - * returned by all end points. + * two-character ISO 3166-1 alpha code} for the country. * * @property string $name The name of the country based on the locales list - * passed to the constructor. This attribute is returned by all end points. + * passed to the constructor. * * @property array $names An array map where the keys are locale codes and - * the values are names. This attribute is returned by all end points. + * the values are names. * * @property string $type A string indicating the type of entity that is * representing the country. Currently we only return military - * but this could expand to include other types such as embassy - * in the future. Returned by all endpoints. + * but this could expand to include other types in the future. */ class RepresentedCountry extends Country { From 7d78bd9b2ea64fe7f399b1f62b4d43e9f8390c82 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Mon, 21 Jul 2014 09:23:05 -0700 Subject: [PATCH 3/3] Added missing 's' --- src/GeoIp2/Record/Traits.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GeoIp2/Record/Traits.php b/src/GeoIp2/Record/Traits.php index 59f168d..7b9285c 100644 --- a/src/GeoIp2/Record/Traits.php +++ b/src/GeoIp2/Record/Traits.php @@ -67,7 +67,7 @@ namespace GeoIp2\Record; *
  • traveler * *

    - * This attribute is only available from the Insight web service end + * This attribute is only available from the Insights web service end * point. *

    */