Updates for v0.4.0 release

.gitignore

@@ -1,7 +1,9 @@
-bin/
+_site
+.gh-pages
 composer.lock
 composer.phar
 phpunit.xml
+geoip2-php.sublime-*
 vendor/
 *.sw?
 t.php

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "maxmind-db"]
+	path = maxmind-db
+	url = git://github.com/maxmind/MaxMind-DB.git

.travis.yml

@@ -7,13 +7,17 @@ php:
 
 before_install:
   - composer self-update
-  - composer install
+  - composer install --dev -n --prefer-source
   - pyrus install pear/PHP_CodeSniffer
   - phpenv rehash
 
 script:
+  - mkdir -p build/logs
   - phpcs --standard=PSR2 src/
-  - phpunit
+  - phpunit -c phpunit.xml.dist
+
+after_script:
+  - php vendor/bin/coveralls
 
 notifications:
   email:

CHANGELOG.md

@@ -1,14 +1,44 @@
 CHANGELOG
 =========
 
+0.4.0 (2013-07-16)
+------------------
+
+* This is the first release with the GeoIP2 database reader. Please see the
+  `README.md` file and the `\GeoIp2\Database\Reader` class.
+* The general exception classes were replaced with specific exception classes
+  representing particular types of errors, such as an authentication error.
+
+0.3.0 (2013-07-12)
+------------------
+
+* In namespaces and class names, "GeoIP2" was renamed to "GeoIp2" to improve
+  consistency.
+
+0.2.1 (2013-06-10)
+------------------
+
+* First official beta release.
+* Documentation updates and corrections.
+
+0.2.0 (2013-05-29)
+------------------
+
+* `GenericException` was renamed to `GeoIP2Exception`.
+* We now support more languages. The new languages are de, es, fr, and pt-BR.
+* The REST API now returns a record with data about your account. There is
+  a new `GeoIP\Records\MaxMind` class for this data.
+* The `continentCode` attribute on `Continent` was renamed to `code`.
+* Documentation updates.
+
 0.1.1 (2013-05-14)
 ------------------
 
-* Updated Guzzle version requirement
-* Fixed Composer example in README.md
+* Updated Guzzle version requirement.
+* Fixed Composer example in README.md.
 
 
 0.1.0 (2013-05-13)
 ------------------
 
-* Initial release
+* Initial release.

README.md

@@ -1,28 +1,34 @@
 # GeoIP2 PHP API #
 
+## Beta Note ##
+
+This is a beta release. The API may change before the first production
+release, which will be numbered 2.0.0.
+
+You may find information on the GeoIP2 beta release process on [our
+website](http://www.maxmind.com/en/geoip2_beta).
+
+To provide feedback or get support during the beta, please see the
+[MaxMind Customer Community](https://getsatisfaction.com/maxmind).
+
 ## Description ##
 
-Currently, this distribution provides an API for the GeoIP2 web services
- (as documented at http://dev.maxmind.com/geoip/geoip2/web-services).
-
-In the future, this distribution will also provide the same API for the
-GeoIP2 downloadable databases. These databases have not yet been
-released as a downloadable product.
-
-See GeoIP2\WebService\Client for details on the web service client
-API.
+This distribution provides an API for the [GeoIP2 web services]
+(http://dev.maxmind.com/geoip/geoip2/web-services) and the [GeoLite2
+databases](http://dev.maxmind.com/geoip/geoip2/geolite2/). The commercial
+GeoIP2 databases have not yet been released as a downloadable product.
 
 ## Installation ##
 
 ### Define Your Dependencies ###
 
 We recommend installing this package with [Composer](http://getcomposer.org/).
-To do this, add ```geoip2/geoip2``` to your ```composer.json``` file.
+To do this, add `geoip2/geoip2` to your `composer.json` file.
 
 ```json
 {
     "require": {
-        "geoip2/geoip2": "0.1.*"
+        "geoip2/geoip2": "0.4.*"
     }
 }
 ```
@@ -49,11 +55,43 @@ You can autoload all dependencies by adding this to your code:
 ```
 require 'vendor/autoload.php';
 ```
+## Database Reader ##
 
-## Usage ##
+### Usage ###
 
-To use this API, you must create a new ``\GeoIP2\WebService\Client``
-object with your ``$userId`` and ``$licenseKey``, then you call the method
+To use this API, you must create a new `\GeoIp2\Database\Reader` object with
+the path to the database file as the first argument to the constructor. You
+may then call the method corresponding to the database you are using.
+
+If the lookup succeeds, the method call will return a model class for the
+record in the database. This model in turn contains multiple container
+classes for the different parts of the data such as the city in which the
+IP address is located.
+
+If the record is not found, a `\GeoIp2\Exception\AddressNotFoundException`
+is returned. If the database is invalid or corrupt, a
+`\MaxMind\Db\InvalidDatabaseException` will be thrown.
+
+See the API documentation for more details.
+
+### Example ###
+
+```php
+<?php
+require_once 'vendor/autoload.php';
+use \GeoIp2\Database\Reader;
+
+$reader = new Reader('/usr/local/share/GeoIP2/GeoIP2-City.mmdb');
+$record = $reader->city('24.24.24.24');
+print($record->country->isoCode);
+```
+
+## Web Service Client ##
+
+### Usage ###
+
+To use this API, you must create a new `\GeoIp2\WebService\Client`
+object with your `$userId` and `$licenseKey`, then you call the method
 corresponding to a specific end point, passing it the IP address you want to
 look up.
 
@@ -61,41 +99,23 @@ If the request succeeds, the method call will return a model class for the end
 point you called. This model in turn contains multiple record classes, each of
 which represents part of the data returned by the web service.
 
+If there is an error, a structured exception is thrown.
+
 See the API documentation for more details.
 
-## Example ##
+### Example ###
 
 ```php
 <?php
 require_once 'vendor/autoload.php';
-use \GeoIP2\WebService\Client;
+use \GeoIp2\WebService\Client;
 
 $client = new Client(42, 'abcdef123456');
 $omni = $client->omni('24.24.24.24');
-echo $omni->country->isoCode;
+print($omni->country->isoCode);
 ```
 
-## Exceptions ##
-
-For details on the possible errors returned by the web service itself, see
-http://dev.maxmind.com/geoip2/geoip/web-services for the GeoIP2 web service
-docs.
-
-If the web service returns an explicit error document, this is thrown as a
-```\GeoIP2\Exception\WebServiceException```. If some other sort of transport
-error occurs, this is thrown as a ```\GeoIP2\Exception\HttpException```.
-The difference is that the web service error includes an error message and
-error code delivered by the web service. The latter is thrown when some sort
-of unanticipated error occurs, such as the web service returning a 500 or an
-invalid error document.
-
-If the web service returns any status code besides 200, 4xx, or 5xx, this also
-becomes a ```\GeoIP2\Exception\HttpException```.
-
-Finally, if the web service returns a 200 but the body is invalid, the client
-throws a ```\GeoIP2\Exception\GenericException```.
-
-## What data is returned? ##
+### What data is returned? ###
 
 While many of the end points return the same basic records, the attributes
 which can be populated vary between end points. In addition, while an end
@@ -105,11 +125,12 @@ piece of data for any given IP address.
 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 http://dev.maxmind.com/geoip/geoip2/web-services for details on what data
-each end point may return.
+See the
+[GeoIP2 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```
-attribute in the ``GeoIP2\Record\Traits`` record.
+The only piece of data which is always returned is the `ipAddress`
+attribute in the `GeoIp2\Record\Traits` record.
 
 Every record class attribute has a corresponding predicate method so you can
 check to see if the attribute is set.
@@ -119,10 +140,10 @@ check to see if the attribute is set.
 [GeoNames](http://www.geonames.org/) offers web services and downloadable
 databases with data on geographical features around the world, including
 populated places. They offer both free and paid premium data. Each
-feature is unique identified by a ```geonameId```, which is an integer.
+feature is unique identified by a `geonameId`, which is an integer.
 
 Many of the records returned by the GeoIP2 web services and databases
-include a ```geonameId``` property. This is the ID of a geographical feature
+include a `geonameId` property. This is the ID of a geographical feature
 (city, region, country, etc.) in the GeoNames database.
 
 Some of the data that MaxMind provides is also sourced from GeoNames. We
@@ -132,11 +153,11 @@ the GeoNames premium data set.
 ## Reporting data problems ##
 
 If the problem you find is that an IP address is incorrectly mapped,
-please submit your correction to MaxMind at
-http://www.maxmind.com/en/correction.
+please
+[submit your correction to MaxMind](http://www.maxmind.com/en/correction).
 
 If you find some other sort of mistake, like an incorrect spelling,
-please check the GeoNames site (http://www.geonames.org/) first. Once
+please check the [GeoNames site](http://www.geonames.org/) first. Once
 you've searched for a place and found it on the GeoNames map view, there
 are a number of links you can use to correct data ("move", "edit",
 "alternate names", etc.). Once the correction is part of the GeoNames
@@ -144,17 +165,17 @@ data set, it will be automatically incorporated into future MaxMind
 releases.
 
 If you are a paying MaxMind customer and you're not sure where to submit
-a correction, please contact MaxMind support at
-http://www.maxmind.com/en/support for help.
+a correction, please
+[contact MaxMind support](http://www.maxmind.com/en/support) for help.
 
 ## Other Support ##
 
-Please report all issues with this code using the GitHub issue tracker
-at https://github.com/maxmind/GeoIP2-php/issues
+Please report all issues with this code using the
+[GitHub issue tracker](https://github.com/maxmind/GeoIP2-php/issues).
 
 If you are having an issue with a MaxMind service that is not specific
-to the client API please see http://www.maxmind.com/en/support for
-details.
+to the client API, please see
+[our support page](http://www.maxmind.com/en/support).
 
 ## Requirements  ##
 
@@ -172,10 +193,6 @@ PSR-2 style guidelines. Please include unit tests whenever possible.
 
 The GeoIP2 PHP API uses [Semantic Versioning](http://semver.org/).
 
-## Author ##
-
-[Gregory Oschwald](mailto:goschwald@maxmind.com)
-
 ## Copyright and License ##
 
 This software is Copyright (c) 2013 by MaxMind, Inc.

bin/release.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+
+TAG=$1
+
+if [ -z $TAG ]; then
+    echo "Please specify a tag"
+    exit 1
+fi
+
+if [ -n "$(git status --porcelain)" ]; then
+    echo ". is not clean." >&2
+    exit 1
+fi
+
+if [ ! -d .gh-pages ]; then
+    echo "Checking out gh-pages in .gh-pages"
+    git clone -b gh-pages git@git.maxmind.com:GeoIP2-php .gh-pages
+    cd .gh-pages
+else
+    echo "Updating .gh-pages"
+    cd .gh-pages
+    git pull
+fi
+
+if [ -n "$(git status --porcelain)" ]; then
+    echo ".gh-pages is not clean" >&2
+    exit 1
+fi
+
+apigen --quiet --download --title "GeoIP2 PHP API $TAG" --source ../src --destination doc/$TAG
+
+PAGE=index.md
+cat <<EOF > $PAGE
+---
+layout: default
+title: MaxMind GeoIP2 PHP API
+language: php
+version: $TAG
+---
+
+EOF
+
+cat ../README.md >> $PAGE
+
+git add doc/
+git commit -m "Updated for $TAG" -a
+
+read -e -p "Push to origin? " SHOULD_PUSH
+
+if [ "$SHOULD_PUSH" != "y" ]; then
+    echo "Aborting"
+    exit 1
+fi
+
+# If we don't push directly to github, the page doesn't get built for some
+# reason.
+git push git@github.com:maxmind/GeoIP2-php.git
+git push
+
+cd ..
+git tag -a $TAG
+git push
+git push --tags

composer.json

@@ -14,12 +14,14 @@
     ],
     "require": {
         "guzzle/guzzle": "3.*",
+        "maxmind-db/reader": "0.1.*",
         "php": ">=5.3.1"
     },
     "require-dev": {
-        "phpunit/phpunit": "3.7.*"
+        "phpunit/phpunit": "3.7.*",
+        "satooshi/php-coveralls": "dev-master"
     },
     "autoload": {
-        "psr-0": { "GeoIP2": "src/" }
+        "psr-0": { "GeoIp2": "src/" }
     }
 }

phpunit.xml.dist

@@ -3,13 +3,18 @@
 <phpunit bootstrap="./tests/bootstrap.php" colors="true">
     <testsuites>
         <testsuite name="GeoIP2 Test Suite">
-            <directory suffix="Test.php">./tests/GeoIP2/Test/</directory>
+            <directory suffix="Test.php">./tests/GeoIp2/Test/</directory>
         </testsuite>
     </testsuites>
 
     <filter>
         <whitelist>
-            <directory suffix=".php">./src/GeoIP2/</directory>
+            <directory suffix=".php">./src/GeoIp2/</directory>
         </whitelist>
     </filter>
+
+    <logging>
+        <log type="coverage-clover" target="build/logs/clover.xml"/>
+    </logging>
+
 </phpunit>

src/GeoIP2/Exception/GenericException.php

@@ -1,10 +0,0 @@
-<?php
-
-namespace GeoIP2\Exception;
-
-/**
- * This class represents a generic error.
- */
-class GenericException extends \Exception
-{
-}

src/GeoIp2/Database/Reader.php

@@ -0,0 +1,150 @@
+<?php
+
+namespace GeoIp2\Database;
+
+use GeoIp2\Exception\AddressNotFoundException;
+use GeoIp2\Model\City;
+use GeoIp2\Model\CityIspOrg;
+use GeoIp2\Model\Country;
+use GeoIp2\Model\Omni;
+use MaxMind\Db\Reader as DbReader;
+
+/**
+ * Instances of this class provide a reader for the GeoIP2 database format.
+ * IP addresses can be looked up using the <code>country</code>
+ * and <code>city</code> methods. We also provide <code>cityIspOrg</code>
+ * and <code>omni</code> methods to ease compatibility with the web service
+ * client, although we may offer the ability to specify additional databases
+ * to replicate these web services in the future (e.g., the ISP/Org database).
+ *
+  * **Usage**
+ *
+ * The basic API for this class is the same for every database. First, you
+ * create a reader object, specifying a file name. You then call the method
+ * corresponding to the specific database, passing it the IP address you want
+ * to look up.
+ *
+ * If the request succeeds, the method call will return a model class for
+ * the method you called. This model in turn contains multiple record classes,
+ * each of which represents part of the data returned by the database. If
+ * the database does not contain the requested information, the attributes
+ * on the record class will have a <code>null</code> value.
+ *
+ * If the address is not in the database, an
+ * {@link \GeoIp2\Exception\AddressNotFoundException} exception will be
+ * thrown. If an invalid IP address is passed to one of the methods, a
+ * SPL {@link \InvalidArgumentException} will be thrown. If the database is
+ * corrupt or invalid, a {@link \MaxMind\Db\Reader\InvalidDatabaseException}
+ * will be thrown.
+ *
+ */
+class Reader
+{
+    private $dbReader;
+    private $languages;
+
+    /**
+     * Constructor.
+     *
+     * @param string $filename The path to the GeoIP2 database file.
+     * @throws \MaxMind\Db\Reader\InvalidDatabaseException if the database
+     *          is corrupt or invalid
+     */
+    public function __construct(
+        $filename,
+        $languages = array('en')
+    ) {
+        $this->dbReader = new DbReader($filename);
+        $this->languages = $languages;
+    }
+
+    /**
+     * This method returns a GeoIP2 City model.
+     *
+     * @param string $ipAddress IPv4 or IPv6 address as a string.
+     *
+     * @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
+     */
+    public function city($ipAddress)
+    {
+        return $this->modelFor('City', $ipAddress);
+    }
+
+    /**
+     * This method returns a GeoIP2 Country model.
+     *
+     * @param string $ipAddress IPv4 or IPv6 address as a string.
+     *
+     * @return \GeoIp2\Model\Country
+     *
+     * @throws \GeoIp2\Exception\AddressNotFoundException if the address is
+     *         not in the database.
+     * @throws \MaxMind\Db\Reader\InvalidDatabaseException if the database
+     *         is corrupt or invalid
+     */
+    public function country($ipAddress)
+    {
+        return $this->modelFor('Country', $ipAddress);
+    }
+
+    /**
+     * This method returns a GeoIP2 City/ISP/Org model.
+     *
+     * @param string $ipAddress IPv4 or IPv6 address as a string.
+     *
+     * @return \GeoIp2\Model\CityIspOrg
+     *
+     * @throws \GeoIp2\Exception\AddressNotFoundException if the address is
+     *         not in the database.
+     * @throws \MaxMind\Db\Reader\InvalidDatabaseException if the database
+     *         is corrupt or invalid
+     */
+    public function cityIspOrg($ipAddress)
+    {
+        return $this->modelFor('CityIspOrg', $ipAddress);
+    }
+
+    /**
+     * This method returns a GeoIP2 Omni model.
+     *
+     * @param string $ipAddress IPv4 or IPv6 address as a string.
+     *
+     * @return \GeoIp2\Model\Omni
+     *
+     * @throws \GeoIp2\Exception\AddressNotFoundException if the address is
+     *         not in the database.
+     * @throws \MaxMind\Db\Reader\InvalidDatabaseException if the database
+     *         is corrupt or invalid
+     */
+    public function omni($ipAddress)
+    {
+        return $this->modelFor('Omni', $ipAddress);
+    }
+
+    private function modelFor($class, $ipAddress)
+    {
+        $record = $this->dbReader->get($ipAddress);
+        if ($record === null) {
+            throw new AddressNotFoundException(
+                "The address $ipAddress is not in the database."
+            );
+        }
+        $record['traits']['ip_address'] = $ipAddress;
+        $class = "GeoIp2\\Model\\" . $class;
+
+        return new $class($record, $this->languages);
+    }
+
+    /**
+     * Closes the GeoIP2 database and returns the resources to the system.
+     */
+    public function close()
+    {
+        $this->dbReader->close();
+    }
+}

src/GeoIp2/Exception/AddressNotFoundException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace GeoIp2\Exception;
+
+/**
+ * This class represents a generic error.
+ */
+class AddressNotFoundException extends GeoIp2Exception
+{
+}

src/GeoIp2/Exception/AuthenticationException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace GeoIp2\Exception;
+
+/**
+ * This class represents a generic error.
+ */
+class AuthenticationException extends GeoIp2Exception
+{
+}

src/GeoIp2/Exception/GeoIp2Exception.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace GeoIp2\Exception;
+
+/**
+ * This class represents a generic error.
+ */
+class GeoIp2Exception extends \Exception
+{
+}

src/GeoIp2/Exception/HttpException.php

@@ -1,12 +1,12 @@
 <?php
 
-namespace GeoIP2\Exception;
+namespace GeoIp2\Exception;
 
 /**
  *  This class represents an HTTP transport error.
  */
 
-class HttpException extends GenericException
+class HttpException extends GeoIp2Exception
 {
     /**
      * The URI queried

src/GeoIp2/Exception/InvalidRequestException.php

@@ -1,12 +1,12 @@
 <?php
 
-namespace GeoIP2\Exception;
+namespace GeoIp2\Exception;
 
 /**
- * This class represents an error returned by MaxMind's GeoIP2 Precision
+ * This class represents an error returned by MaxMind's GeoIP2
  * web service.
  */
-class WebServiceException extends HttpException
+class InvalidRequestException extends HttpException
 {
     /**
      * The code returned by the MaxMind web service

src/GeoIp2/Exception/OutOfQueriesException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace GeoIp2\Exception;
+
+/**
+ * This class represents a generic error.
+ */
+class OutOfQueriesException extends GeoIp2Exception
+{
+}

src/GeoIp2/Model/City.php

@@ -1,39 +1,42 @@
 <?php
 
-namespace GeoIP2\Model;
+namespace GeoIp2\Model;
 
 /**
- * This class provides a model for the data returned by the GeoIP2 Precision
+ * This class provides a model for the data returned by the GeoIP2
  * 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
+ * @property \GeoIp2\Record\City $city City data for the requested IP
  * address.
  *
- * @property \GeoIP2\Record\Continent $continent Continent data for the
+ * @property \GeoIp2\Record\Continent $continent Continent data for the
  * requested IP address.
  *
- * @property \GeoIP2\Record\Country $country Country data for the requested
+ * @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
+ * @property \GeoIp2\Record\Location $location Location data for the
  * requested IP address.
  *
- * @property \GeoIP2\Record\Country $registeredCountry Registered country
+ * @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 in and may differ from the
+ * where the ISP has registered a given IP block and may differ from the
  * user's country.
  *
- * @property \GeoIP2\Record\RepresentedCountry $representedCountry
+ * @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}
+ * @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
@@ -41,12 +44,12 @@ namespace GeoIP2\Model;
  * If the response did not contain any subdivisions, this method returns
  * an empty array.
  *
- * @property \GeoIP2\Record\Subdivision $mostSpecificSubdivision An  object
+ * @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.
+ * {@link \GeoIp2\Record\Subdivision} object.
  *
- * @property \GeoIP2\Record\Traits $traits Data for the traits of the
+ * @property \GeoIp2\Record\Traits $traits Data for the traits of the
  * requested IP address.
  */
 class City extends Country
@@ -75,9 +78,9 @@ class City extends Country
     {
         parent::__construct($raw, $languages);
 
-        $this->city = new \GeoIP2\Record\City($this->get('city'), $languages);
-        $this->location = new \GeoIP2\Record\Location($this->get('location'));
-        $this->postal = new \GeoIP2\Record\Postal($this->get('postal'));
+        $this->city = new \GeoIp2\Record\City($this->get('city'), $languages);
+        $this->location = new \GeoIp2\Record\Location($this->get('location'));
+        $this->postal = new \GeoIp2\Record\Postal($this->get('postal'));
 
         $this->createSubdivisions($raw, $languages);
     }
@@ -91,7 +94,7 @@ class City extends Country
         foreach ($raw['subdivisions'] as $sub) {
             array_push(
                 $this->subdivisions,
-                new \GeoIP2\Record\Subdivision($sub, $languages)
+                new \GeoIp2\Record\Subdivision($sub, $languages)
             );
         }
     }
@@ -111,7 +114,7 @@ class City extends Country
     private function mostSpecificSubdivision()
     {
         return empty($this->subdivisions)?
-            new \GeoIP2\Record\Subdivision(array(), $this->languages):
+            new \GeoIp2\Record\Subdivision(array(), $this->languages):
             end($this->subdivisions);
     }
 }

src/GeoIp2/Model/CityIspOrg.php

@@ -1,39 +1,42 @@
 <?php
 
-namespace GeoIP2\Model;
+namespace GeoIp2\Model;
 
 /**
- * This class provides a model for the data returned by the GeoIP2 Precision
+ * 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 Country data for the requested IP
+ * @property \GeoIp2\Record\City $city City data for the requested IP
  * address.
  *
- * @property \GeoIP2\Record\Continent $continent Continent data for the
+ * @property \GeoIp2\Record\Continent $continent Continent data for the
  * requested IP address.
  *
- * @property \GeoIP2\Record\Country $country Country data for the requested
+ * @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
+ * @property \GeoIp2\Record\Location $location Location data for the
  * requested IP address.
  *
- * @property \GeoIP2\Record\Country $registeredCountry Registered country
+ * @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 in and may differ from the
+ * where the ISP has registered a given IP block and may differ from the
  * user's country.
  *
- * @property \GeoIP2\Record\RepresentedCountry $representedCountry
+ * @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}
+ * @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
@@ -41,12 +44,12 @@ namespace GeoIP2\Model;
  * If the response did not contain any subdivisions, this method returns
  * an empty array.
  *
- * @property \GeoIP2\Record\Subdivision $mostSpecificSubdivision An  object
+ * @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.
+ * {@link \GeoIp2\Record\Subdivision} object.
  *
- * @property \GeoIP2\Record\Traits $traits Data for the traits of the
+ * @property \GeoIp2\Record\Traits $traits Data for the traits of the
  * requested IP address.
  */
 class CityIspOrg extends City

src/GeoIp2/Model/Country.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace GeoIP2\Model;
+namespace GeoIp2\Model;
 
 /**
  * This class provides a model for the data returned by the GeoIP2 Country
@@ -10,24 +10,27 @@ namespace GeoIP2\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
+ * @property \GeoIp2\Record\Continent $continent Continent data for the
  * requested IP address.
  *
- * @property \GeoIP2\Record\Country $country Country data for the requested
+ * @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
+ * @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 in and may differ from the
+ * where the ISP has registered a given IP block and may differ from the
  * user's country.
  *
- * @property \GeoIP2\Record\RepresentedCountry $representedCountry
+ * @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
+ * @property \GeoIp2\Record\Traits $traits Data for the traits of the
  * requested IP address.
  */
 class Country
@@ -35,6 +38,7 @@ class Country
     private $continent;
     private $country;
     private $languages;
+    private $maxmind;
     private $registeredCountry;
     private $representedCountry;
     private $traits;
@@ -47,23 +51,24 @@ class Country
     {
         $this->raw = $raw;
 
-        $this->continent = new \GeoIP2\Record\Continent(
+        $this->continent = new \GeoIp2\Record\Continent(
             $this->get('continent'),
             $languages
         );
-        $this->country = new \GeoIP2\Record\Country(
+        $this->country = new \GeoIp2\Record\Country(
             $this->get('country'),
             $languages
         );
-        $this->registeredCountry = new \GeoIP2\Record\Country(
+        $this->maxmind = new \GeoIp2\Record\MaxMind($this->get('maxmind'));
+        $this->registeredCountry = new \GeoIp2\Record\Country(
             $this->get('registered_country'),
             $languages
         );
-        $this->representedCountry = new \GeoIP2\Record\RepresentedCountry(
+        $this->representedCountry = new \GeoIp2\Record\RepresentedCountry(
             $this->get('represented_country'),
             $languages
         );
-        $this->traits = new \GeoIP2\Record\Traits($this->get('traits'));
+        $this->traits = new \GeoIp2\Record\Traits($this->get('traits'));
 
         $this->languages = $languages;
     }

src/GeoIp2/Model/Omni.php

@@ -1,39 +1,42 @@
 <?php
 
-namespace GeoIP2\Model;
+namespace GeoIp2\Model;
 
 /**
- * This class provides a model for the data returned by the GeoIP2 Precision
+ * This class provides a model for the data returned by the GeoIP2
  * 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
+ * @property \GeoIp2\Record\City $city City data for the requested IP
  * address.
  *
- * @property \GeoIP2\Record\Continent $continent Continent data for the
+ * @property \GeoIp2\Record\Continent $continent Continent data for the
  * requested IP address.
  *
- * @property \GeoIP2\Record\Country $country Country data for the requested
+ * @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
+ * @property \GeoIp2\Record\Location $location Location data for the
  * requested IP address.
  *
- * @property \GeoIP2\Record\Country $registeredCountry Registered country
+ * @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 in and may differ from the
+ * where the ISP has registered a given IP block and may differ from the
  * user's country.
  *
- * @property \GeoIP2\Record\RepresentedCountry $representedCountry
+ * @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}
+ * @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
@@ -41,12 +44,12 @@ namespace GeoIP2\Model;
  * If the response did not contain any subdivisions, this method returns
  * an empty array.
  *
- * @property \GeoIP2\Record\Subdivision $mostSpecificSubdivision An  object
+ * @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.
+ * {@link \GeoIp2\Record\Subdivision} object.
  *
- * @property \GeoIP2\Record\Traits $traits Data for the traits of the
+ * @property \GeoIp2\Record\Traits $traits Data for the traits of the
  * requested IP address.
  */
 class Omni extends CityIspOrg

src/GeoIp2/Record/AbstractPlaceRecord.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace GeoIP2\Record;
+namespace GeoIp2\Record;
 
 abstract class AbstractPlaceRecord extends AbstractRecord
 {

src/GeoIp2/Record/AbstractRecord.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace GeoIP2\Record;
+namespace GeoIp2\Record;
 
 abstract class AbstractRecord
 {

src/GeoIp2/Record/City.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace GeoIP2\Record;
+namespace GeoIp2\Record;
 
 /**
  * City-level data associated with an IP address.

src/GeoIp2/Record/Continent.php

@@ -1,15 +1,14 @@
 <?php
 
-namespace GeoIP2\Record;
+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 string $code 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.
@@ -27,7 +26,7 @@ class Continent extends AbstractPlaceRecord
      * @ignore
      */
     protected $validAttributes = array(
-        'continentCode',
+        'code',
         'geonameId',
         'names'
     );

src/GeoIp2/Record/Country.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace GeoIP2\Record;
+namespace GeoIp2\Record;
 
 /**
  * Contains data for the country record associated with an IP address

src/GeoIp2/Record/Location.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace GeoIP2\Record;
+namespace GeoIp2\Record;
 
 /**
  * Contains data for the location record associated with an IP address

src/GeoIp2/Record/MaxMind.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace GeoIp2\Record;
+
+/**
+ * Contains data about your account.
+ *
+ * This record is returned by all the end points.
+ *
+ * @property int $queriesRemaining The number of remaining queries you have
+ * for the end point you are calling.
+ */
+class MaxMind extends AbstractRecord
+{
+    /**
+     * @ignore
+     */
+    protected $validAttributes = array('queriesRemaining');
+}

src/GeoIp2/Record/Postal.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace GeoIP2\Record;
+namespace GeoIp2\Record;
 
 /**
  * Contains data for the postal record associated with an IP address

src/GeoIp2/Record/RepresentedCountry.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace GeoIP2\Record;
+namespace GeoIp2\Record;
 
 /**
  * Contains data for the represented country associated with an IP address

src/GeoIp2/Record/Subdivision.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace GeoIP2\Record;
+namespace GeoIp2\Record;
 
 /**
  *

src/GeoIp2/Record/Traits.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace GeoIP2\Record;
+namespace GeoIp2\Record;
 
 /**
  *
@@ -35,12 +35,16 @@ namespace GeoIP2\Record;
  * 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.
+ * @property boolean $isSatelliteProvider This is true if the IP belongs
+ * to a satellite Internet provider.  This attribute is returned by all
+ * 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
  * points.
  *
  * @property string $organization The name of the organization associated
- * the IP address. This attribute is only available from the City/ISP/Org
+ * with 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

src/GeoIp2/WebService/Client.php

@@ -1,21 +1,24 @@
 <?php
 
-namespace GeoIP2\WebService;
+namespace GeoIp2\WebService;
 
-use GeoIP2\Exception\GenericException;
-use GeoIP2\Exception\HttpException;
-use GeoIP2\Exception\WebServiceException;
-use GeoIP2\Model\City;
-use GeoIP2\Model\CityIspOrg;
-use GeoIP2\Model\Country;
-use GeoIP2\Model\Omni;
+use GeoIp2\Exception\GeoIp2Exception;
+use GeoIp2\Exception\HttpException;
+use GeoIp2\Exception\AddressNotFoundException;
+use GeoIp2\Exception\AuthenticationException;
+use GeoIp2\Exception\InvalidRequestException;
+use GeoIp2\Exception\OutOfQueriesException;
+use GeoIp2\Model\City;
+use GeoIp2\Model\CityIspOrg;
+use GeoIp2\Model\Country;
+use GeoIp2\Model\Omni;
 use Guzzle\Http\Client as GuzzleClient;
 use Guzzle\Common\Exception\RuntimeException;
 use Guzzle\Http\Exception\ClientErrorResponseException;
 use Guzzle\Http\Exception\ServerErrorResponseException;
 
 /**
- * This class provides a client API for all the GeoIP Precision web service's
+ * 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.
@@ -44,26 +47,6 @@ use Guzzle\Http\Exception\ServerErrorResponseException;
  * service.
  *
  * If the request fails, the client class throws an exception.
- *
- * **Exceptions**
- *
- * For details on the possible errors returned by the web service itself, see
- * {@link http://dev.maxmind.com/geoip2/geoip/web-services the GeoIP2 web
- * service docs}.
- *
- * If the web service returns an explicit error document, this is thrown as a
- * {@link \GeoIP2\Exception\WebServiceException}. If some other sort of
- * transport error occurs, this is thrown as a {@link
- * \GeoIP2\Exception\HttpException}. The difference is that the web service
- * error includes an error message and error code delivered by the web
- * service. The latter is thrown when some sort of unanticipated error occurs,
- * such as the web service returning a 500 or an invalid error document.
- *
- * If the web service returns any status code besides 200, 4xx, or 5xx, this
- * also becomes a {@link \GeoIP2\Exception\HttpException}.
- *
- * Finally, if the web service returns a 200 but the body is invalid, the
- * client throws a {@link \GeoIP2\Exception\GenericException}.
  */
 class Client
 {
@@ -100,20 +83,31 @@ class Client
     }
 
     /**
-     * This method calls the GeoIP2 Precision City endpoint.
+     * This method calls the GeoIP2 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
+     * @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.
+     * @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\QutOfQueriesException 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.
      */
     public function city($ipAddress = 'me')
     {
@@ -127,14 +121,25 @@ class Client
      * address is provided, the address that the web service is called
      * from will be used.
      *
-     * @return \GeoIP2\Model\Country
+     * @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.
+     * @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\QutOfQueriesException 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.
      */
     public function country($ipAddress = 'me')
     {
@@ -142,20 +147,31 @@ class Client
     }
 
     /**
-     * This method calls the GeoIP2 Precision City/ISP/Org endpoint.
+     * This method calls the GeoIP2 City/ISP/Org 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\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.
+     * @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\QutOfQueriesException 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.
      */
     public function cityIspOrg($ipAddress = 'me')
     {
@@ -163,20 +179,31 @@ class Client
     }
 
     /**
-     * This method calls the GeoIP2 Precision Omni endpoint.
+     * This method calls the GeoIP2 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\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.
+     * @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\QutOfQueriesException 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.
      */
     public function omni($ipAddress = 'me')
     {
@@ -191,11 +218,8 @@ class Client
             $this->guzzleClient : new GuzzleClient();
         $request = $client->get($uri, array('Accept' => 'application/json'));
         $request->setAuth($this->userId, $this->licenseKey);
-        $ua = $request->getHeader('User-Agent');
-        $ua = "GeoIP2 PHP API ($ua)";
-        $request->setHeader('User-Agent', $ua);
+        $this->setUserAgent($request);
 
-        $response = null;
         try {
             $response = $request->send();
         } catch (ClientErrorResponseException $e) {
@@ -206,7 +230,7 @@ class Client
 
         if ($response && $response->isSuccessful()) {
             $body = $this->handleSuccess($response, $uri);
-            $class = "GeoIP2\\Model\\" . $class;
+            $class = "GeoIp2\\Model\\" . $class;
             return new $class($body, $this->languages);
         } else {
             $this->handleNon200($response, $uri);
@@ -216,7 +240,7 @@ class Client
     private function handleSuccess($response, $uri)
     {
         if ($response->getContentLength() == 0) {
-            throw new GenericException(
+            throw new GeoIp2Exception(
                 "Received a 200 response for $uri but did not " .
                 "receive a HTTP body."
             );
@@ -225,7 +249,7 @@ class Client
         try {
             return $response->json();
         } catch (RuntimeException $e) {
-            throw new GenericException(
+            throw new GeoIp2Exception(
                 "Received a 200 response for $uri but could not decode " .
                 "the response as JSON: " . $e->getMessage()
             );
@@ -244,7 +268,7 @@ class Client
                 try {
                     $body = $response->json();
                     if (!isset($body['code']) || !isset($body['error'])) {
-                        throw new GenericException(
+                        throw new GeoIp2Exception(
                             'Response contains JSON but it does not specify ' .
                             'code or error keys: ' . $response->getBody()
                         );
@@ -273,8 +297,7 @@ class Client
                 $uri
             );
         }
-
-        throw new WebServiceException(
+        $this->handleWebServiceError(
             $body['error'],
             $body['code'],
             $status,
@@ -282,6 +305,28 @@ class Client
         );
     }
 
+    private function handleWebServiceError($message, $code, $status, $uri)
+    {
+        switch ($code) {
+            case 'IP_ADDRESS_NOT_FOUND':
+            case 'IP_ADDRESS_RESERVED':
+                throw new AddressNotFoundException($message);
+            case 'AUTHORIZATION_INVALID':
+            case 'LICENSE_KEY_REQUIRED':
+            case 'USER_ID_REQUIRED':
+                throw new AuthenticationException($message);
+            case 'OUT_OF_QUERIES':
+                throw new OutOfQueriesException($message);
+            default:
+                throw new InvalidRequestException(
+                    $message,
+                    $code,
+                    $status,
+                    $uri
+                );
+        }
+    }
+
     private function handle5xx($response, $uri)
     {
         $status = $response->getStatusCode();
@@ -305,6 +350,13 @@ class Client
         );
     }
 
+    private function setUserAgent($request)
+    {
+        $userAgent = $request->getHeader('User-Agent');
+        $userAgent = "GeoIP2 PHP API ($userAgent)";
+        $request->setHeader('User-Agent', $userAgent);
+    }
+
     private function baseUri()
     {
         return 'https://' . $this->host . '/geoip/v2.0';

tests/GeoIp2/Test/Database/ReaderTest.php

@@ -0,0 +1,80 @@
+<?php
+
+namespace GeoIp2\Test\WebService;
+
+use GeoIp2\Database\Reader;
+
+class ReaderTest extends \PHPUnit_Framework_TestCase
+{
+    public function testDefaultLanguage()
+    {
+        $reader = new Reader('maxmind-db/test-data/GeoIP2-City-Test.mmdb');
+        // Needed for PHP 5.3
+        $that = $this;
+        $this->checkAllMethods(
+            function ($method) use (&$that, &$reader) {
+                $record = $reader->$method('81.2.69.160');
+                $that->assertEquals('United Kingdom', $record->country->name);
+            }
+        );
+        $reader->close();
+    }
+
+    public function testLanguageList()
+    {
+        $reader = new Reader(
+            'maxmind-db/test-data/GeoIP2-City-Test.mmdb',
+            array('xx', 'ru', 'pt-BR', 'es', 'en')
+        );
+        $that = $this;
+        $this->checkAllMethods(
+            function ($method) use (&$that, &$reader) {
+                $record = $reader->$method('81.2.69.160');
+                $that->assertEquals('Великобритания', $record->country->name);
+            }
+        );
+        $reader->close();
+    }
+
+    public function testHasIpAddress()
+    {
+        $reader = new Reader('maxmind-db/test-data/GeoIP2-City-Test.mmdb');
+        $that = $this;
+        $this->checkAllMethods(
+            function ($method) use (&$that, &$reader) {
+                $record = $reader->$method('81.2.69.160');
+                $that->assertEquals('81.2.69.160', $record->traits->ipAddress);
+            }
+        );
+        $reader->close();
+    }
+
+    /**
+     * @expectedException GeoIp2\Exception\AddressNotFoundException
+     * @expectedExceptionMessage The address 10.10.10.10 is not in the database.
+     */
+    public function testUnknownAddress()
+    {
+        $reader = new Reader('maxmind-db/test-data/GeoIP2-City-Test.mmdb');
+        $reader->city('10.10.10.10');
+        $reader->close();
+    }
+
+    /**
+     * @expectedException InvalidArgumentException
+     * @expectedExceptionMessage invalid is not a valid IP address
+     */
+    public function testInvalidAddress()
+    {
+        $reader = new Reader('maxmind-db/test-data/GeoIP2-City-Test.mmdb');
+        $reader->city('invalid');
+        $reader->close();
+    }
+
+    public function checkAllMethods($testCb)
+    {
+        foreach (array('city', 'cityIspOrg', 'country', 'omni') as $method) {
+            $testCb($method);
+        }
+    }
+}

tests/GeoIp2/Test/Model/CountryTest.php

@@ -1,15 +1,15 @@
 <?php
 
-namespace GeoIP2\Test\Model;
+namespace GeoIp2\Test\Model;
 
-use GeoIP2\Model\Country;
+use GeoIp2\Model\Country;
 
 class CountryTest extends \PHPUnit_Framework_TestCase
 {
 
     private $raw = array(
         'continent' => array(
-            'continent_code' => 'NA',
+            'code'       => 'NA',
             'geoname_id' => 42,
             'names'      => array( 'en' => 'North America' ),
         ),
@@ -38,28 +38,28 @@ class CountryTest extends \PHPUnit_Framework_TestCase
     public function testObjects ()
     {
         $this->assertInstanceOf(
-            'GeoIP2\Model\Country',
+            'GeoIp2\Model\Country',
             $this->model,
-            'minimal GeoIP2::Model::Country object'
+            'minimal GeoIp2::Model::Country object'
         );
         $this->assertInstanceOf(
-            'GeoIP2\Record\Continent',
+            'GeoIp2\Record\Continent',
             $this->model->continent
         );
         $this->assertInstanceOf(
-            'GeoIP2\Record\Country',
+            'GeoIp2\Record\Country',
             $this->model->country
         );
         $this->assertInstanceOf(
-            'GeoIP2\Record\Country',
+            'GeoIp2\Record\Country',
             $this->model->registeredCountry
         );
         $this->assertInstanceOf(
-            'GeoIP2\Record\RepresentedCountry',
+            'GeoIp2\Record\RepresentedCountry',
             $this->model->representedCountry
         );
         $this->assertInstanceOf(
-            'GeoIP2\Record\Traits',
+            'GeoIp2\Record\Traits',
             $this->model->traits
         );
     }
@@ -75,8 +75,8 @@ class CountryTest extends \PHPUnit_Framework_TestCase
 
         $this->assertEquals(
             'NA',
-            $this->model->continent->continentCode,
-            'continent continent_code is NA'
+            $this->model->continent->code,
+            'continent code is NA'
         );
 
         $this->assertEquals(

tests/GeoIp2/Test/Model/NameTest.php

@@ -1,14 +1,14 @@
 <?php
 
-namespace GeoIP2\Test\Model;
+namespace GeoIp2\Test\Model;
 
-use GeoIP2\Model\Country;
+use GeoIp2\Model\Country;
 
 class NameTest extends \PHPUnit_Framework_TestCase
 {
     public $raw = array(
             'continent' => array(
-                'continent_code' => 'NA',
+                'code'       => 'NA',
                 'geoname_id' => 42,
                 'names'      => array(
                     'en'    => 'North America',
@@ -46,7 +46,8 @@ class NameTest extends \PHPUnit_Framework_TestCase
         );
     }
 
-    public function testTwoFallbacks() {
+    public function testTwoFallbacks()
+    {
         $model = new Country($this->raw, array('ru', 'ja'));
 
         $this->assertEquals(

tests/GeoIp2/Test/Model/OmniTest.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace GeoIP2\Test\Model;
+namespace GeoIp2\Test\Model;
 
-use GeoIP2\Model\Omni;
+use GeoIp2\Model\Omni;
 
 class OmniTest extends \PHPUnit_Framework_TestCase
 {
@@ -17,7 +17,7 @@ class OmniTest extends \PHPUnit_Framework_TestCase
                 'names'      => array( 'en' => 'Minneapolis' ),
             ),
             'continent' => array(
-                'continent_code' => 'NA',
+                'code'       => 'NA',
                 'geoname_id' => 42,
                 'names'      => array( 'en' => 'North America' ),
             ),
@@ -36,6 +36,9 @@ class OmniTest extends \PHPUnit_Framework_TestCase
                 'postal_confidence' => 33,
                 'time_zone'         => 'America/Chicago',
             ),
+            'maxmind' => array(
+                'queries_remaining' => 22,
+            ),
             'registered_country' => array(
                 'geoname_id' => 2,
                 'iso_code'   => 'CA',
@@ -69,64 +72,70 @@ class OmniTest extends \PHPUnit_Framework_TestCase
         $model = new Omni($raw, array('en'));
 
         $this->assertInstanceOf(
-            'GeoIP2\Model\Omni',
+            'GeoIp2\Model\Omni',
             $model,
-            'GeoIP2\Model\Omni object'
+            'GeoIp2\Model\Omni object'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\City',
+            'GeoIp2\Record\City',
             $model->city,
             '$model->city'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Continent',
+            'GeoIp2\Record\Continent',
             $model->continent,
             '$model->continent'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Country',
+            'GeoIp2\Record\Country',
             $model->country,
             '$model->country'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Location',
+            'GeoIp2\Record\Location',
             $model->location,
             '$model->location'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Country',
+            'GeoIp2\Record\Country',
             $model->registeredCountry,
             '$model->registeredCountry'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\RepresentedCountry',
+            'GeoIp2\Record\RepresentedCountry',
             $model->representedCountry,
             '$model->representedCountry'
         );
 
         $subdivisions = $model->subdivisions;
         foreach ($subdivisions as $subdiv) {
-            $this->assertInstanceOf('GeoIP2\Record\Subdivision', $subdiv);
+            $this->assertInstanceOf('GeoIp2\Record\Subdivision', $subdiv);
         }
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Subdivision',
+            'GeoIp2\Record\Subdivision',
             $model->mostSpecificSubdivision,
             '$model->mostSpecificSubdivision'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Traits',
+            'GeoIp2\Record\Traits',
             $model->traits,
             '$model->traits'
         );
 
+        $this->assertEquals(
+            22,
+            $model->maxmind->queriesRemaining,
+            'queriesRemaining is correct'
+        );
+
         $this->assertEquals(
             $raw,
             $model->raw,
@@ -141,43 +150,43 @@ class OmniTest extends \PHPUnit_Framework_TestCase
         $model = new Omni($raw, array('en'));
 
         $this->assertInstanceOf(
-            'GeoIP2\Model\Omni',
+            'GeoIp2\Model\Omni',
             $model,
-            'GeoIP2\Model\Omni object with no data except traits.ipAddress'
+            'GeoIp2\Model\Omni object with no data except traits.ipAddress'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\City',
+            'GeoIp2\Record\City',
             $model->city,
             '$model->city'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Continent',
+            'GeoIp2\Record\Continent',
             $model->continent,
             '$model->continent'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Country',
+            'GeoIp2\Record\Country',
             $model->country,
             '$model->country'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Location',
+            'GeoIp2\Record\Location',
             $model->location,
             '$model->location'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Country',
+            'GeoIp2\Record\Country',
             $model->registeredCountry,
             '$model->registeredCountry'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\RepresentedCountry',
+            'GeoIp2\Record\RepresentedCountry',
             $model->representedCountry,
             '$model->representedCountry'
         );
@@ -189,13 +198,13 @@ class OmniTest extends \PHPUnit_Framework_TestCase
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Subdivision',
+            'GeoIp2\Record\Subdivision',
             $model->mostSpecificSubdivision,
             '$model->mostSpecificSubdivision'
         );
 
         $this->assertInstanceOf(
-            'GeoIP2\Record\Traits',
+            'GeoIp2\Record\Traits',
             $model->traits,
             '$model->traits'
         );
@@ -225,7 +234,7 @@ class OmniTest extends \PHPUnit_Framework_TestCase
         $model = new Omni($raw, array('en'));
 
         $this->assertInstanceOf(
-            'GeoIP2\Model\Omni',
+            'GeoIp2\Model\Omni',
             $model,
             'no exception when Omni model gets raw data with unknown keys'
         );

tests/GeoIp2/Test/WebService/ClientTest.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace GeoIP2\Test\WebService;
+namespace GeoIp2\Test\WebService;
 
-use GeoIP2\WebService\Client;
+use GeoIp2\WebService\Client;
 use Guzzle\Http\Client as GuzzleClient;
 use Guzzle\Http\Message\Response;
 use Guzzle\Plugin\Mock\MockPlugin;
@@ -13,7 +13,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
     private $country
         = array(
             'continent' => array(
-                'continent_code' => 'NA',
+                'code'       => 'NA',
                 'geoname_id' => 42,
                 'names'      => array( 'en' => 'North America' ),
             ),
@@ -22,6 +22,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
                 'iso_code'   => 'US',
                 'names'      => array( 'en' => 'United States of America' ),
             ),
+            'maxmind' => array('queries_remaining' => 11),
             'traits' => array(
                 'ip_address' => '1.2.3.4',
             ),
@@ -81,6 +82,54 @@ class ClientTest extends \PHPUnit_Framework_TestCase
                 null,
                 'text/plain'
             ),
+            '1.2.3.13'=> $this->response(
+                'error',
+                404,
+                array(
+                    'code'  => 'IP_ADDRESS_NOT_FOUND',
+                    'error' => 'The address "1.2.3.13" is not in our database.'
+                )
+            ),
+            '1.2.3.14'=> $this->response(
+                'error',
+                400,
+                array(
+                    'code'  => 'IP_ADDRESS_RESERVED',
+                    'error' => 'The address "1.2.3.14" is a private address.'
+                )
+            ),
+            '1.2.3.15'=> $this->response(
+                'error',
+                401,
+                array(
+                    'code'  => 'AUTHORIZATION_INVALID',
+                    'error' => 'A user ID and license key are required to use this service'
+                )
+            ),
+            '1.2.3.16'=> $this->response(
+                'error',
+                401,
+                array(
+                    'code'  => 'LICENSE_KEY_REQUIRED',
+                    'error' => 'A license key is required to use this service'
+                )
+            ),
+            '1.2.3.17'=> $this->response(
+                'error',
+                401,
+                array(
+                    'code'  => 'USER_ID_REQUIRED',
+                    'error' => 'A user ID is required to use this service'
+                )
+            ),
+            '1.2.3.18'=> $this->response(
+                'error',
+                402,
+                array(
+                    'code'  => 'OUT_OF_QUERIES',
+                    'error' => 'The license key you have provided is out of queries.'
+                )
+            ),
         );
         return $responses[$ip];
     }
@@ -90,7 +139,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
         $country = $this->client($this->getResponse('1.2.3.4'))
             ->country('1.2.3.4');
 
-        $this->assertInstanceOf('GeoIP2\Model\Country', $country);
+        $this->assertInstanceOf('GeoIp2\Model\Country', $country);
 
         $this->assertEquals(
             42,
@@ -100,8 +149,8 @@ class ClientTest extends \PHPUnit_Framework_TestCase
 
         $this->assertEquals(
             'NA',
-            $country->continent->continentCode,
-            'continent continent_code is NA'
+            $country->continent->code,
+            'continent code is NA'
         );
 
         $this->assertEquals(
@@ -139,6 +188,36 @@ class ClientTest extends \PHPUnit_Framework_TestCase
             $country->country->name,
             'country name is United States of America'
         );
+
+        $this->assertEquals(
+            11,
+            $country->maxmind->queriesRemaining,
+            'queriesRemaining is correct'
+        );
+
+    }
+
+
+    public function testOmni()
+    {
+        $omni = $this->client($this->getResponse('1.2.3.4'))
+            ->omni('1.2.3.4');
+
+        $this->assertInstanceOf('GeoIp2\Model\Omni', $omni);
+
+        $this->assertEquals(
+            42,
+            $omni->continent->geonameId,
+            'continent geoname_id is 42'
+        );
+    }
+
+    public function testCity()
+    {
+        $city = $this->client($this->getResponse('1.2.3.4'))
+            ->city('1.2.3.4');
+
+        $this->assertInstanceOf('GeoIp2\Model\City', $city);
     }
 
     public function testMe()
@@ -146,14 +225,14 @@ class ClientTest extends \PHPUnit_Framework_TestCase
         $client = $this->client($this->getResponse('me'));
 
         $this->assertInstanceOf(
-            'GeoIP2\Model\CityIspOrg',
+            'GeoIp2\Model\CityIspOrg',
             $client->cityIspOrg('me'),
             'can set ip parameter to me'
         );
     }
 
     /**
-     * @expectedException GeoIP2\Exception\GenericException
+     * @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.
      */
     public function testNoBodyException()
@@ -164,7 +243,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
     }
 
     /**
-     * @expectedException GeoIP2\Exception\GenericException
+     * @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:
      */
     public function testBadBodyException()
@@ -176,7 +255,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
 
 
     /**
-     * @expectedException GeoIP2\Exception\WebServiceException
+     * @expectedException GeoIp2\Exception\InvalidRequestException
      * @expectedExceptionCode 400
      * @expectedExceptionMessage The value "1.2.3" is not a valid ip address
      */
@@ -185,11 +264,10 @@ class ClientTest extends \PHPUnit_Framework_TestCase
         $client = $this->client($this->getResponse('1.2.3.6'));
 
         $client->country('1.2.3.6');
-
     }
 
     /**
-     * @expectedException GeoIP2\Exception\HttpException
+     * @expectedException GeoIp2\Exception\HttpException
      * @expectedExceptionCode 400
      * @expectedExceptionMessage with no body
      */
@@ -201,7 +279,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
     }
 
     /**
-     * @expectedException GeoIP2\Exception\GenericException
+     * @expectedException GeoIp2\Exception\GeoIp2Exception
      * @expectedExceptionMessage Response contains JSON but it does not specify code or error keys
      */
     public function testWeirdErrorBodyIPException()
@@ -213,7 +291,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
     }
 
     /**
-     * @expectedException GeoIP2\Exception\HttpException
+     * @expectedException GeoIp2\Exception\HttpException
      * @expectedExceptionCode 400
      * @expectedExceptionMessage did not include the expected JSON body
      */
@@ -226,7 +304,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
     }
 
     /**
-     * @expectedException GeoIP2\Exception\HttpException
+     * @expectedException GeoIp2\Exception\HttpException
      * @expectedExceptionCode 500
      * @expectedExceptionMessage Received a server error (500)
      */
@@ -239,7 +317,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
     }
 
     /**
-     * @expectedException GeoIP2\Exception\HttpException
+     * @expectedException GeoIp2\Exception\HttpException
      * @expectedExceptionCode 300
      * @expectedExceptionMessage Received a very surprising HTTP status (300)
      */
@@ -252,7 +330,7 @@ class ClientTest extends \PHPUnit_Framework_TestCase
     }
 
     /**
-     * @expectedException GeoIP2\Exception\HttpException
+     * @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
      */
@@ -262,6 +340,72 @@ class ClientTest extends \PHPUnit_Framework_TestCase
         $client->country('1.2.3.12');
     }
 
+    /**
+     * @expectedException GeoIp2\Exception\AddressNotFoundException
+     * @expectedExceptionMessage The address "1.2.3.13" is not in our database.
+     */
+    public function testAddressNotFoundException()
+    {
+        $client = $this->client($this->getResponse('1.2.3.13'));
+
+        $client->country('1.2.3.13');
+    }
+
+    /**
+     * @expectedException GeoIp2\Exception\AddressNotFoundException
+     * @expectedExceptionMessage The address "1.2.3.14" is a private address.
+     */
+    public function testAddressReservedException()
+    {
+        $client = $this->client($this->getResponse('1.2.3.14'));
+
+        $client->country('1.2.3.14');
+    }
+
+    /**
+     * @expectedException GeoIp2\Exception\AuthenticationException
+     * @expectedExceptionMessage A user ID and license key are required to use this service
+     */
+    public function testAuthorizationException()
+    {
+        $client = $this->client($this->getResponse('1.2.3.15'));
+
+        $client->country('1.2.3.15');
+    }
+
+    /**
+     * @expectedException GeoIp2\Exception\AuthenticationException
+     * @expectedExceptionMessage A license key is required to use this service
+     */
+    public function testMissingLicenseKeyException()
+    {
+        $client = $this->client($this->getResponse('1.2.3.16'));
+
+        $client->country('1.2.3.16');
+    }
+
+    /**
+     * @expectedException GeoIp2\Exception\AuthenticationException
+     * @expectedExceptionMessage A user ID is required to use this service
+     */
+    public function testMissingUserIdException()
+    {
+        $client = $this->client($this->getResponse('1.2.3.17'));
+
+        $client->country('1.2.3.17');
+    }
+
+    /**
+     * @expectedException GeoIp2\Exception\OutOfQueriesException
+     * @expectedExceptionMessage The license key you have provided is out of queries.
+     */
+    public function testOutOfQueriesException()
+    {
+        $client = $this->client($this->getResponse('1.2.3.18'));
+
+        $client->country('1.2.3.18');
+    }
+
     public function testParams()
     {
         $plugin = new MockPlugin();

tests/bootstrap.php

@@ -4,4 +4,4 @@ if (!$loader = @include __DIR__.'/../vendor/autoload.php') {
     die('Project dependencies missing');
 }
 
-$loader->add('GeoIP2\Test', __DIR__);
+$loader->add('GeoIp2\Test', __DIR__);