How to use a maintenance.php file inside a WordPress theme?

Question

I was wondering if anyone knows a way to use a maintenance.php file inside your WordPress theme, instead of the one in the wp-content folder.

I'm mainly looking for some code for the functions.php file which would call the maintenance.php file in the theme folder.

We'd like to add some branding to the maintenance page and therefore it would be best to be able to use it from inside the theme folder. I know there are special plugins for this. But we don't want to give our sites too much overhead from plugins that are only used for small details like this, so if there's a way to achieve this via the theme folder it'd be great!

score 3 · Accepted Answer · answered Aug 02 '17 at 06:52

When WordPress goes into maintenance mode, it adds a file named .maintenance to the root directory while the maintenance is being performed, then it's removed afterwards. You can write a function inside your theme's functions.php that checks for this file and loads a custom maintenance page from the theme.

if ( ! function_exists( 'wpse84987_maintenance_mode' ) ) {
    function wpse84987_maintenance_mode() {
        if ( file_exists( ABSPATH . '.maintenance' ) ) {
            include_once get_stylesheet_directory() . '/maintenance.php';
            die();
        }
    }
    add_action( 'wp', 'wpse84987_maintenance_mode' );
}

Put your maintenance content in the maintenance.php page inside your theme folder and you're all set to style it however you would like.

If you use the wp_die function, you'll get the standard white box on grey background. This way lets you style your maintenance page like you would any other theme page.

You can also do this outside the theme by adding maintenance.php to the wp-content directory (or wherever you've set WP_CONTENT_DIR to point to) as a drop-in plugin. When WP checks for maintenance mode from inside wp_maintenance() it'll look for that file and load it if present, or load its own if not. If the site isn't in maintenance mode, or is in it for more than 10 minutes, 'maintenance.php' won't load even though the site is technically still in maintenance mode. WordPress 4.6 introduces the 'enable_maintenance_mode' filter, which can be (ab)used by a tool like wp-cli to force the check for the drop-in and would let you run a CLI command from your maintenance file.

Weird. I came across exactly the same code yesterday but I didn't get it to work at that time. Now it works like intended, it loads the maintenance.php in the theme! Thank you! — ProxxiM, Aug 02 '17 at 07:02
Although this will load the file, I've noticed that using wordpress functions such as `get_header()` will result in a Undefined function message when viewing the page. How can this be resolved so the page can be built just like a page.php file within the theme? — Lee, Sep 04 '18 at 08:19

Roko C. Buljan · Answer 2 · 2021-06-22T03:07:37.127

Wordpress switch Maintenance mode

What we'll create:

User - show the "Under Maintenance" page
Admin - able to view the entire website
Add an option to the Settings - General panel to switch the maintenance mode on/off

First, create a maintenance.php file in your theme root:

<!DOCTYPE html>
<html <?php language_attributes(); ?>>

<head>
    <meta charset="<?php bloginfo('charset'); ?>">
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <?php wp_head(); ?>
</head>

<body class="page-maintenance">

    <img src="<?= get_template_directory_uri() . '/assets/img/logo.png'; ?>" alt="<?= get_bloginfo('name') ?>">
    <p><?= get_bloginfo('description') ?></p>
    <h1>Under maintenance</h1>
    <p><b>We'll be back soon!</b></p>

    <?php wp_footer(); ?>
</body>
</html>

Add to functions.php:

/** 
 * Under Maintenance
 */

// Add options checkbox to Settings / General 
function mythemename_settings_general_maintenance()
{
    add_settings_section(
        'my_settings_section', // Section ID 
        'ADDITIONAL SETTINGS', // Section Title
        'my_section_options_callback', // Content Callback
        'general' // Show under "General" settings page
    );
    add_settings_field(
        'maintenance_mode', // Option ID
        'Maintenance mode', // Option Label
        'maintenance_mode_callback', // Callback for Arguments 
        'general', // Show under "General" settings page
        'my_settings_section', // Name of the section
        array( // The $args to pass to the callback
            'maintenance_mode' // Should match Option ID
        )
    );
    register_setting('general', 'maintenance_mode', 'esc_attr');
}
function my_section_options_callback()
{
    // Custom Section Callback content
    echo "Custom theme options";
}
function maintenance_mode_callback($args)
{
    // Checkbox Callback
    $value = get_option($args[0]);
    $checked = ($value == "on") ? "checked" : "";
    echo "<label>
      <input type=\"checkbox\" id=\"$args[0]\" name=\"$args[0]\" $checked />
      <span>Check to activate Maintenance Mode page</span>
    </label><p>A general <i>Under Maintenance</i> page will be shown to non-admin users.</p>";
}
add_action('admin_init', 'mythemename_settings_general_maintenance');

// Handle Maintenance page
if (!function_exists('wp_under_maintenance')) :
    function wp_under_maintenance()
    {
        $isLoginPage = basename($_SERVER['PHP_SELF']) == 'wp-login.php';
        $isMaintenanceModeOn = get_option('maintenance_mode') == "on";

        if (
            $isMaintenanceModeOn &&
            !$isLoginPage &&
            !is_user_logged_in() &&
            !is_admin() &&
            !current_user_can("update_plugins")
        ) {
            get_template_part('maintenance');
            exit();
        }
    }
endif;
add_action('init', 'wp_under_maintenance', 30);

Now go to your Admin panel, Settings, General and you'll find:

How to use a maintenance.php file inside a WordPress theme?

2 Answers2

Wordpress switch Maintenance mode