WordPress Maintenance Mode

Recently, I was playing around with some new tools and libraries, and remembered that back in the days there was a special PHP file used to intercept requests early in WordPress loading cycle and inject additional logic. It is called sunrise.php and unfortunately it only works with Multisite. But in this post I want to talk about the WordPress Maintenance Mode.

These two things are connected with each other because both of them are called “dropins” in WordPress terminology, and both of them are living in the /wp-content/ directory.

Maintenance mode is technically a procedure, not just a drop-the-file-and-forget, like with sunrise.php. That’s because it consists of multiple steps.

But before I get into how to work with it, I will briefly describe what’s that in general.

Default Maintenance Mode

Maintenance mode in WordPress is a message, or a state (both are true), displayed to anyone accessing your site while something is being done behind the scenes. I think there are thousands of blog posts out there describing that you can put the site into a maintenance mode while updating plugins, changing the site design, working on big changes, prevent the server to die, etc.

But that’s from you – site admin – point of view.

From WordPress-the-software point of view it’s a “do not load” mode, when WP does not respond to requests and does no business/loading logic.

By default, it’s used only when upgrading WordPress and swapping directories when doing a plugin upgrade.

When this happens, WordPress does several things:

1. writes a special key=>value pair into the wp_options table
2. creates a new .maintenance file in the root of your site (where the wp-load.php is located), with a single global PHP variable called $upgrading holding a timestamp value.
3. decreases significantly the number of files it’s loading for the request
4. responds with a default message:

No plugins are loaded, no theme is loaded, no translations, even the database is not engaged at all. At this point only a dozen or so files are loaded, with minimum logic.

The caveat is – this is happening for everyone.

So you, as a site admin, can’t do anything in the wp-admin area, as there is none being loaded.

And this is a perfect screen to display to your users while some database migrations are being done, or infrastructural changes that will affect data integrity or visual representation.

Luckily, we can customize it, and that’s why earlier in the post I mentioned that the WordPress Maintenance Mode is actually a multistep procedure – you can initiate it yourself!

How to initiate Maintenance Mode

To initiate this mode you need to do one thing, but you can do that in 2 different ways:

The “file” way

You will need to create a .maintenance file on the same level where the wp-config.php is located.

And then put this code inside of it, so just the $upgrading variable is set and usable.

<?php $upgrading = 1731272292; ?>Code language: PHP (php)

The value is actually important. WordPress considers the maintenance to be over if more than 10 minutes has passed between the variable value and the current timestamp. So pick the value carefully.

The “command-line” way

The second approach is more suitable for hosts, developers, and especially for CI/CD integrations.

You need to run a wp-cli command:

wp maintenance-mode activate

Which will create that file for you with the current timestamp.

You can read more in the wp-cli maintenance-mode doc.

How to configure the look of the maintenance message

And now, if you want to make your maintenance message less boring, we’ve come to the second step of the procedure – making it nice.

For that, as mentioned earlier, WordPress has a dropin called maintenance.php file, which is loaded from this location wp-content/maintenance.php only if the site is already in the maintenance mode.

So that means having that file there without this mode does absolutely nothing. But if someone guesses it and opens directly by navigating to https://example.com/wp-content/maintenance.php – they will see you message.

So you can create (or find/generate online) a nice-looking HTML template that will nicely output some reassuring message, put it into that .php file, and call it a day.

And it will be presented to site visitors sporadically when the maintenance mode is initiated manually, or when WordPress is updating, or when CI/CD triggers the wp-cli command.

I asked Copilot in my PhpStorm to generate some basic HTML for the maintenance page. This is the only thing that was generated by AI in this post: