Cleaned up old 'geoplugin' references. Thoroughly updated README. Pre…

…pped for release.

CHANGELOG.md

@@ -1,11 +1,5 @@
-# v1.0.1
-##  09/04/2016
-
-1. [](#improved)
-    * Moved to the built-in fetch and cache utilities, saving on API calls
-
 # v1.0.0
-##  09/03/2016
+##  09/05/2016
 
 1. [](#new)
     * ChangeLog started...

README.md

@@ -1,48 +1,101 @@
-# Geoplugin Plugin
+# IPLocate Plugin
 
-The **Geoplugin** Plugin is for [Grav CMS](http://github.com/getgrav/grav). It attempts to geolocate your visitor using [the geoPlugin service](http://www.geoplugin.com).
+The **IPLocate** Plugin is for [Grav CMS](http://github.com/getgrav/grav). It attempts to geolocate your visitor using various services. 
 
-> Remember that it is very easy to spoof your IP address! All this plugin does is return the data from [the geoPlugin service](http://www.geoplugin.com).
+> Remember that it is very easy to spoof your IP address! All this plugin does is return the data from the service.
 
 ## Installation
 
-Installing the Geoplugin plugin can be done in one of two ways. The GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.
+Installing the IPLocate plugin can be done in one of two ways. The GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.
 
 ### GPM Installation (Preferred)
 
 The simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm) through your system's terminal (also called the command line).  From the root of your Grav install type:
 
-    bin/gpm install geoplugin
+    bin/gpm install iplocate
 
-This will install the Geoplugin plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/geoplugin`.
+This will install the IPLocate plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/iplocate`.
 
 ### Manual Installation
 
-To install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `geoplugin`. You can find these files on [GitHub](https://github.com/Perlkonig/grav-plugin-geoplugin) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
+To install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `iplocate`. You can find these files on [GitHub](https://github.com/Perlkonig/grav-plugin-iplocate) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
 
 You should now have all the plugin files under
 
-    /your/site/grav/user/plugins/geoplugin
+    /your/site/grav/user/plugins/iplocate
 
 > NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav) and the [Error](https://github.com/getgrav/grav-plugin-error) and [Problems](https://github.com/getgrav/grav-plugin-problems) to operate.
 
-## Usage
+## Services
+
+The plugin currently supports the following geolocation services (in alphabetical order):
+
+| Name | Code | Key Required? | 
+| --- | --- | --- |
+| [DB-IP](https://www.db-ip.com) | `dbip` | Y (free) |
+| [FreeGeoIP](https://freegeoip.net) | `freegeoip` | N |
+| [geoPlugin](http://www.geoplugin.com/) | `geoplugin` | N |
+| [IPInfo](http://ipinfo.io) | `ipinfo` | N |
+
+Visit the individual websites for more information on what exact data they provide and what limitations exist.
+
+>> NOTE: Some services have licensing terms that involve linking back to the service. This plugin does **not** do this! It is the user's responsibility to ensure that all licensing conditions are met.
+
+If you wish me to add new services, please submit an issue containing a link or description of the API and I am happy to add it.
+
+## Configuration
 
-As long as the plugin is `enabled`, it will inject the following settings:
+Here's the default configuration. To override, first copy `iplocate.yaml` from the `plugins/iplocate` folder to your `config/plugins` folder.
 
 ```
-plugins.geoplugin.city
-plugins.geoplugin.region
-plugins.geoplugin.areaCode
-plugins.geoplugin.dmaCode
-plugins.geoplugin.countryName
-plugins.geoplugin.countryCode
-plugins.geoplugin.longitude
-plugins.geoplugin.latitude
+enabled: true
+sequence:
+  - geoplugin
+  - freegeoip
+  - ipinfo
+  - dbip # API key required
+
+keys:
+  dbip: "FAKEKEY"
 ```
 
-[Please visit the geoPlugin site for more information.](http://www.geoplugin.com)
+  - `enabled` is used to enable/disable the plugin. There is no way to selectively enable this plugin. Either it is on or off.
+
+  - `sequence` tells the system in what order to try the various services. You do not need to include them all in this list. If you only wish to rely on one or two, then only list those. The system will stop going through the list once it receives a valid response.
+
+  - `keys` is where you'll list your API keys.
+
+## Usage
+
+All you have to do is make sure the plugin is `enabled`. The system will then use the `sequence` list and the cache to get what data it can. Any data found will be injected into the system config in the `plugins.iplocate` namespace. Below is the list of available field names:
+
+- areaCode
+- city
+- continentCode
+- continentName
+- countryCode
+- countryName
+- currencyCode
+- district
+- dmaCode
+- geonameID
+- gmtOffset
+- isp
+- languages
+- latitude
+- longitude
+- metroCode
+- organization
+- regionCode
+- regionName
+- stateProv
+- timezone
+- zipcode
+
+The plugin does not guarantee that any one of these fields will be populated. That depends on the service provider. I have, though, attempted to normalize the data as much as is reasonable. The `countryCode`, for example, is always upper case
 
 ## Performance
 
-This plugin uses Grav's built-in caching API, so only one external API call should ever be made for a given IP address unless you clear the cache.
+The system stops processing the `sequence` list once any one of the services returns a valid response. Also, this plugin uses Grav's built-in caching API, so only one external API call should ever be made for a given service + IP address combination unless you clear the cache. 
+
+Note, though, that these are still external calls! If one is slow to respond, it could slow down rendering your site as well. Caveat emptor!

blueprints.yaml

@@ -1,14 +1,14 @@
-name: Geoplugin
-version: 1.0.1
-description: Geo locates your visitor using GeoPlugin.com
+name: IPLocate
+version: 1.0.0
+description: Attempts to geolocate your visitor using various services
 icon: globe
 author:
   name: Aaron Dalton
   email: [email protected]
-homepage: https://github.com/Perlkonig/grav-plugin-geoplugin
+homepage: https://github.com/Perlkonig/grav-plugin-iplocate
 keywords: grav, plugin, geoip, geolocation, location
-bugs: https://github.com/Perlkonig/grav-plugin-geoplugin/issues
-readme: https://github.com/Perlkonig/grav-plugin-geoplugin/blob/master/README.md
+bugs: https://github.com/Perlkonig/grav-plugin-iplocate/issues
+readme: https://github.com/Perlkonig/grav-plugin-iplocate/blob/master/README.md
 license: MIT
 
 form:

classes/dbip.class.php

@@ -36,7 +36,7 @@ function DBIP() {
 
 	function locate($cache, $key, $ip, $lang = "en-US") {
 
-		$data = $cache->fetch('geoplugin.dbip.'.$ip);
+		$data = $cache->fetch('iplocate.dbip.'.$ip);
 		if (! $data) {
 			$host = str_replace( '{IP}', $ip, $this->host );
 			$host = str_replace( '{KEY}', $key, $host );
@@ -45,7 +45,7 @@ function locate($cache, $key, $ip, $lang = "en-US") {
 			if (array_key_exists('error', $data)) {
 				throw new \RuntimeException("Error communicating with DB-IP server. Server said '".$data['error']."'.");
 			}
-			$cache->save('geoplugin.dbip.'.$ip, $data);
+			$cache->save('iplocate.dbip.'.$ip, $data);
 		}
 
 		//set the DBIP vars

classes/freegeoip.class.php

@@ -28,12 +28,12 @@ function freeGeoIP() {
 
 	function locate($cache, $ip) {
 
-		$data = $cache->fetch('geoplugin.freegeoip.'.$ip);
+		$data = $cache->fetch('iplocate.freegeoip.'.$ip);
 		if (! $data) {
 			$host = str_replace( '{IP}', $ip, $this->host );
 			$response = Response::get($host);
 			$data = json_decode($response, true);
-			$cache->save('geoplugin.freegeoip.'.$ip, $data);
+			$cache->save('iplocate.freegeoip.'.$ip, $data);
 		}
 
 		//set the freeGeoIP vars

classes/geoplugin.class.php

@@ -64,14 +64,14 @@ function geoPlugin() {
 
 	function locate($cache, $ip) {
 
-		$data = $cache->fetch('geoplugin.geoplugin.'.$ip);
+		$data = $cache->fetch('iplocate.geoplugin.'.$ip);
 		if (! $data) {
 			$host = str_replace( '{IP}', $ip, $this->host );
 			$host = str_replace( '{CURRENCY}', $this->currency, $host );
 			$response = Response::get($host);
 			$data = array();
 			$data = unserialize($response);
-			$cache->save('geoplugin.geoplugin.'.$ip, $data);
+			$cache->save('iplocate.geoplugin.'.$ip, $data);
 		}
 
 		//set the geoPlugin vars

classes/ipinfo.class.php

@@ -24,7 +24,7 @@ function IPInfo() {
 
 	function locate($cache, $ip) {
 
-		$data = $cache->fetch('geoplugin.ipinfo.'.$ip);
+		$data = $cache->fetch('iplocate.ipinfo.'.$ip);
 		if (! $data) {
 			$options = [
 				'curl' => [
@@ -39,7 +39,7 @@ function locate($cache, $ip) {
 			$response = Response::get($host, $options);
 			//dump($response);
 			$data = json_decode($response, true);
-			$cache->save('geoplugin.ipinfo.'.$ip, $data);
+			$cache->save('iplocate.ipinfo.'.$ip, $data);
 		}
 
 		//set the IPInfo vars