lukeyouell / craft-geocookie
Collect information about a visitor's location based on their IP address and store the information as a cookie.
Installs: 6 246
Dependents: 0
Suggesters: 0
Security: 0
Stars: 13
Watchers: 2
Forks: 13
Open Issues: 11
Type:craft-plugin
Requires
- craftcms/cms: ^3.0.0
README
Geo Cookie plugin for Craft CMS 3.x
Collect information about a visitor's location based on their IP address and store the information as a cookie.
Requirements
This plugin requires Craft CMS 3.0.0 or later.
Installation
To install the plugin, follow these instructions.
-
Open your terminal and go to your Craft project:
cd /path/to/project
-
Then tell Composer to load the plugin:
composer require lukeyouell/craft-geocookie
-
In the Control Panel, go to Settings → Plugins and click the “Install” button for Geo Cookie.
Configuring Geo Cookie
IP Anonymisation
Anonymisation is the process of turning data into a form which does not identify individuals and where identification is not likely to take place. This allows for a much wider use of the information.
You can toggle this on/off in the CP.
API Sources
There are currently 8 different API's to choose from:
- db-ip.com (api key required)
- extreme-ip-lookup.com
- freegeoip.net
- ip-api.com
- ipapi.co (default)
- ipfind.co
- ipinfo.io
- ipvigilante.com
- keycdn.com
API Key
You can supply an API key, should your chosen API source require one.
Request Timeout
You can specify the number of seconds to allow for the request to take place before timing out. The default value is 5 seconds.
Fallback IP Address
This will be used as the fallback ip address, should the plugin fail to source the user's ip address.
Default value is 8.8.8.8
(Google Inc.)
Cookie Name
The default value is geoCookie
although you can change this to whatever you like.
To purge existing cookies simply change the name of the cookie.
Cookie Duration
The user's location is stored in a cookie, you can define the length of time this cookie should exist.
The current options are:
- 1 Hour
- 1 Day
- 1 Week
- 1 Month
- 6 Months
- 1 Year
Using Geo Cookie
Setting the Variable
{% set location = geocookie() %}
The location
variable gives you access to the geolocation data.
Example Usage
JSON Response (ipapi.co)
{ "ip": "8.8.8.8", "city": "Mountain View", "region": "California", "region_code": "CA", "country": "US", "country_name": "United States", "postal": "94035", "latitude": 37.386, "longitude": -122.0838, "timezone": "America/Los_Angeles", "asn": "AS15169", "org": "Google Inc." }
Usage
Caching
If an active cookie matching the cookie name in the settings exists, the plugin will use the location stored within the cookie instead of performing another API request.
To check if a cookie exists simply use location.cached
which will return a boolean true/false response.
Example API Responses
db-ip.com
{ "ipAddress": "8.8.8.8", "continentCode": "NA", "continentName": "North America", "countryCode": "US", "countryName": "United States", "stateProv": "California", "city": "Mountain View" }
extreme-ip-lookup.com
{ "businessName": "", "businessWebsite": "", "city": "Mountain View", "continent": "North America", "country": "United States", "countryCode": "US", "ipName": "google-public-dns-a.google.com", "ipType": "Residential", "isp": "Google", "lat": "37.3860", "lon": "-122.0838", "org": "Google Inc.", "query": "8.8.8.8", "region": "California", "status": "success" }
freegeoip.net
{ "ip": "8.8.8.8", "country_code": "US", "country_name": "United States", "region_code": "", "region_name": "", "city": "", "zip_code": "", "time_zone": "", "latitude": 37.751, "longitude": -97.822, "metro_code": 0 }
ip-api.com
{ "as": "AS15169 Google Inc.", "city": "Mountain View", "country": "United States", "countryCode": "US", "isp": "Google", "lat": 37.4229, "lon": -122.085, "org": "Google", "query": "8.8.8.8", "region": "CA", "regionName": "California", "status": "success", "timezone": "America/Los_Angeles", "zip": "" }
ipapi.co
{ "ip": "8.8.8.8", "city": "Mountain View", "region": "California", "region_code": "CA", "country": "US", "country_name": "United States", "postal": "94035", "latitude": 37.386, "longitude": -122.0838, "timezone": "America/Los_Angeles", "asn": "AS15169", "org": "Google Inc." }
ipfind.co
{ "ip_address": "8.8.8.8", "country": "United States", "country_code": "US", "continent": "North America", "continent_code": "NA", "city": null, "county": null, "region": null, "region_code": null, "timezone": null, "owner": null, "longitude": -97.822, "latitude": 37.751, "currency": "USD", "languages": ["en-US","es-US","haw","fr"] }
ipinfo.io
{ "ip": "8.8.8.8", "hostname": "google-public-dns-a.google.com", "city": "Mountain View", "region": "California", "country": "US", "loc": "37.3860,-122.0840", "org": "AS15169 Google Inc.", "postal": "94035", "phone": "650" }
ipvigilante.com
{ "status": "success", "data": { "ipv4": "8.8.8.8", "continent_name": "North America", "country_name": "United States", "subdivision_1_name": "California", "subdivision_2_name": null, "city_name": "Mountain View", "latitude": "37.38600", "longitude": "-122.08380" } }
keycdn.com
{ "status": "success", "description": "Data successfully received.", "data": { "geo": { "host": "8.8.8.8", "ip": "8.8.8.8", "rdns": "google-public-dns-a.google.com", "asn": "AS15169", "isp": "Google Inc.", "country_name": "United States", "country_code": "US", "region": "", "city": "", "postal_code": "", "continent_code": "NA", "latitude": "37.750999450684", "longitude": "-97.821998596191", "dma_code": "0", "area_code": "0", "timezone": false, "datetime": "na" } } }
Overriding Plugin Settings
If you create a config file in your config
folder called geo-cookie.php
, you can override the plugin’s settings in the Control Panel. Since that config file is fully multi-environment aware, this is a handy way to have different settings across multiple environments.
Here’s what that config file might look like along with a list of all of the possible values you can override.
<?php return [ 'logging' => true, 'anonymisation' => true, 'apiSource' => 'keycdn', 'apiKey' => 'lLyl85arR3nT04T4WDt5AVBJrPTBRjUk', 'requestTimeout' => 4, 'fallbackIp' => '8.8.8.8', 'cookieName' => 'geoCookieName', 'cookieDuration' => 168, ];
Debugging
You can dump the API response:
<pre>{{ location|json_encode(constant('JSON_PRETTY_PRINT')) }}</pre>
Errors are now logged. Simply search your logs for geocookie
.
Geo Cookie Roadmap
Some things to do, and ideas for potential features:
Brought to you by Luke Youell