Website DIY - tricks and solutions

GeoLocation and WP Super Cache: caching by page + visitor country, instead of just page

In this article:

1. Introduction
2. What the free WPSC Country Caching Extension does
3. Getting and setting-up the CC Extension plugin
4. Why a custom add-on directory is recommended
5. Configuring Super Cache to use a custom directory for add-ons
6. How do I know Super Cache is country caching?
7. When do I need to clear cache?
8. GeoLocation, and how to auto-update
9. Directory & file permission problems
10. Auto & Manual Uninstall
11. 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 builds an add-on script which uses an official documented Super Cache interface to cache by page/country instead of just page. You can limit separate caching to specified countries.
  • It provides the GeoIP look-up (via Cloudflare or Maxmind data) to enable WPSC to determine the visitor’s country.

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.


  1. Dashboard->Country Caching“. Check the “Enable WPSC” check box, and click save.
  2. Dashboard->Settings->WP Super Cache->Advanced Tab”
    • ensure “Cache Delivery Method” is set to Simple; and
    • check/tick “Cache HTTP headers with page content”
    • then save.

NOTE: if you later use WPSC’s settings to temporarily disable caching it also unsets “Cache HTTP headers with page content.” You will have to check this again on WPSC’s Advanced tab for country caching to function.

Optional, but strongly recommended (see why below): configure Super Cache to use a custom directory for add-ons (see how below)

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.

4. Why you should configure WPSC to use a custom directory for add-ons

The Super Cache plugin (WPSC) is designed to by default to check for add-on scripts in a sub-directory of its own plugin folder. As WPSC’s author explains this isn’t ideal; any scripts you, or a 3rd party plugin, insert there will be deleted when you upgrade to a new version of Super Cache. WPSC will revert to using and creating “standard” cache. AS WPSC’s author explains this problem will not arise if you configure WPSC to use a custom plugin (add-on) folder – see next section.

What if I don’t use a custom folder? If you install a new version of WPSC then you will need to go to the Country Caching settings form and click save settings – this will re-apply the country caching add-on.

Automatic reminder, if you forget:The Country Caching plugin automatically (once a week by default) checks if the add-on is missing, and if so will email you a reminder to re-apply it. N.B. if you didn’t receive an email when you installed country caching, then the plugin is unable to schedule monitoring and email reminders from your server.

5. How to configure WPSC to use a custom directory for add-ons

Only do this if you are confident you know what you are doing and how to recover from errors.

Edit “wp-cache-config.php” (located in your “wp-content” folder); replace:

$wp_cache_plugins_dir = WPCACHEHOME . 'plugins';


$wp_cache_plugins_dir = WP_CONTENT_DIR . '/ccwpsc_plugins/';
if ( !defined('CCWPSC_WPSC_CUSTDIR') ) define( 'CCWPSC_WPSC_CUSTDIR', $wp_cache_plugins_dir);
N.B. if you had previously used the CC plugin to generate an add-on script then it will still be located in the old WPSC directory. You will have to rebuild it in the new Custom Folder by going to “Dashboard->WPSC Country Caching Settings” and clicking the “Save Caching Settings” button.

6. How do I know WPSC is country caching

Testing GOTCHAs:

  • 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 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":"\/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.

7. 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.

8. 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 GeoLite Legacy Country Database (available from Maxmind) will be automatically installed.

Updating The included Maxmind Country/IP range data files will lose accuracy over time. If you would like an automate update of these files then install the Category Country Aware plugin (here on WordPress.Org). Even if you don’t use any of its other features, it will automatically update GeoIP data “every 3 weeks”.

If your server’s settings prevent auto install of this data (see next section) then you will have to upload both IPv4 data from this location; and IPv6 data to the “maxmind data folder”. The required name/location on your server for this folder can be identified via the Monitoring” tab of the Country Caching Settings Form.

9. Problems and Issues

If the plugin is unable to install Maxmind data, or save the generated add-on script, it is probably 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.

If permission changes still do not enable the plugin to save the add-on script, then the plugin will give you an option to download the add-on, which you can then manually upload to your server using FTP (see below).

Alternative solution: manual upload:

N.B. If you are having to do a manual upload then it makes sense to configure and use a custom add-on folder (see above).

For FTP of Maxmind files see section 8 above.

If the plugin is unable to write the script to the add-on folder it will display a “Files” panel with an option to download the generated script.

  1. Check that the country settings for the add-on are as required (these will be displayed just above the download button). If not, go back to the settings form “WPSC” tab, change the Country settings field and click “Save”.
  2. Click “download” to save the file (“cca_wpsc_geoip_plugin.php”) to your local machine.
  3. Use a text editor to open the file. It should contain PHP code; if just contains an error message then abandon the upload.
  4. connect to your server with FTP
  5. if you have configured WPSC to use a custom add-on folder, and it doesn’t exist, then create it under the appropriate directory.
  6. if WPSC is using the “standard” folder then change directory to your custom folder (if using one) otherwise to the “/wp-content/plugins/wp-super-cache/plugins/” folder.
  7. upload “”cca_qc_geoip_plugin.php” to the appropriate add-on folder, then exit ftp.
  8. on the Country Caching settings form switch to the “WPSC” tab, confirm you have completed the upload and click update.

10. 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.

If all else fails:

  1. Log into your site via FTP; e.g. with CoreFTP or FileZilla; and if they exist:
  2. Delete this directory and contents: /wp-content/plugins/country-caching-wpsc/
  3. Delete cca_wpsc_geoip_plugin.php from any custom add-on directory you defined, and from “path to /wp-content/plugins/wp-super-cache/plugins/”
  4. Then via your WordPress Admin: Dashboard->Settings->WP Super Cache->Easy->delete cache

11. 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.


  1. Legacy page caching is not anymore an option for latests versions of WP Super cache.
    Is that a problem?

    • AW

      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:

      On the advanced Tab:
      Set “Cache Delivery Method” to Simple
      And check/tick “Cache HTTP headers with page content.”

  2. This plugin is just great! Do you have an workaround/idea about how to preload the pages per country?

    • AW

      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.

  3. I added it to my blog and it’s working ok. Great post for newbie like me.

  4. 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.

    • AW

      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 “”.

      “GeoipLite is going to discontinued from next month.”

      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).

      “I am using GeoLite2-City.mmdb …. I thought of using the same DB that this plugin use on my website”

      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.

  5. 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”].

Leave a Reply

Your comment will appear after its approved; usually within 12 hours but can be up to a week.
Your email address is optional and will not be published.

Copyright © 2015-2018  Means.Us.Com
This site recommends and is hosted by: Kualo Web Hosting.    
Theme: hemingway

Blog home  |  ↑ Top of Page ↑