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

Setup:

  1. Dashboard->Country Caching“. Check the “Enable WPSC” check box, and click save.
  2. Dashboard->Settings->WP Super Cache->Advanced Tab” Ensure “Legacy page caching” is selected, then save.
  3. Optional, but strongly recommended (see why below): configure Super Cache to use a custom directory for add-ons (see how below)

You don’t even need to clear existing cache!

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';

by:

$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

  1. Ensure WPSC is set for Legacy Page Caching (see set-up above)
  2. Open a few pages on your site using a “virgin” browser (see Gotchas below)
  3. Using another logged-in browser, go to “Dashboard->Settings->WP Super Cache->Contents” and click “List all cached files”. Note WPSC won’t automatically refresh this display; you may have to exit and return to this page a few times.
  4. If Country Caching is working you will see the country code for your location is used as a key suffix by WPSC (see yellow highlighted country codes in snapshot image above).
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).

N.B. if you have limited separate caching to specific countries 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 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.

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.