lukeyouell/craft3-geocookie

Collect information about a visitor's location based on their IP address and store the information as a cookie.

, _(*1)

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., _(*2)

Requirements

This plugin requires Craft CMS 3.0.0 or later., _(*3)

Installation

To install the plugin, follow these instructions., _(*4)

1. Open your terminal and go to your Craft project:, _(*5)

   cd /path/to/project

2. Then tell Composer to load the plugin:, _(*6)

   composer require lukeyouell/craft-geocookie

3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Geo Cookie., _(*7)

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., _(*8)

You can toggle this on/off in the CP., _(*9)

API Sources

There are currently 8 different API's to choose from:, _(*10)

• 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., _(*11)

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., _(*12)

Fallback IP Address

This will be used as the fallback ip address, should the plugin fail to source the user's ip address., _(*13)

Default value is 8.8.8.8 (Google Inc.), _(*14)

Cookie Name

The default value is geoCookie although you can change this to whatever you like., _(*15)

To purge existing cookies simply change the name of the cookie., _(*16)

Cookie Duration

The user's location is stored in a cookie, you can define the length of time this cookie should exist., _(*17)

The current options are:, _(*18)

• 1 Hour
• 1 Day
• 1 Week
• 1 Month
• 6 Months
• 1 Year

Using Geo Cookie

Setting the Variable

{% set location = geocookie() %}, _(*19)

The location variable gives you access to the geolocation data., _(*20)

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., _(*21)

To check if a cookie exists simply use location.cached which will return a boolean true/false response., _(*22)

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., _(*23)

Here’s what that config file might look like along with a list of all of the possible values you can override., _(*24)

<?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:, _(*25)

<pre>{{ location|json_encode(constant('JSON_PRETTY_PRINT')) }}</pre>

Errors are now logged. Simply search your logs for geocookie., _(*26)

Geo Cookie Roadmap

Some things to do, and ideas for potential features:, _(*27)

Brought to you by Luke Youell, _(*28)