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..adb61c8 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 @@ -33,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/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 @@ -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 { diff --git a/src/GeoIp2/Record/Subdivision.php b/src/GeoIp2/Record/Subdivision.php index 4d5c5f8..61758dd 100644 --- a/src/GeoIp2/Record/Subdivision.php +++ b/src/GeoIp2/Record/Subdivision.php @@ -10,7 +10,7 @@ namespace GeoIp2\Record; * * @property int $confidence This is a value from 0-100 indicating MaxMind's * confidence that the subdivision is correct. This attribute is only - * available from the Omni end point. + * available from the Insights end point. * * @property int $geonameId This is a GeoName ID for the subdivision. This * attribute is returned by all end points except Country. diff --git a/src/GeoIp2/Record/Traits.php b/src/GeoIp2/Record/Traits.php index 31ca391..7b9285c 100644 --- a/src/GeoIp2/Record/Traits.php +++ b/src/GeoIp2/Record/Traits.php @@ -11,18 +11,18 @@ namespace GeoIp2\Record; * @property int $autonomousSystemNumber The {@link * http://en.wikipedia.org/wiki/Autonomous_system_(Internet) autonomous * system number} associated with the IP address. This attribute is only - * available from the City/ISP/Org and Omni end points. + * available from the City and Insights web service end points. * * @property string $autonomousSystemOrganization The organization * associated with the registered {@link * http://en.wikipedia.org/wiki/Autonomous_system_(Internet) autonomous * system number} for the IP address. This attribute is only available from - * the City/ISP/Org and Omni end points. + * the City and Insights web service end points. * * @property string $domain The second level domain associated with the * IP address. This will be something like "example.com" or "example.co.uk", * not "foo.example.com". This attribute is only available from the - * City/ISP/Org and Omni end points. + * City and Insights web service end points. * * @property string $ipAddress The IP address that the data in the model * is for. If you performed a "me" lookup against the web service, this @@ -40,12 +40,12 @@ namespace GeoIp2\Record; * end points. * * @property string $isp The name of the ISP associated with the IP address. - * This attribute is only available from the City/ISP/Org and Omni end + * This attribute is only available from the City and Insights web service end * points. * * @property string $organization The name of the organization associated - * with the IP address. This attribute is only available from the City/ISP/Org - * and Omni end points. + * with the IP address. This attribute is only available from the City and + * Insights web service end points. * * @property string $userType

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 Insights 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' );