Create a Custom WordPress Maintenance Mode Plugin

Putting your site into maintenance mode serves a few purposes. First off, it tells users that something is up – you’re working on it or there’s an error to resolve. Second, a proper maintenance mode will throw a server response code that tells search bots that the site is only temporarily unavailable and to check back later. Finally, a good maintenance mode, won’t change or redirect any URLs.

In this tutorial, I’m going to show you how to create a custom WordPress plugin that, when activated, puts the site in maintenance mode for all buy administrators.

The proper status to use when your site is undergoing maintenance is 503 Service Unavaiable. Fortunately there’s a handy filter we can hook into to change the status. The hooked function will get four arguments: the current status header (text), the status code, the text part of the status header (eg. OK or Not Found), and the HTTP protocol.

<?php

add_filter('status_header', 'pmg_maint_change_status', 10, 4);  /**  * Changes the status header to 503.  *  * @uses get_status_header_desc  * @return string The status header  */  function pmg_maint_change_status($header, $status_code, $text, $proto)  {  $text = get_status_header_desc(503);  return "{$proto} 503 {$text}";

}

503 statuses often have another accompanying header, Retry-After, which tells bots and browsers when they should check back. We can hook into wp_headers to add that header. Retry-After should contain a length of time in seconds. We’re going to use an hour, 3,600 seconds.

<?php

add_filter('wp_headers', 'pmg_maint_headers');  /**  * Hooked into 'wp_headers'. Adds the 'Retry-After' header  *  * @return array The array of HTTP headers  */  function pmg_maint_headers($headers)  {  $headers['Retry-After'] = 3600;  return $headers;

}

With the stuff for bots out of the way, it’s time to show our visitors a message. To do that, we’re going to hook into the template_include filter. Whenever you load a page, eventually the WordPress codebase includes a file at wp-includes/template-loader.php that finds the templates in your theme to use for each given page. template_include fires after the template has been located and allows you to override it.

<?php

add_filter('template_include', 'pmg_maint_template');  /**  * Hooked into 'template_include', returns a new template for all the pages  *  * @return string The full path to the template file  */  function pmg_maint_template($t)  {  return PMG_MAINT_PATH . 'inc/template.php';

}

From here’s it’s just a matter of a bit of code to style the template. This can be as simple or complex as you want.

If you happen to be doing work on your site, chances are you actually want to preview it. To make that happen, we could include a call to current_user_can to check for admin capabilities inside each of the three functions above. Or, to save some typing, we can hook into init and add our actions to the other filters if there’s no administrator.

<?php

add_action('init', 'pmg_maint_init');  /**  * Hooked into 'init'. Adds other actions if there isn't an admin viewing the  * site.  *  * @uses add_filter  */  function pmg_maint_init()  {  if(current_user_can('manage_options'))  return;  add_filter('status_header', 'pmg_maint_change_status', 10, 4);  add_filter('wp_headers', 'pmg_maint_headers');  add_filter('template_include', 'pmg_maint_template');

}

You can view an example of all this on Github.