Merge pull request #128 from maxmind/horgh/phpdoc

Use phpDocumentor2 instead of ApiGen

.gitignore

@@ -3,11 +3,11 @@ _site
 .idea
 .php_cs.cache
 GeoLite2-City.mmdb
-apigen.phar
 box.phar
 build
 composer.lock
 composer.phar
+/phpDocumentor.phar
 phpunit.xml
 geoip2.phar
 geoip2-php.sublime-*

.travis.yml

@@ -10,6 +10,7 @@ matrix:
     - php: '7.0'
     - php: '7.1'
     - php: '7.2'
+    - php: '7.3'
       env:
         - RUN_LINTER=1
         - RUN_SNYK=1

README.md

@@ -3,14 +3,14 @@
 ## Description ##
 
 This package provides an API for the GeoIP2
-[web services](http://dev.maxmind.com/geoip/geoip2/web-services) and
-[databases](http://dev.maxmind.com/geoip/geoip2/downloadable). The API also
+[web services](https://dev.maxmind.com/geoip/geoip2/web-services) and
+[databases](https://dev.maxmind.com/geoip/geoip2/downloadable). The API also
 works with the free
-[GeoLite2 databases](http://dev.maxmind.com/geoip/geoip2/geolite2/).
+[GeoLite2 databases](https://dev.maxmind.com/geoip/geoip2/geolite2/).
 
 ## Install via Composer ##
 
-We recommend installing this package with [Composer](http://getcomposer.org/).
+We recommend installing this package with [Composer](https://getcomposer.org/).
 
 ### Download Composer ###
 
@@ -46,18 +46,18 @@ require 'vendor/autoload.php';
 ## Install via Phar ##
 
 Although we strongly recommend using Composer, we also provide a
-[phar archive](http://php.net/manual/en/book.phar.php) containing most of the
+[phar archive](https://php.net/manual/en/book.phar.php) containing most of the
 dependencies for GeoIP2. Our latest phar archive is available on
 [our releases page](https://github.com/maxmind/GeoIP2-php/releases).
 
 ### Install Dependencies ###
 
 In order to use the phar archive, you must have the PHP
-[Phar extension](http://php.net/manual/en/book.phar.php) installed and
+[Phar extension](https://php.net/manual/en/book.phar.php) installed and
 enabled.
 
 If you will be making web service requests, you must have the PHP
-[cURL extension](http://php.net/manual/en/book.curl.php)
+[cURL extension](https://php.net/manual/en/book.curl.php)
 installed to use this archive. For Debian based distributions, this can
 typically be found in the the `php-curl` package. For other operating
 systems, please consult the relevant documentation. After installing the
@@ -326,15 +326,15 @@ 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 the
-[GeoIP2 Precision web service docs](http://dev.maxmind.com/geoip/geoip2/web-services)
+[GeoIP2 Precision web service docs](https://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.
 
 ## Integration with GeoNames ##
 
-[GeoNames](http://www.geonames.org/) offers web services and downloadable
+[GeoNames](https://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.
@@ -351,10 +351,10 @@ the GeoNames premium data set.
 
 If the problem you find is that an IP address is incorrectly mapped,
 please
-[submit your correction to MaxMind](http://www.maxmind.com/en/correction).
+[submit your correction to MaxMind](https://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](https://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
@@ -363,7 +363,7 @@ releases.
 
 If you are a paying MaxMind customer and you're not sure where to submit
 a correction, please
-[contact MaxMind support](http://www.maxmind.com/en/support) for help.
+[contact MaxMind support](https://www.maxmind.com/en/support) for help.
 
 ## Other Support ##
 
@@ -372,7 +372,7 @@ Please report all issues with this code using the
 
 If you are having an issue with a MaxMind service that is not specific
 to the client API, please see
-[our support page](http://www.maxmind.com/en/support).
+[our support page](https://www.maxmind.com/en/support).
 
 ## Requirements  ##
 
@@ -390,11 +390,10 @@ https://github.com/maxmind/MaxMind-DB
 
 ## Versioning ##
 
-The GeoIP2 PHP API uses [Semantic Versioning](http://semver.org/).
+The GeoIP2 PHP API uses [Semantic Versioning](https://semver.org/).
 
 ## Copyright and License ##
 
-This software is Copyright (c) 2013-2018 by MaxMind, Inc.
+This software is Copyright (c) 2013-2019 by MaxMind, Inc.
 
 This is free software, licensed under the Apache License, Version 2.0.
-

composer.json

@@ -9,7 +9,7 @@
         {
             "name": "Gregory J. Oschwald",
             "email": "goschwald@maxmind.com",
-            "homepage": "http://www.maxmind.com/"
+            "homepage": "https://www.maxmind.com/"
         }
     ],
     "require": {

dev-bin/release.sh

@@ -76,21 +76,21 @@ if [ -n "$(git status --porcelain)" ]; then
     exit 1
 fi
 
-# We no longer have apigen as a dependency in Composer as it pulls in old
-# versions of other libraries, breaking PHP 7.2.
-#
-# Note that the Phar is no longer being updated. We will likely need to go
-# back to a Composer dep or use another generator at some point in the
-# future.
-wget -O apigen.phar "http://apigen.org/apigen.phar"
-
-php apigen.phar generate \
-    -s ../src \
-    -s ../../MaxMind-DB-Reader-php/src \
-    -d "doc/$tag" \
+# Using Composer is possible, but they don't recommend it.
+wget -O phpDocumentor.phar https://github.com/phpDocumentor/phpDocumentor2/releases/download/v2.9.0/phpDocumentor.phar
+
+# Use cache dir in /tmp as otherwise cache files get into the output directory.
+cachedir="/tmp/phpdoc-$$-$RANDOM"
+rm -rf "$cachedir"
+
+php phpDocumentor.phar \
+    -d src,../MaxMind-DB-Reader-php/src \
+    --visibility public \
+    --cache-folder "$cachedir" \
     --title "GeoIP2 PHP API $tag" \
-    --php
+    -t "doc/$tag"
 
+rm -rf "$cachedir"
 
 page=index.md
 cat <<EOF > $page

src/Model/City.php

@@ -7,42 +7,25 @@
  *
  * The only difference between the City and Insights model classes is which
  * fields in each record may be populated. See
- * http://dev.maxmind.com/geoip/geoip2/web-services more details.
+ * https://dev.maxmind.com/geoip/geoip2/web-services for more details.
  *
  * @property-read \GeoIp2\Record\City $city City data for the requested IP
  * address.
- * @property-read \GeoIp2\Record\Continent $continent Continent data for the
- * requested IP address.
- * @property-read \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-read \GeoIp2\Record\Location $location Location data for the
  * requested IP address.
  * @property-read \GeoIp2\Record\Postal $postal Postal data for the
  * requested IP address.
- * @property-read \GeoIp2\Record\MaxMind $maxmind Data related to your MaxMind
- * account.
- * @property-read \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 and may differ from the
- * user's country.
- * @property-read \GeoIp2\Record\RepresentedCountry $representedCountry
- * Represented country data for the requested IP address. The represented
- * country is used for things like military bases. It is only present when
- * the represented country differs from the country.
- * @property-read array $subdivisions An array of {@link \GeoIp2\Record\Subdivision}
+ * @property-read array $subdivisions An array \GeoIp2\Record\Subdivision
  * objects representing the country subdivisions for the requested IP
  * address. The number and type of subdivisions varies by country, but a
  * subdivision is typically a state, province, county, etc. Subdivisions
  * are ordered from most general (largest) to most specific (smallest).
  * If the response did not contain any subdivisions, this method returns
  * an empty array.
- * @property-read \GeoIp2\Record\Subdivision $mostSpecificSubdivision An  object
+ * @property-read \GeoIp2\Record\Subdivision $mostSpecificSubdivision An object
  * representing the most specific subdivision returned. If the response
  * did not contain any subdivisions, this method returns an empty
- * {@link \GeoIp2\Record\Subdivision} object.
- * @property-read \GeoIp2\Record\Traits $traits Data for the traits of the
- * requested IP address.
+ * \GeoIp2\Record\Subdivision object.
  */
 class City extends Country
 {

src/Model/Country.php

@@ -7,7 +7,7 @@
  *
  * The only difference between the City and Insights model classes is which
  * fields in each record may be populated. See
- * http://dev.maxmind.com/geoip/geoip2/web-services more details.
+ * https://dev.maxmind.com/geoip/geoip2/web-services for more details.
  *
  * @property-read \GeoIp2\Record\Continent $continent Continent data for the
  * requested IP address.

src/Model/Enterprise.php

@@ -7,40 +7,7 @@
  *
  * The only difference between the City and Enterprise model classes is which
  * fields in each record may be populated. See
- * http://dev.maxmind.com/geoip/geoip2/web-services more details.
- *
- * @property-read \GeoIp2\Record\City $city City data for the requested IP
- * address.
- * @property-read \GeoIp2\Record\Continent $continent Continent data for the
- * requested IP address.
- * @property-read \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-read \GeoIp2\Record\Location $location Location data for the
- * requested IP address.
- * @property-read \GeoIp2\Record\MaxMind $maxmind Data related to your MaxMind
- * account.
- * @property-read \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 and may differ from the
- * user's country.
- * @property-read \GeoIp2\Record\RepresentedCountry $representedCountry
- * Represented country data for the requested IP address. The represented
- * country is used for things like military bases. It is only present when
- * the represented country differs from the country.
- * @property-read array $subdivisions An array of {@link \GeoIp2\Record\Subdivision}
- * objects representing the country subdivisions for the requested IP
- * address. The number and type of subdivisions varies by country, but a
- * subdivision is typically a state, province, county, etc. Subdivisions
- * are ordered from most general (largest) to most specific (smallest).
- * If the response did not contain any subdivisions, this method returns
- * an empty array.
- * @property-read \GeoIp2\Record\Subdivision $mostSpecificSubdivision An  object
- * representing the most specific subdivision returned. If the response
- * did not contain any subdivisions, this method returns an empty
- * {@link \GeoIp2\Record\Subdivision} object.
- * @property-read \GeoIp2\Record\Traits $traits Data for the traits of the
- * requested IP address.
+ * https://dev.maxmind.com/geoip/geoip2/web-services for more details.
  */
 class Enterprise extends City
 {

src/Model/Insights.php

@@ -7,40 +7,7 @@
  *
  * The only difference between the City and Insights model classes is which
  * fields in each record may be populated. See
- * http://dev.maxmind.com/geoip/geoip2/web-services more details.
- *
- * @property-read \GeoIp2\Record\City $city City data for the requested IP
- * address.
- * @property-read \GeoIp2\Record\Continent $continent Continent data for the
- * requested IP address.
- * @property-read \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-read \GeoIp2\Record\Location $location Location data for the
- * requested IP address.
- * @property-read \GeoIp2\Record\MaxMind $maxmind Data related to your MaxMind
- * account.
- * @property-read \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 and may differ from the
- * user's country.
- * @property-read \GeoIp2\Record\RepresentedCountry $representedCountry
- * Represented country data for the requested IP address. The represented
- * country is used for things like military bases. It is only present when
- * the represented country differs from the country.
- * @property-read array $subdivisions An array of {@link \GeoIp2\Record\Subdivision}
- * objects representing the country subdivisions for the requested IP
- * address. The number and type of subdivisions varies by country, but a
- * subdivision is typically a state, province, county, etc. Subdivisions
- * are ordered from most general (largest) to most specific (smallest).
- * If the response did not contain any subdivisions, this method returns
- * an empty array.
- * @property-read \GeoIp2\Record\Subdivision $mostSpecificSubdivision An  object
- * representing the most specific subdivision returned. If the response
- * did not contain any subdivisions, this method returns an empty
- * {@link \GeoIp2\Record\Subdivision} object.
- * @property-read \GeoIp2\Record\Traits $traits Data for the traits of the
- * requested IP address.
+ * https://dev.maxmind.com/geoip/geoip2/web-services for more details.
  */
 class Insights extends City
 {

src/Record/Country.php

@@ -15,10 +15,9 @@
  * @property-read bool $isInEuropeanUnion This is true if the country is a
  * member state of the European Union. This attribute is returned by all
  * location services and databases.
- * @property-read string|null $isoCode The
- * {@link * http://en.wikipedia.org/wiki/ISO_3166-1 two-character ISO 3166-1 alpha
- * code} for the country. This attribute is returned by all location services
- * and databases.
+ * @property-read string|null $isoCode The two-character ISO 3166-1 alpha code
+ * for the country. See https://en.wikipedia.org/wiki/ISO_3166-1. This
+ * attribute is returned by all location services and databases.
  * @property-read string|null $name The name of the country based on the locales
  * list passed to the constructor. This attribute is returned by all location
  * services and databases.

src/Record/Location.php

@@ -27,11 +27,11 @@
  * from the Insights service.
  * @property-read int|null $metroCode The metro code of the location if the location
  * is in the US. MaxMind returns the same metro codes as the
- * {@link * https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions
- * Google AdWords API}.
+ * Google AdWords API. See
+ * https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions.
  * @property-read string|null $timeZone The time zone associated with location, as
- * specified by the {@link http://www.iana.org/time-zones IANA Time Zone
- * Database}, e.g., "America/New_York".
+ * specified by the IANA Time Zone Database, e.g., "America/New_York". See
+ * https://www.iana.org/time-zones.
  */
 class Location extends AbstractRecord
 {

src/Record/RepresentedCountry.php

@@ -9,19 +9,6 @@
  * for the IP's represented country. The represented country is the country
  * represented by something like a military base.
  *
- * @property-read int|null $confidence A value from 0-100 indicating MaxMind's
- * confidence that the country is correct. This attribute is only available
- * from the Insights service and the GeoIP2 Enterprise database.
- * @property-read int|null $geonameId The GeoName ID for the country.
- * @property-read bool $isInEuropeanUnion This is true if the country is a
- * member state of the European Union. This attribute is returned by all
- * location services and databases.
- * @property-read string|null $isoCode The {@link http://en.wikipedia.org/wiki/ISO_3166-1
- * two-character ISO 3166-1 alpha code} for the country.
- * @property-read string|null $name The name of the country based on the locales list
- * passed to the constructor.
- * @property-read array|null $names An array map where the keys are locale codes and
- * the values are names.
  * @property-read string|null $type A string indicating the type of entity that is
  * representing the country. Currently we only return <code>military</code>
  * but this could expand to include other types in the future.

src/Record/Subdivision.php

@@ -16,9 +16,9 @@
  * This attribute is returned by all location databases and services besides
  * Country.
  * @property-read string|null $isoCode This is a string up to three characters long
- * contain the subdivision portion of the
- * {@link * http://en.wikipedia.org/wiki/ISO_3166-2 ISO 3166-2 code}. This attribute
- * is returned by all location databases and services except Country.
+ * contain the subdivision portion of the ISO 3166-2 code. See
+ * https://en.wikipedia.org/wiki/ISO_3166-2. This attribute is returned by all
+ * location databases and services except Country.
  * @property-read string|null $name The name of the subdivision based on the
  * locales list passed to the constructor. This attribute is returned by all
  * location databases and services besides Country.