Merge pull request #19 from maxmind/greg/ws-v2.1

Update for GeoIP2 web services v2.1
This commit is contained in:
Olaf Alders 2014-07-21 12:24:02 -04:00
commit b3e5aaac21
17 changed files with 146 additions and 147 deletions

View File

@ -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)
------------------

View File

@ -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`

View File

@ -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)

View File

@ -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

View File

@ -1,57 +0,0 @@
<?php
namespace GeoIp2\Model;
/**
* This class provides a model for the data returned by the GeoIP2
* City/ISP/Org end point.
*
* The only difference between the City, City/ISP/Org, and Omni 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
* address.
*
* @property \GeoIp2\Record\Continent $continent Continent data for the
* requested IP address.
*
* @property \GeoIp2\Record\Country $country Country data for the requested
* IP address. This object represents the country where MaxMind believes the
* end user is located.
*
* @property \GeoIp2\Record\Location $location Location data for the
* requested IP address.
*
* @property \GeoIp2\Record\MaxMind $maxmind Data related to your MaxMind
* account.
*
* @property \GeoIp2\Record\Country $registeredCountry Registered country
* data for the requested IP address. This record represents the country
* where the ISP has registered a given IP block and may differ from the
* user's country.
*
* @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.
*
* @property array $subdivisions An array of {@link \GeoIp2\Record\Subdivision}
* objects representing the country subdivisions for the requested IP
* address. The number and type of subdivisions varies by country, but a
* subdivision is typically a state, province, county, etc. Subdivisions
* are ordered from most general (largest) to most specific (smallest).
* If the response did not contain any subdivisions, this method returns
* an empty array.
*
* @property \GeoIp2\Record\Subdivision $mostSpecificSubdivision An object
* representing the most specific subdivision returned. If the response
* did not contain any subdivisions, this method returns an empty
* {@link \GeoIp2\Record\Subdivision} object.
*
* @property \GeoIp2\Record\Traits $traits Data for the traits of the
* requested IP address.
*/
class CityIspOrg extends City
{
}

View File

@ -3,10 +3,10 @@
namespace GeoIp2\Model;
/**
* This class provides a model for the data returned by the GeoIP2 Country.
* Model class for the data returned by GeoIP2 Country 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\Continent $continent Continent data for the
@ -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.

View File

@ -3,11 +3,10 @@
namespace GeoIp2\Model;
/**
* This class provides a model for the data returned by the GeoIP2
* Omni end point.
* Model class for the data returned by GeoIP2 Precision: Insights web service.
*
* 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
@ -52,6 +51,6 @@ namespace GeoIp2\Model;
* @property \GeoIp2\Record\Traits $traits Data for the traits of the
* requested IP address.
*/
class Omni extends CityIspOrg
class Insights extends City
{
}

View File

@ -21,14 +21,18 @@ interface ProviderInterface
/**
* @param ipAddress
* IPv4 or IPv6 address to lookup.
* @return \GeoIp2\Model\CityIspOrg A CityIspOrg model for the requested IP address.
* @return \GeoIp2\Model\City A City model for the requested IP address.
*
* @deprecated deprecated since version 0.7.0
*/
public function cityIspOrg($ipAddress);
/**
* @param ipAddress
* IPv4 or IPv6 address to lookup.
* @return \GeoIp2\Model\Omni An Omni model for the requested IP address.
* @return \GeoIp2\Model\Insights An Insights model for the requested IP address.
*
* @deprecated deprecated since version 0.7.0
*/
public function omni($ipAddress);
}

View File

@ -9,7 +9,7 @@ namespace GeoIp2\Record;
*
* @property int $confidence A value from 0-100 indicating MaxMind's
* confidence that the city is correct. This attribute is only available
* from the Omni end point.
* from the Insights end point.
*
* @property int $geonameId The GeoName ID for the city. This attribute
* is returned by all end points.

View File

@ -9,7 +9,7 @@ namespace GeoIp2\Record;
*
* @property int $accuracyRadius The radius in kilometers around the
* specified location where the IP address is likely to be. This attribute
* is only available from the Omni end point.
* is only available from the Insights end point.
*
* @property float $latitude The latitude of the location as a floating
* point number. This attribute is returned by all end points except the

View File

@ -14,7 +14,7 @@ namespace GeoIp2\Record;
*
* @property int $confidence A value from 0-100 indicating MaxMind's
* confidence that the postal code is correct. This attribute is only
* available from the Omni end point.
* available from the Insights end point.
*/
class Postal extends AbstractRecord
{

View File

@ -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 Omni end point.
* 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 <code>military</code>
* but this could expand to include other types such as <code>embassy</code>
* in the future. Returned by all endpoints.
* but this could expand to include other types in the future.
*/
class RepresentedCountry extends Country
{

View File

@ -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.

View File

@ -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 <p>The user type associated with the IP
* address. This can be one of the following values:</p>
@ -66,7 +66,10 @@ namespace GeoIp2\Record;
* <li>search_engine_spider
* <li>traveler
* </ul>
* <p>This attribute is only available from the Omni end point.</p>
* <p>
* This attribute is only available from the Insights web service end
* point.
* </p>
*/
class Traits extends AbstractRecord
{

View File

@ -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';
}
}

View File

@ -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(

View File

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