Surge is a new WordPress page caching plugin that stands out because it has no settings. There’s nothing to configure, it just works. If you’re an experienced webmaster however, there are a few configuration tweaks you can do by adding a small PHP file. Here’s how.
Step 1, add the file
Create a new file in the root of your WordPress install, and call it “cache-config.php”. You can use a differen name since we’ll tell Surge where to find it in step 2, but make sure it’s a PHP file. This is what should be in it at the very minimum.
<?php
return $config;Code language: PHP (php)Once we’ve hooked it up in the next step, this file will be included by Surge, and it’ll know about the $config variable. That variable contains an array of settings. Our file’s job is to modify $config, and then return it. Any settings we’ll change before returning $config will then be used by Surge. But for now, let’s simply return the array as is.
Step 2, modify wp-config.php
Next, we’ll need to tell Surge where our new file is, and what it’s called. You can do this by adding a single line to your website’s wp-config.php. Find the line that sets “WP_CACHE” to true, and directly below it, add the following.
define( 'WP_CACHE_CONFIG', __DIR__ . '/cache-config.php' );Code language: PHP (php)This will tell Surge to look for cache-config.php in the current folder. Check if your site still works, and we’re ready to do some actual tweaks. If your wp-config.php is not in the site’s web root folder, you’ll nee to modify the code above accordingly.
Configuration fields
Currently, the $config array contains four fields that you can change. You’re not allowed to remove any, and adding new ones won’t work either.
| Array key | Value |
|---|---|
| ttl | The number of seconds a page is cached before cache is invalidated |
| ignore_cookies | An array of cookie names that are will not cause a page to be excluded from caching |
| ignore_query_vars | An array of URL parameters that won’t cause a page to be excluded from caching |
| variants | An array of “variants”, see this blog post for more info |
Setting a longer cache expiration time
TTL stands for “time to live”, and basically determines how long any page will be served from cache before a fresh copy is generated. By default the value is 600, so any cache file will be expire after 10 minutes. This is a good default value, but on this blog, which isn’t updated very often, I wanted to set it to a higher value. Here’s the cache-config.php I’m using.
<?php
$config['ttl'] = 1800;
return $config;Code language: PHP (php)As you can see, I’ve added a line that sets the “ttl” value before returning the array to Surge. As a result, pages are now cached for half an hour.
Adding a URL parameter to ignore
If your website uses a URL parameter that does not result in the page’s content being unique, you can improve Surge’s efficiency by adding that parameter to “ignore_query_vars”.
<?php
$config['ignore_query_vars'][] = 'my_var';
return $config;Code language: PHP (php)This will add “my_var” to the of set url variables that Surge ignores. This means that “example.com?my_var=1” and “example.com?my_var=2” are considered identical and will be served from cache.
If you’re not familiar with PHP, please note the extra set op square brackets. In other languages, you’d use something like push(), but this is PHP’s weird way of adding an item to an array. Without the [], the existing array would be overwritten. Since is contains a large number of commonly use tracking and marketing variables, that is not a good idea. Also, “ignore_query_vars” would then be a string, not an array.
Adding cookie names and variants works in much the same way.
Advanced options
Since the configuration file is written in PHP, you can get creative with it. For instance, a simple if-statement will allow you to modify the settings only for certain user agents. Please do note that cache-config.php is executed very early, before most of WordPress is booted up. Hooks, filters and core functions may not yet be available.
For most users, Surge will work fine out of the box. But it’s nice to have some control should you need it.
