WordPress Implementing the GeoIP Functionality Into a WordPress Theme
In this blog post you will see how you how you can easily implement the GeoIP feature into your WordPress site and how you can benefit from it by integrating it into things like page templates, widgets etc. To achieve just that we will first need to install the MaxMind GeoIP2 PHP library into our WordPress site and then we will need to create few custom functions that will make this feature usable within the WordPress theme on which we will work on in this tutorial. So let’s get started.
Installation
There are 2 ways in which you can install the MaxMind GeoIp2 PHP library into your WordPress project so let’s quickly run through them.
#1. Install via Composer
When it comes to the MaxMind GeoIP2 library installation (or any other PHP library installation for that matter), Composer is the way to go. If you don’t know what Composer is, you can learn more about it here.
In order to use Composer, you must first download it. You can download and install Composer into your project or you can install it globally (it’s totally up to you). For the purpose of this blog post we will install it into the project itself and, since we want to implement the GeoIP feature into our theme, we will install the Composer directly into our theme.
To do that, we will need to open up the terminal and navigate to the theme directory of our project. If you are working on a remote server, you will need to gain a SSH access to it. If you cannot obtain a SSH access to the server you can read more info about how to download and install the MaxMind GeoIP2 library via a PHAR archive.
Once we are within the theme directory, we can install the composer by running the following command:
curl -sS https://getcomposer.org/installer | php
If you are working on a Windows machine and the installation process doesn’t work for you, you can manually download the composer.phar archive from the official Composer download page.
After the composer.phar (Composer PHAR archive) gets downloaded into the theme directory we can tell it to require (download) the MaxMind GeoIP2 library. To do that, all we need to do is run the following command
php composer.phar require geoip2/geoip2:~2.0
If you see any errors appear during the package download and installation process, it’s very likely that you are missing one or more installation dependencies. To run the command (and to use the GeoIP library) it’s important to have PHP (version 5.3 or greater) installed alongside with the php5-curl extension. If you are not sure which php extensions are installed on your machine, you can simply run the following command that will list them out for you:
php --ini
After the GeoIP2 package gets downloaded (alongside with all the dependencies that the library relies on) you should see following files and directories show up within the theme directory:
- composer.phar
- composer.json
- composer.lock
- vendor/
If you are using Git you should add both composer.lock and composer.phar files as well as the vendors/ directory into the .gitignore file. Reason for that is the fact that the composer.json file now contains all the dependencies that our theme relies on and next time you clone the project, installation of those dependencies is as simple as running the php composer.phar install command from within the theme directory.
After you’ve installed the GeoIP2 package it’s time for you to include it within the functions.php file. To do that, you will need to include the vendor autoloader within the functions.php file which will autoload the library for you. I highly suggest you add the following line somewhere on the top of the file:
require_once 'vendor/autoload.php';
OPTIONAL
If you wish to replace the vendor/ directory name with something else (for example you might want to use lib/ instead), you can do just that by appending the following declaration to the composer.json file:
"config": {
"vendor-dir": "lib"
}
After that you should update the composer, remove the old vendor directory and update the autoload.php require path. Also, if you are using Git, you should replace the “vendor/” record with the new one which is, in this case at least, “lib/”.
#2. Install via PHAR archive
If you don’t have a SSH access to your server or you are simply not into the whole Composer thing, you can still download the GeoIP2 PHAR archive from the official releases page, place it somewhere within your theme and then include it within the functions.php file.
<?php require 'geoip2.phar'; // function.php code
Be sure that the require path matches the path to the dowloaded/imported PHAR archive file.
Implementation
Once you have the GeoIP2 library installed you can now move on with the theme integration. To do that you will first need to decide which type of information about the visitor do you wish to extract. For the purpose of this tutorial we will extract the visitors country. Keep in mind that this library also allows you to extract things like the name of the city from where the visitor is visiting from, details about their ISP etc. You can read more about those and other types of information that you can extract on the projects official Github page.
Also, you should know that the IP geolocation is not very precise in general so you shouldn’t use it to pin point the visitors location by trying to find out his street address. Nevertheless, IP geolocation is really reliable when trying to find out from which country and sometimes even from which city is the visitor visiting from.
Now, in order to extract the visitors country you will first need to download the MaxMind DB file in which that type of information is stored. Since we want to extract the visitors country we will download the “GeoLite2 Country” database from the following URL:
https://dev.maxmind.com/geoip/geoip2/geolite2/
You could also decide to use the “GeoLite2 City” database instead since city database contains both the country name and the city name from where the visitor is visiting from.
After you’ve downloaded the gzipped database file you should extract it and place the extracted MMDB file somewhere within the theme directory on which you are currently working on. Now let’s try out the GeoIP2 functionality by implementing the following snippet into the functions.php file:
This code snippet will first grab the details about the 78.134.247.178 IP address from within the “GeoLite2-Country.mmdb” database file and will extract the ISO 3166-1 alpha-2 country code ($country_iso_code) as well as the name of the country ($country_name) from which the visitor is visiting from. Then, with the help of the var_dump function, it will display both the country ISO code and country name somewhere at the very top of the <body> tag of the site.
Now let’s reorganize that same code into few small functions that we will then be able to easily use across our WordPress theme. In this process we will create a function that will provide us with a GeoIP2 Reader object, a function that will return visitors real IP address (in the code above we have used the hard-coded one) and a function that will return visitors country ISO code.
All we need to do now is utilize our new get_geoip2_country_code() function. For the purpose of this blog post we will use it to redirect the users from Croatia to a special landing page that we’ve made just for them.
Keep in mind that this code won’t work if you are testing the feature locally since you local sever will use your local IP address instead of the public one. In order to prevent any localhost related issues you will see that we’ve implemented the try-catch block within the get_geoip2_country_code function. That try-catch block will prevent any uncaught exceptions from messing with with the rest of the site and, as a result, your site will display normally even if the library wasn’t able to extract any data for the given IP address. You can always edit the try-catch block to match your own needs, of course.
Conclusion
By making your site IP geolocation aware you are opening your site to much more possibilities than you’ve previously had. For example, if you are running a online store, you can display a notice to the visitors in which you inform them if you are sending shipments to their country or not. You can even use this feature to display prices in different currencies or to show certain stuff only for the visitors from some specific country (or a list of countries). There are really no limitations to what you can do with this feature so we would really like to hear back from you on how you plan to implement this feature into your own site.
Happy coding!
