diff --git a/src/GeoIP2/Exception/GenericException.php b/src/GeoIP2/Exception/GenericException.php index b12d3ac..7195e6c 100644 --- a/src/GeoIP2/Exception/GenericException.php +++ b/src/GeoIP2/Exception/GenericException.php @@ -2,6 +2,9 @@ namespace GeoIP2\Exception; +/** + * This class represents a generic error. + */ class GenericException extends \Exception { } diff --git a/src/GeoIP2/Exception/HttpException.php b/src/GeoIP2/Exception/HttpException.php index 4b5ef85..e0e3851 100644 --- a/src/GeoIP2/Exception/HttpException.php +++ b/src/GeoIP2/Exception/HttpException.php @@ -2,17 +2,24 @@ namespace GeoIP2\Exception; -class HttpException extends \Exception +/** + * This class represents an HTTP transport error. + */ + +class HttpException extends GenericException { - public $code; + /** + * The URI queried + */ + public $uri; public function __construct( $message, - $code, + $httpStatus, $uri, Exception $previous = null ) { - $this->code = $code; - parent::__construct($message, null, $previous); + $this->uri = $uri; + parent::__construct($message, $httpStatus, $previous); } } diff --git a/src/GeoIP2/Exception/WebserviceException.php b/src/GeoIP2/Exception/WebserviceException.php index fc46e31..8134f79 100644 --- a/src/GeoIP2/Exception/WebserviceException.php +++ b/src/GeoIP2/Exception/WebserviceException.php @@ -2,18 +2,25 @@ namespace GeoIP2\Exception; +/** + * This class represents an error returned by MaxMind's GeoIP2 Precision + * web service. + */ class WebserviceException extends HttpException { - public $httpStatus; + /** + * The code returned by the MaxMind web service + */ + public $error; public function __construct( $message, - $code, + $error, $httpStatus, $uri, Exception $previous = null ) { - $this->httpStatus = $httpStatus; - parent::__construct($message, $code, $uri, $previous); + $this->error = $error; + parent::__construct($message, $httpStatus, $uri, $previous); } } diff --git a/src/GeoIP2/Model/City.php b/src/GeoIP2/Model/City.php index 9f09b96..5bb19ee 100644 --- a/src/GeoIP2/Model/City.php +++ b/src/GeoIP2/Model/City.php @@ -2,13 +2,75 @@ namespace GeoIP2\Model; +/** + * This class provides a model for the data returned by the GeoIP2 Precision + * City 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 Country 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\Country $registeredCountry Registered country + * data for the requested IP address. This record represents the country + * where the ISP has registered a given IP block in 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 City extends Country { + /** + * @ignore + */ protected $city; + /** + * @ignore + */ protected $location; + /** + * @ignore + */ protected $postal; + /** + * @ignore + */ protected $subdivisions = array(); + /** + * @ignore + */ public function __construct($raw, $languages) { parent::__construct($raw, $languages); @@ -34,6 +96,9 @@ class City extends Country } } + /** + * @ignore + */ public function __get($attr) { if ($attr == 'mostSpecificSubdivision') { diff --git a/src/GeoIP2/Model/CityIspOrg.php b/src/GeoIP2/Model/CityIspOrg.php index 354d163..e91a344 100644 --- a/src/GeoIP2/Model/CityIspOrg.php +++ b/src/GeoIP2/Model/CityIspOrg.php @@ -2,6 +2,53 @@ namespace GeoIP2\Model; +/** + * This class provides a model for the data returned by the GeoIP2 Precision + * 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 Country 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\Country $registeredCountry Registered country + * data for the requested IP address. This record represents the country + * where the ISP has registered a given IP block in 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 { } diff --git a/src/GeoIP2/Model/Country.php b/src/GeoIP2/Model/Country.php index 9810aa9..daf23c5 100644 --- a/src/GeoIP2/Model/Country.php +++ b/src/GeoIP2/Model/Country.php @@ -2,6 +2,34 @@ namespace GeoIP2\Model; +/** + * This class provides a model for the data returned by the GeoIP2 Country + * 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\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\Country $registeredCountry Registered country + * data for the requested IP address. This record represents the country + * where the ISP has registered a given IP block in 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 \GeoIP2\Record\Traits $traits Data for the traits of the + * requested IP address. + */ class Country { private $continent; @@ -12,6 +40,9 @@ class Country private $traits; private $raw; + /** + * @ignore + */ public function __construct($raw, $languages) { $this->raw = $raw; @@ -37,11 +68,17 @@ class Country $this->languages = $languages; } + /** + * @ignore + */ protected function get($field) { return isset($this->raw[$field]) ? $this->raw[$field] : array(); } + /** + * @ignore + */ public function __get ($attr) { if ($attr != "instance" && isset($this->$attr)) { diff --git a/src/GeoIP2/Model/Omni.php b/src/GeoIP2/Model/Omni.php index c791539..e53e3fc 100644 --- a/src/GeoIP2/Model/Omni.php +++ b/src/GeoIP2/Model/Omni.php @@ -2,6 +2,53 @@ namespace GeoIP2\Model; +/** + * This class provides a model for the data returned by the GeoIP2 Precision + * Omni 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 Country 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\Country $registeredCountry Registered country + * data for the requested IP address. This record represents the country + * where the ISP has registered a given IP block in 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 Omni extends CityIspOrg { } diff --git a/src/GeoIP2/Record/AbstractPlaceRecord.php b/src/GeoIP2/Record/AbstractPlaceRecord.php index a32c2ca..f72e4d7 100644 --- a/src/GeoIP2/Record/AbstractPlaceRecord.php +++ b/src/GeoIP2/Record/AbstractPlaceRecord.php @@ -6,12 +6,18 @@ abstract class AbstractPlaceRecord extends AbstractRecord { private $languages; + /** + * @ignore + */ public function __construct($record, $languages) { $this->languages = $languages; parent::__construct($record); } + /** + * @ignore + */ public function __get($attr) { if ($attr == 'name') { diff --git a/src/GeoIP2/Record/AbstractRecord.php b/src/GeoIP2/Record/AbstractRecord.php index c393867..b2c0721 100644 --- a/src/GeoIP2/Record/AbstractRecord.php +++ b/src/GeoIP2/Record/AbstractRecord.php @@ -6,11 +6,17 @@ abstract class AbstractRecord { private $record; + /** + * @ignore + */ public function __construct($record) { $this->record = $record; } + /** + * @ignore + */ public function __get($attr) { $valid = in_array($attr, $this->validAttributes); diff --git a/src/GeoIP2/Record/City.php b/src/GeoIP2/Record/City.php index 6ef2e68..804942c 100644 --- a/src/GeoIP2/Record/City.php +++ b/src/GeoIP2/Record/City.php @@ -2,7 +2,28 @@ namespace GeoIP2\Record; +/** + * City-level data associated with an IP address. + * + * This record is returned by all the end points except the Country end point. + * + * @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. + * + * @property int $geonameId The GeoName ID for the city. This attribute + * is returned by all end points. + * + * @property string $name The name of the city based on the languages list + * passed to the constructor. This attribute is returned by all end points. + * + * @property array $names A array map where the keys are language codes + * and the values are names. This attribute is returned by all end points. + */ class City extends AbstractPlaceRecord { + /** + * @ignore + */ protected $validAttributes = array('confidence', 'geonameId', 'names'); } diff --git a/src/GeoIP2/Record/Continent.php b/src/GeoIP2/Record/Continent.php index f68b6c8..d0bbc48 100644 --- a/src/GeoIP2/Record/Continent.php +++ b/src/GeoIP2/Record/Continent.php @@ -2,8 +2,30 @@ namespace GeoIP2\Record; +/** + * Contains data for the continent record associated with an IP address + * + * This record is returned by all the end points. + * + * @property string $continentCode A two character continent code + * like "NA" (North America) or "OC" (Oceania). This attribute is returned + * by all end points. + * + * @property int $geonameId The GeoName ID for the continent. This attribute + * is returned by all end points. + * + * @property string $name Returns the name of the continent based on the + * languages list passed to the constructor. This attribute is returned by + * all end points. + * + * @property array $names An array map where the keys are language codes + * and the values are names. This attribute is returned by all end points. + */ class Continent extends AbstractPlaceRecord { + /** + * @ignore + */ protected $validAttributes = array( 'continentCode', 'geonameId', diff --git a/src/GeoIP2/Record/Country.php b/src/GeoIP2/Record/Country.php index 2aab579..0f7b564 100644 --- a/src/GeoIP2/Record/Country.php +++ b/src/GeoIP2/Record/Country.php @@ -2,8 +2,33 @@ namespace GeoIP2\Record; +/** + * Contains data for the country record associated with an IP address + * + * This record is returned by all the end points. + * + * @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. + * + * @property int $geonameId The GeoName ID for the country. This attribute is + * returned by all end points. + * + * @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. + * + * @property string $name The name of the country based on the languages list + * passed to the constructor. This attribute is returned by all end points. + * + * @property array $names An array map where the keys are language codes and + * the values are names. This attribute is returned by all end points. + */ class Country extends AbstractPlaceRecord { + /** + * @ignore + */ protected $validAttributes = array( 'confidence', 'geonameId', diff --git a/src/GeoIP2/Record/Location.php b/src/GeoIP2/Record/Location.php index ae17e43..5104c7e 100644 --- a/src/GeoIP2/Record/Location.php +++ b/src/GeoIP2/Record/Location.php @@ -2,8 +2,40 @@ namespace GeoIP2\Record; +/** + * Contains data for the location record associated with an IP address + * + * This record is returned by all the end points except the Country end point. + * + * @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. + * + * @property float $latitude The latitude of the location as a floating + * point number. This attribute is returned by all end points except the + * Country end point. + * + * @property float $longitude The longitude of the location as a + * floating point number. This attribute is returned by all end points + * except the Country end point. + * + * @property int $metroCode The metro code of the location if the location + * is in the US. MaxMind returns the same metro codes as the + * {@link + * https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions + * Google AdWords API}. This attribute is returned by all end points except + * the Country end point. + * + * @property string $timeZone The time zone associated with location, as + * specified by the {@link http://www.iana.org/time-zones IANA Time Zone + * Database}, e.g., "America/New_York". This attribute is returned by all + * end points except the Country end point. + */ class Location extends AbstractRecord { + /** + * @ignore + */ protected $validAttributes = array( 'accuracyRadius', 'latitude', diff --git a/src/GeoIP2/Record/Postal.php b/src/GeoIP2/Record/Postal.php index 66a2ee6..d7a41e4 100644 --- a/src/GeoIP2/Record/Postal.php +++ b/src/GeoIP2/Record/Postal.php @@ -2,7 +2,24 @@ namespace GeoIP2\Record; +/** + * Contains data for the postal record associated with an IP address + * + * This record is returned by all the end points except the Country end point. + * + * @property string $code The postal code of the location. Postal codes are + * not available for all countries. In some countries, this will only contain + * part of the postal code. This attribute is returned by all end points + * except the Country end point. + * + * @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. + */ class Postal extends AbstractRecord { + /** + * @ignore + */ protected $validAttributes = array('code', 'confidence'); } diff --git a/src/GeoIP2/Record/RepresentedCountry.php b/src/GeoIP2/Record/RepresentedCountry.php index ddc201e..ce7db85 100644 --- a/src/GeoIP2/Record/RepresentedCountry.php +++ b/src/GeoIP2/Record/RepresentedCountry.php @@ -2,6 +2,37 @@ namespace GeoIP2\Record; +/** + * Contains data for the represented country associated with an IP address + * + * 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. + * + * @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. + * + * @property int $geonameId The GeoName ID for the country. This attribute is + * returned by all end points. + * + * @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. + * + * @property string $name The name of the country based on the languages list + * passed to the constructor. This attribute is returned by all end points. + * + * @property array $names An array map where the keys are language codes and + * the values are names. This attribute is returned by all end points. + * + * @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. + */ class RepresentedCountry extends Country { protected $validAttributes = array( diff --git a/src/GeoIP2/Record/Subdivision.php b/src/GeoIP2/Record/Subdivision.php index b209c0e..342b2d8 100644 --- a/src/GeoIP2/Record/Subdivision.php +++ b/src/GeoIP2/Record/Subdivision.php @@ -2,8 +2,37 @@ namespace GeoIP2\Record; +/** + * + * Contains data for the subdivisions associated with an IP address + * + * This record is returned by all the end points except the Country end point. + * + * @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. + * + * @property int $geonameId This is a GeoName ID for the subdivision. This + * attribute is returned by all end points except Country. + * + * @property string $isoCode This is a string up to three characters long + * contain the subdivision portion of the {@link + * http://en.wikipedia.org/wiki/ISO_3166-2 ISO 3166-2 code}. This attribute + * is returned by all end points except Country. + * + * @property string $name The name of the subdivision based on the languages + * list passed to the constructor. This attribute is returned by all end + * points except Country. + * + * @property array $names An array map where the keys are language codes and + * the values are names. This attribute is returned by all end points except + * Country. +*/ class Subdivision extends AbstractPlaceRecord { + /** + * @ignore + */ protected $validAttributes = array( 'confidence', 'geonameId', diff --git a/src/GeoIP2/Record/Traits.php b/src/GeoIP2/Record/Traits.php index 095a3a8..c590bd6 100644 --- a/src/GeoIP2/Record/Traits.php +++ b/src/GeoIP2/Record/Traits.php @@ -2,8 +2,73 @@ namespace GeoIP2\Record; +/** + * + * Contains data for the traits record associated with an IP address + * + * This record is returned by all the end points. + * + * @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. + * + * @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. + * + * @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. + * + * @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 + * will be the externally routable IP address for the system the code is + * running on. If the system is behind a NAT, this may differ from the IP + * address locally assigned to it. This attribute is returned by all end + * points. + * + * @property boolean $isAnonymousProxy This is true if the IP is an + * anonymous proxy. See {@link http://dev.maxmind.com/faq/geoip#anonproxy} + * for further details. This attribute is returned by all end points. + * + * @property string $isp The name of the ISP associated the IP address. + * This attribute is only available from the City/ISP/Org and Omni end + * points. + * + * @property string $organization The name of the organization associated + * the IP address. This attribute is only available from the City/ISP/Org + * and Omni end points. + * + * @property string $userType

The user type associated with the IP + * address. This can be one of the following values:

+ * + *

This attribute is only available from the Omni end point.

+ */ class Traits extends AbstractRecord { + /** + * @ignore + */ protected $validAttributes = array( 'autonomousSystemNumber', 'autonomousSystemOrganization', diff --git a/src/GeoIP2/Webservice/Client.php b/src/GeoIP2/Webservice/Client.php index 509f386..551bd97 100644 --- a/src/GeoIP2/Webservice/Client.php +++ b/src/GeoIP2/Webservice/Client.php @@ -71,7 +71,14 @@ class Client * address is provided, the address that the web service is called * from will be used. * - * @return \GeoIP2\Model\City object + * @return \GeoIP2\Model\City + * + * @throws \GeoIP2\Exception\GenericException 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. */ public function city($ipAddress = 'me') { @@ -85,7 +92,14 @@ class Client * address is provided, the address that the web service is called * from will be used. * - * @return \GeoIP2\Model\City object + * @return \GeoIP2\Model\Country + * + * @throws \GeoIP2\Exception\GenericException 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. */ public function country($ipAddress = 'me') { @@ -99,7 +113,14 @@ class Client * address is provided, the address that the web service is called * from will be used. * - * @return \GeoIP2\Model\City object + * @return \GeoIP2\Model\CityIspOrg + * + * @throws \GeoIP2\Exception\GenericException 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. */ public function cityIspOrg($ipAddress = 'me') { @@ -113,7 +134,14 @@ class Client * address is provided, the address that the web service is called * from will be used. * - * @return \GeoIP2\Model\City object + * @return \GeoIP2\Model\Omni + * + * @throws \GeoIP2\Exception\GenericException 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. */ public function omni($ipAddress = 'me') { diff --git a/tests/GeoIP2/Test/Webservice/ClientTest.php b/tests/GeoIP2/Test/Webservice/ClientTest.php index c9b9f1b..a53e45a 100644 --- a/tests/GeoIP2/Test/Webservice/ClientTest.php +++ b/tests/GeoIP2/Test/Webservice/ClientTest.php @@ -177,7 +177,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase /** * @expectedException GeoIP2\Exception\WebserviceException - * @expectedExceptionCode IP_ADDRESS_INVALID + * @expectedExceptionCode 400 * @expectedExceptionMessage The value "1.2.3" is not a valid ip address */ public function testInvalidIPException()