In this article:
1. Introduction
2. What the free WPSC Country Caching Extension does
3. Getting and setting-up the plugin
4. Overriding folder used for CC settings (not recommended)
5. How do I know Super Cache is country caching?
6. When do I need to clear cache?
7. GeoLocation, and how to auto-update
8. Resolving problems
9. Auto & Manual Uninstall
10. Warning
1. Introduction:
WP Super Cache (WPSC) improves performance by serving a snapshot (cache) of a previously visited page, making it unnecessary for WordPress to generate a fresh “new” page for every visitor.
This causes the display of wrong content on sites that use country geo-location. This page should display your National flag 
. However, if the page was “first” requested by someone in Samoa, WPSC would, instead, serve you the cached page with the Samoan flag. The Country Caching extension for WPSC solves this problem.
2. What the Country Caching Extension for WPSC does:
- It uses an official documented Super Cache interface to provide a settings file enabling WPSC to cache by page/country instead of just page. You can limit separate caching to specified countries and/or a group of countries e.g. the European Union.
- It provides the GeoIP country look-up (via Cloudflare or Maxmind Geolite2 data) to enable WPSC to determine the visitor’s country. It is also possible to “plug in” an alternative geolocation system
- It ensures that WPSC settings needed for country caching are set. (i.e. that “Cache Delivery Method” is its default and recommended setting; and that “Enable HTTP headers” is on.
3. Installation and set-up of the Country Caching Extension for WPSC
Install in the normal way via “Dashboard->Plugins->Add New” and search for “Country Caching Extension for WPSC“; or download from WordPress.Org.
Simple Setup:
- “Dashboard->Country Caching“. Check the “Enable WPSC” check box, and click save.
Fine Tuning:
By default (when the Country Codes box is empty) ALL countries will be separately cached.
Alternatively, you can allow most visitors to see the same “normal” cached page, and just specify specific countries that should have their own separate cache e.g. specify “FR,CA” if only visitors from France and Canada should see content different to the “normal” page. This results in the generation of less cached pages and is more efficient.
You can also specify a group of countries that will use the same cache file. e.g. If you serve additional content/javascript to visitors from the Europe to comply with EU GDPR cookie laws – but not to visitors from elsewhere; then you could place a list of EU country codes in the group box.
4. Overriding folder used for CC settings (not recommended)
As recommended in Super Cache guidelines; the Country Caching plugin places its settings file in a “permanent” dedicated folder (and tells WPSC where it is located).
DO NOT override use of the dedicated folder, and check the “Use WPSC default folder”, UNLESS you have enabled (unlikely) any of the “add-ons” in WPSC’s own Plugins tab (image below).
As per Super Caches explanation (inage above): If you do enable the “Use WPSC default folder” option then your Country Caching settings file will be deleted whenever you update to a new version of Super Cache. Note: The Country Caching plugin does its best to warn you when this happens and should display a message on your WP dashboard soon after the file has been deleted. The settings file can be recreated by re-saving your Country Caching settings.
5. How do I know WPSC is country caching
- WPSC might NOT cache pages if you are (or have PREVIOUSLY been) logged in.
To test, use a browser that has NEVER been used to log in to your site (if you can’t do this, ensure you are not logged in and cookies are deleted before viewing a page).
To test with WPSC 1.5.4 on:
Visit pages on your site using a couple of Browsers including Opera Developer which has a VPN allowing you to choose and pretend to be a visitor from different countries (note VPNs can be slow to load pages). As at Feb 18 Opera VPN is no longer useful for testing (it may be fixed). Whatever VPN locale you select, the IP is identified as either unknown or “EU” by Cloudflare, Maxmind etc. So, instead visit Locabrowser.com to simulate visiting your site from different countries. Check content is as expected for that country (if not you may need to clear existing WPSC cache).
For each of the countries from which you “visited” a page (that is specified in Country Caching), WPSC will create a cached page (n.b. only ONE cache for unspecified/default countries).
Cached pages are located in directories under “/wp-content/cache/supercache/”. A tiny “meta-head” file that points to the relevant visitor country (or default) cache is also created. If you “open” one of these meta files you will see the relevant 2 character country code at the end of the text”.
>php<{"headers":{"Vary":"Vary: Cookie","Content-Type":"Content-Type: text\/html; charset=UTF-8","Link":"Link: ; rel=shortlink","Last-Modified":"Last-Modified: Tue, 12 Sep 2017 09:42:40 GMT"},"uri":"example.com\/category\/some-post-or-page\/","blog_id":1,"post":1329,"key":"example.com80\/category\/some-post-or-page\/US\/"} N.B. if you have limited separate caching to specific countries and you are not testing with a VPN/anon proxy then ensure your country is in this list during your tests, otherwise you will (correctly) see keys without country suffixes, indicating the normal cache is being used.
You can also test by using Country proxy servers.
6. When do I need to clear cache?
You probably don’t need to delete cache simply because you are using the CC plugin or changing its settings.
If you are only separately caching specific countries then existing “standard” cache will continue to be used/created for all other countries. Unless you have changed your “standard/default” content, deleting cache will be counter-productive (this is also dependent on no changes in behaviour by new versions of WPSC).
If you are separately caching ALL countries then the old “standard” cache won’t be used at all, you don’t need to delete it, but deletion may have a small performance benefit.
7. GeoLocation, and how to auto-update:
If you use Cloudflare and have “switched on” their GeoLocation option ( see Cloudflare’s instructions ) then it will be used to identify visitor country. If not, then the GeoLite2 Country Database (available from Maxmind) will be automatically installed. For techies, it is also possible to plugin your own choice of alternative Geolocation. (Documentation coming soon)
Updating New IP addresses are constantly being allocated to countries, so the installed Maxmind Country/IP data file will become less accurate over time. If you would like to automate update of this file then install and enable the Category Country Aware plugin (on WordPress.Org). Even if you don’t use any of its other features, it will schedule a monthly update of your Maxmind file.
If instead, you wish to manually update the Maxmind file: download “GeoLite2-Country.tar.gz” from Maxmind, extract the file “GeoLite2-Country.mmdb” and upload it to your servers “/wp-content/cca_maxmind_data/” directory.
8. Problems and Issues
Should be posted on its WordPress.org support forum (as at 25 May 18 in over 5 years there have been questions but no problems raised).
If you do experience any problems the plugins “CC Status” tab may provide information useful for support requests or to enable you solve issues yourself.
The most likely problems will probably be due to your server’s permissions. Read Smashing Magazine’s article on WordPress Folder and File security requirements for different servers; and how to change WP Folder and File permissions.
Directory Permissions: Assuming you have a “typical” server, permissions for your WordPress “wp-content/” and “wp-content/ac-plugins/” (if it exists) folders should be set to 755 on a shared server, and 775 on a dedicated server; do NOT use slacker permissions.
Likewise file permissions for “cca_wps_geoip_plugin.php” would typically “644”, or on a dedicated server 664.
9. Auto & Manual Uninstall
You should deactivate (removes the add-on script) and then delete the plugin in the normal manner. Then clear the WPSC cache.
However, just like with Super Cache there may be occasions when the normal method fails to completely uninstall.
Manual removal: log into your site via CPanel, CLI or FTP client; e.g. with CoreFTP or FileZilla; and if they exist:
- Delete this directory and its content: /wp-content/ccwpsc_plugins/ (or any alternative add-on directory you defined yourself by editing wp-cache-config.php)
- Delete this file: “cca_wpsc_geoip_plugin.php” from “/wp-content/wp-super-cache/plugins/”
- Edit /wp-content/wp-cache-config.php and change “$wp_cache_plugins_dir = ‘/somepath/wp-content/ccwpsc_plugins’;” to “$wp_cache_plugins_dir = WPCACHEHOME . ‘plugins’;“
10. Warning:
You should not use ANY Caching plugin OR extensions to them UNLESS you know how to use an FTP program (e.g. Filezilla). Caching plugins can cause “white screen” problems for some users; and sometimes the only solution is to manually delete files using FTP or OS command line. WPSC is no different; when I checked the first page of its support forum included 4 posts about this. The Country Caching plugin deletes files on deactivation/delete, but in “white screen” situations you may have to resort to “manual” deletion – see FAQ for instructions.
August 26, 2017 at 1:58 pm
Legacy page caching is not anymore an option for latests versions of WP Super cache.
Is that a problem?
August 26, 2017 at 5:30 pm
Thanks for pointing this out Konstantinos.
I’ll check it out more thoroughly later. But quick testing shows it works with these new WPSC settings:
Dashboard->Settings->wpsc->
On the advanced Tab:
Set “Cache Delivery Method” to Simple
And check/tick “Cache HTTP headers with page content.”
January 19, 2018 at 6:31 pm
This plugin is just great! Do you have an workaround/idea about how to preload the pages per country?
January 21, 2018 at 4:33 pm
Thanks & excellent question. Pre-generating cached pages for every post for every specified country in addition to the “default county(s)’s” is not really feasible. However; I have an alternative DIY “5 line plugin” solution that may suit.
Browsers recognize prefetch meta tags which tell the browser that after loading current page to then make “advance” background requests for other pages (if not in browser cache). As well as being faster for visitors than server caching, these requests would also result in WPSC caching these pages based on the visitor’s country.
e.g. You could make the prefetch plugin always specify prefetching of home page and some slow page; and additionally to prefetch other posts specifically related to the actual post requested by the visitor. If these pages aren’t already cached for the visitors country then WPSC will then cache them. See adding prefetch and prerender tags to WP posts.
February 9, 2018 at 3:56 am
I added it to my blog and it’s working ok. Great post for newbie like me.
February 27, 2018 at 11:14 am
It’s a great plugin. I just installed this plugin on my website and is working well.
Here are the few queries,
Recently I noticed that some mismatch between IP detection for the database I used in my website and to that to this plugin, in a rare case. Thought the problem occurs once in 1000 users, Think that any of the two DB determines differently for the 1st user. I am using GeoLite2-City.mmdb on my website. Is there a way to make this plugin to detect the country using GeoLite2 database. Even I thought of using the same DB that this plugin use on my website, but I later found that the GeoipLite is going to discontinued from next month.
Hope you understand the problem that I faced. do please help me with it.
February 27, 2018 at 3:50 pm
Hi Sekar
Excelent question and spot on analysis. The different DBs is the most likely cause of your occasional discrepancies. There will be the odd mismatch e.g. one database returns “EU” for Opera VPN IPs and the other “”.
1. The next releases (1 to 2 months) of both the Country Caching (CC) and Category Country Aware (CCA) plugins will use Maxmind (country) version 2. N.B. The last release of the old legacy DB by Maxmind will be April 2018, any plugins using it will continue to function but the look-up data will become more and more out of date.
2. The CCA plugin already includes a hook that allows use of other Geolocation software, but it is not suitable for Country Caching. Hopefully the next CC plugin release will also include this capability.
3. Country Caching and the CCA plugin share the same Maxmind data directory. If you also install the CCA plugin it will automatically update Maxmind data monthly (I am not aware of any other plugin that will be doing this for V2 data).
The city mmdb is 68MB compared with 3MB for GeoLite2-Country.mmdb. If you don’t need city data then use the country mmdb instead, look-ups will be faster.
Temporary fix (only for PHP experts – it can really break your site):
The CC plugin checks variable $_SERVER[“HTTP_CF_IPCOUNTRY”] for country code as provided by Cloudflare FIRST. As you are not using CF you can populate this variable with Country code from your Geolocation BEFORE WPSC RUNS.
Add appropriate code to do this to wp-config.php e.g.
// include script(s) necessary for your look-up
// (must be able to run independent of wordpress and
// avoid namespace/class/function conflicts
//
// e.g. assuming your Maxmind scripts were installed with composer
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;
$reader = new Reader('/path/to/GeoIP2-City.mmdb');
$record = $reader->city($_SERVER["REMOTE_ADDR"]);
//
// look up visitor country and insert in variable that will be used by CC plugin
$_SERVER["HTTP_CF_IPCOUNTRY"] = $record->country->isoCode;
Not tested. If the above information is insufficient for you to work out how to add your own fix then don’t attempt.
If you are doing your own custom geolocation also alter your own code to obtain country code from $_SERVER[“HTTP_CF_IPCOUNTRY”] first (if not empty) – this will avoid duplicating look ups.
March 2, 2018 at 1:14 pm
Thanks for your reply. I am new to WordPress, even to PHP. However, i will try to implement it. or else I will go with $_SERVER[“HTTP_CF_IPCOUNTRY”].