will/GeoIP2-php
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added basic docs for the API

Browse Source
This commit is contained in:
Gregory Oschwald 2013-05-10 10:47:11 -07:00
parent 8922b3a164
commit 694195fedf
19 changed files with 509 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/GeoIP2/Exception/GenericException.php
View File

@ -2,6 +2,9 @@
namespace GeoIP2\Exception;
/**
* This class represents a generic error.
*/
class GenericException extends \Exception
{
}

17
src/GeoIP2/Exception/HttpException.php
View File

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

15
src/GeoIP2/Exception/WebserviceException.php
View File

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

65
src/GeoIP2/Model/City.php
View File

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

47
src/GeoIP2/Model/CityIspOrg.php
View File

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

37
src/GeoIP2/Model/Country.php
View File

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

47
src/GeoIP2/Model/Omni.php
View File

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

6
src/GeoIP2/Record/AbstractPlaceRecord.php
View File

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

6
src/GeoIP2/Record/AbstractRecord.php
View File

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

21
src/GeoIP2/Record/City.php
View File

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

22
src/GeoIP2/Record/Continent.php
View File

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

25
src/GeoIP2/Record/Country.php
View File

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

32
src/GeoIP2/Record/Location.php
View File

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

17
src/GeoIP2/Record/Postal.php
View File

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

31
src/GeoIP2/Record/RepresentedCountry.php
View File

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

29
src/GeoIP2/Record/Subdivision.php
View File

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

65
src/GeoIP2/Record/Traits.php
View File

@ -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 <p>The user type associated with the IP
* address. This can be one of the following values:</p>
* <ul>
* <li>business
* <li>cafe
* <li>cellular
* <li>college
* <li>content_delivery_network
* <li>dialup
* <li>government
* <li>hosting
* <li>library
* <li>military
* <li>residential
* <li>router
* <li>school
* <li>search_engine_spider
* <li>traveler
* </ul>
* <p>This attribute is only available from the Omni end point.</p>
*/
class Traits extends AbstractRecord
{
/**
* @ignore
*/
protected $validAttributes = array(
'autonomousSystemNumber',
'autonomousSystemOrganization',

36
src/GeoIP2/Webservice/Client.php
View File

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

2
tests/GeoIP2/Test/Webservice/ClientTest.php
View File

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