Added basic docs for the API

src/GeoIP2/Exception/GenericException.php

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

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;
+        $this->uri = $uri;
-        parent::__construct($message, null, $previous);
+        parent::__construct($message, $httpStatus, $previous);
     }
 }

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;
+        $this->error = $error;
-        parent::__construct($message, $code, $uri, $previous);
+        parent::__construct($message, $httpStatus, $uri, $previous);
     }
 }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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