Pimp My WordPress Maintenance Mode Message

When WordPress is updating the core, themes or plugins it generates a file in the root folder called .maintenance.

WordPress will be put into “maintenance mode” and your visitors will then see the message “Briefly unavailable for scheduled maintenance. Check back in a minute”.

You can easily replace this message with a custom page of your own.  Here’s how.

What is Maintenance Mode?

Whenever you run the update process on the WordPress core, a theme or a plugin, WordPress is placed in what is called “maintenance mode”.

The reason for this is to minimize any errors to file updates and to prevent your visitors from seeing any errors.

The update process downloads the most recent zip file from the WordPress.org repository, deletes the existing copy and then unzips the new version replacing the old one.

If you or your visitors were to try and access the site when this update process is taking place they would get errors due to missing files during the deletion and unzipping process.

This is the reason for WordPress’ maintenance mode.

How Does WordPress Know it is in Maintenance Mode?

The update process creates a small file called .maintenance in the root folder of your site.  The same location as your wp-config.php file.

Prior to WordPress 3.0, it was just the file itself that if detected would generate the maintenance mode message.

Sometimes things don’t work according to plan and if, for example, file and folder permissions were incorrect, the new zip files couldn’t be unzipped and the process would die (technically it would crash out).

This would leave the .maintenance file still in the root and the WordPress site would be left in maintenance mode limbo.

Site owners would have to manually delete the .maintenance file to get their site running again.

Since WordPress 3.0 a PHP variable $updating is added to the file containing a UNIX timestamp of when the file was created.

<!–?php $upgrading = 1367901024; ?–>

WordPress now checks this time against the current time and if it’s under 10 minutes the maintenance mode message is displayed.

This means that even if the update process fails and doesn’t automatically delete the .maintenance file, you can still access your site after 10 minutes. Yay.

Replacing the Default Maintenance Mode Message

The default message is pretty sucky, right?

As a developer that just won’t do so, I did a quick check to see where the message is being generated from and if there was anything I could do to change it without changing the WordPress core code (which you should definitely not do BTW).

The code is in the file wp-includes/load.php around line 131 in the function wp_maintenance().

Looking through the code you can see where it checks for the existence of the .maintenance file, then the timestamp within the file.

The next part of the function then checks to see if there is a file called maintenance.php in the wp-content folder.

[gist id=8142756 file=code-snippet-1.php]

Bingo! I can work with that.

Ten minutes later and a lot of code badgering we now have a nicely branded maintenance.php file sitting in the wp-content folder which overrides the sucky default maintenance mode message.

Everything else in your site is branded so why not this too!

Just remember that this page is out of scope for the WordPress libraries so things like $post and WordPress functions won’t work unless you include the appropriate files in your maintenance.php page.

Have a look at the final maintenance mode page.

Go forth and pimp your WordPress maintenance mode message and send us a link to it.

Learn more about Drop-ins and MU Plugins.