Updated alpha note

.gitignore

@@ -1,4 +1,5 @@
-bin/
+_site
+.gh-pages
 composer.lock
 composer.phar
 phpunit.xml

.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,6 +1,16 @@
 CHANGELOG
 =========
 
+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)
 ------------------
 

README.md

@@ -1,15 +1,19 @@
 # GeoIP2 PHP API #
 
+**NOTE**: This is an alpha release. The API may change before the final
+production release. The first production release will have the version
+number 2.0.0.
+
 ## Description ##
 
-Currently, this distribution provides an API for the GeoIP2 web services
+Currently, this distribution provides an API for the [GeoIP2 web services]
- (as documented at http://dev.maxmind.com/geoip/geoip2/web-services).
+(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
+See ``GeoIP2\WebService\Client`` for details on the web service client
 API.
 
 ## Installation ##
@@ -78,8 +82,8 @@ echo $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
+the
-docs.
+[GeoIP2 web service docs](http://dev.maxmind.com/geoip2/geoip/web-service).
 
 If the web service returns an explicit error document, this is thrown as a
 ```\GeoIP2\Exception\WebServiceException```. If some other sort of transport
@@ -93,7 +97,7 @@ 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```.
+throws a ```\GeoIP2\Exception\GeoIP2Exception```.
 
 ## What data is returned? ##
 
@@ -105,8 +109,9 @@ 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
+See the
-each end point may return.
+[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.
@@ -132,11 +137,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
+please
-http://www.maxmind.com/en/correction.
+[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 +149,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
+a correction, please
-http://www.maxmind.com/en/support for help.
+[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
+Please report all issues with this code using the
-at https://github.com/maxmind/GeoIP2-php/issues
+[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
+to the client API, please see
-details.
+[our support page](http://www.maxmind.com/en/support).
 
 ## Requirements  ##
 
@@ -172,10 +177,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 $TAG
+git push
+git push --tags

composer.json

@@ -17,7 +17,8 @@
         "php": ">=5.3.1"
     },
     "require-dev": {
-        "phpunit/phpunit": "3.7.*"
+        "phpunit/phpunit": "3.7.*",
+        "satooshi/php-coveralls": "dev-master"
     },
     "autoload": {
         "psr-0": { "GeoIP2": "src/" }

phpunit.xml.dist

@@ -12,4 +12,9 @@
             <directory suffix=".php">./src/GeoIP2/</directory>
         </whitelist>
     </filter>
+
+    <logging>
+        <log type="coverage-clover" target="build/logs/clover.xml"/>
+    </logging>
+
 </phpunit>

src/GeoIP2/Exception/GeoIP2Exception.php

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

src/GeoIP2/Exception/HttpException.php

@@ -6,7 +6,7 @@ namespace GeoIP2\Exception;
  *  This class represents an HTTP transport error.
  */
 
-class HttpException extends GenericException
+class HttpException extends GeoIP2Exception
 {
     /**
      * The URI queried

src/GeoIP2/Exception/WebServiceException.php

@@ -3,7 +3,7 @@
 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

src/GeoIP2/Model/City.php

@@ -3,14 +3,14 @@
 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
@@ -23,6 +23,9 @@ namespace GeoIP2\Model;
  * @property \GeoIP2\Record\Location $location Location data for the
  * requested IP address.
  *
+ * @property \GeoIP2\Record\MaxMind $maxmind Data related to your MaxMind
+ * account.
+ *
  * @property \GeoIP2\Record\Country $registeredCountry Registered country
  * data for the requested IP address. This record represents the country
  * where the ISP has registered a given IP block in and may differ from the

src/GeoIP2/Model/CityIspOrg.php

@@ -3,14 +3,14 @@
 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
@@ -23,6 +23,9 @@ namespace GeoIP2\Model;
  * @property \GeoIP2\Record\Location $location Location data for the
  * requested IP address.
  *
+ * @property \GeoIP2\Record\MaxMind $maxmind Data related to your MaxMind
+ * account.
+ *
  * @property \GeoIP2\Record\Country $registeredCountry Registered country
  * data for the requested IP address. This record represents the country
  * where the ISP has registered a given IP block in and may differ from the

src/GeoIP2/Model/Country.php

@@ -17,6 +17,9 @@ namespace GeoIP2\Model;
  * IP address. This object represents the country where MaxMind believes the
  * end user is located.
  *
+ * @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
@@ -35,6 +38,7 @@ class Country
     private $continent;
     private $country;
     private $languages;
+    private $maxmind;
     private $registeredCountry;
     private $representedCountry;
     private $traits;
@@ -55,6 +59,7 @@ class Country
             $this->get('country'),
             $languages
         );
+        $this->maxmind = new \GeoIP2\Record\MaxMind($this->get('maxmind'));
         $this->registeredCountry = new \GeoIP2\Record\Country(
             $this->get('registered_country'),
             $languages

src/GeoIP2/Model/Omni.php

@@ -3,14 +3,14 @@
 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
@@ -23,6 +23,9 @@ namespace GeoIP2\Model;
  * @property \GeoIP2\Record\Location $location Location data for the
  * requested IP address.
  *
+ * @property \GeoIP2\Record\MaxMind $maxmind Data related to your MaxMind
+ * account.
+ *
  * @property \GeoIP2\Record\Country $registeredCountry Registered country
  * data for the requested IP address. This record represents the country
  * where the ISP has registered a given IP block in and may differ from the

src/GeoIP2/Record/Continent.php

@@ -7,9 +7,8 @@ namespace GeoIP2\Record;
  *
  * This record is returned by all the end points.
  *
- * @property string $continentCode A two character continent code
+ * @property string $code A two character continent code like "NA" (North
- * like "NA" (North America) or "OC" (Oceania). This attribute is returned
+ * America) or "OC" (Oceania). This attribute is returned by all end points.
- * 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/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/Traits.php

@@ -35,6 +35,10 @@ 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 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 the IP address.
  * This attribute is only available from the City/ISP/Org and Omni end
  * points.

src/GeoIP2/WebService/Client.php

@@ -2,7 +2,7 @@
 
 namespace GeoIP2\WebService;
 
-use GeoIP2\Exception\GenericException;
+use GeoIP2\Exception\GeoIP2Exception;
 use GeoIP2\Exception\HttpException;
 use GeoIP2\Exception\WebServiceException;
 use GeoIP2\Model\City;
@@ -15,7 +15,7 @@ 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.
@@ -63,7 +63,7 @@ use Guzzle\Http\Exception\ServerErrorResponseException;
  * 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}.
+ * client throws a {@link \GeoIP2\Exception\GeoIP2Exception}.
  */
 class Client
 {
@@ -100,7 +100,7 @@ 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
@@ -108,7 +108,7 @@ class Client
      *
      * @return \GeoIP2\Model\City
      *
-     * @throws \GeoIP2\Exception\GenericException if there was a generic
+     * @throws \GeoIP2\Exception\GeoIP2Exception if there was a generic
      * error processing your request.
      * @throws \GeoIP2\Exception\HttpException if there was an HTTP transport
      * error.
@@ -129,7 +129,7 @@ class Client
      *
      * @return \GeoIP2\Model\Country
      *
-     * @throws \GeoIP2\Exception\GenericException if there was a generic
+     * @throws \GeoIP2\Exception\GeoIP2Exception if there was a generic
      * error processing your request.
      * @throws \GeoIP2\Exception\HttpException if there was an HTTP transport
      * error.
@@ -142,7 +142,7 @@ 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
@@ -150,7 +150,7 @@ class Client
      *
      * @return \GeoIP2\Model\CityIspOrg
      *
-     * @throws \GeoIP2\Exception\GenericException if there was a generic
+     * @throws \GeoIP2\Exception\GeoIP2Exception if there was a generic
      * error processing your request.
      * @throws \GeoIP2\Exception\HttpException if there was an HTTP transport
      * error.
@@ -163,7 +163,7 @@ 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
@@ -171,7 +171,7 @@ class Client
      *
      * @return \GeoIP2\Model\Omni
      *
-     * @throws \GeoIP2\Exception\GenericException if there was a generic
+     * @throws \GeoIP2\Exception\GeoIP2Exception if there was a generic
      * error processing your request.
      * @throws \GeoIP2\Exception\HttpException if there was an HTTP transport
      * error.
@@ -216,7 +216,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 +225,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 +244,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()
                         );

tests/GeoIP2/Test/Model/CountryTest.php

@@ -9,7 +9,7 @@ class CountryTest extends \PHPUnit_Framework_TestCase
 
     private $raw = array(
         'continent' => array(
-            'continent_code' => 'NA',
+            'code'       => 'NA',
             'geoname_id' => 42,
             'names'      => array( 'en' => 'North America' ),
         ),
@@ -75,8 +75,8 @@ class CountryTest extends \PHPUnit_Framework_TestCase
 
         $this->assertEquals(
             'NA',
-            $this->model->continent->continentCode,
+            $this->model->continent->code,
-            'continent continent_code is NA'
+            'continent code is NA'
         );
 
         $this->assertEquals(

tests/GeoIP2/Test/Model/NameTest.php

@@ -8,7 +8,7 @@ class NameTest extends \PHPUnit_Framework_TestCase
 {
     public $raw = array(
             'continent' => array(
-                'continent_code' => 'NA',
+                'code'       => 'NA',
                 'geoname_id' => 42,
                 'names'      => array(
                     'en'    => 'North America',

tests/GeoIP2/Test/Model/OmniTest.php

@@ -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',
@@ -127,6 +130,12 @@ class OmniTest extends \PHPUnit_Framework_TestCase
             '$model->traits'
         );
 
+        $this->assertEquals(
+            22,
+            $model->maxmind->queriesRemaining,
+            'queriesRemaining is correct'
+        );
+
         $this->assertEquals(
             $raw,
             $model->raw,

tests/GeoIP2/Test/WebService/ClientTest.php

@@ -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',
             ),
@@ -100,8 +101,8 @@ class ClientTest extends \PHPUnit_Framework_TestCase
 
         $this->assertEquals(
             'NA',
-            $country->continent->continentCode,
+            $country->continent->code,
-            'continent continent_code is NA'
+            'continent code is NA'
         );
 
         $this->assertEquals(
@@ -139,6 +140,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()
@@ -153,7 +184,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/1.2.3.5 but did not receive a HTTP body.
      */
     public function testNoBodyException()
@@ -164,7 +195,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()
@@ -201,7 +232,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()