wp_maintenance() │ WP 3.0.0

Die with a maintenance message when conditions are met.

The default message can be replaced by using a drop-in (maintenance.php in the wp-content directory).

Internal function — this function is designed to be used by the kernel itself. It is not recommended to use this function in your code.

No Hooks.

Return

null. Nothing (null).

Usage

wp_maintenance();

Examples

0

#1 Putting the site into maintenance mode (updates, development)

When updating code on the site, it is recommended to put the site in maintenance mode (block for the duration of the update), so that sudden visits from users could not affect the process of updating files or DB.

To enable such a mode you need:

Option 1:

Create file .maintenance in the root of the site (directory where wp-admin folder is located) with the following code:

<?php
// UNIX time stamp after which + 10 minutes,
// the site will exit development mode.
$upgrading = 1652995051; // time();

Option 2:

Create an empty file ABSPATH . '.maintenance' and manually at an early stage, for example in the wp-config.php file specify a global variable $upgrading:

// UNIX time stamp after which + 10 minutes,
// the site will exit development mode.
$GLOBALS['upgrading'] = 1652995051; // time();

Done!

Refresh the page and see the maintenance message:

The site is briefly closed for maintenance. Come back in a minute.

0

#2 Let's change the text of the maintenance message:

Create a file /wp-content/maintenance.php with following code:

<?php
wp_load_translations_early();

$protocol = $_SERVER["SERVER_PROTOCOL"];
if ( 'HTTP/1.1' != $protocol && 'HTTP/1.0' != $protocol ){
	$protocol = 'HTTP/1.0';
}
header( "$protocol 503 Service Unavailable", true, 503 );
header( 'Content-Type: text/html; charset=utf-8' );
header( 'Retry-After: 600' );

// most WP functions do not work
?>

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"<?php if ( is_rtl() ) echo ' dir="rtl"'; ?>>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<title>Maintenance</title>
</head>
<body>
	<div style="max-width:800px; margin:50px auto; text-align:center;">
		<h1>Site is under maintenance. The correct work will be restored in a few minutes.</h1>
		<h2>Sorry for the inconvenience.</h2>
	</div>
</body>
</html>

When the site is updated, our message about the inaccessibility of the site will be changed and we will see the text specified above.

0

#3 Function to enable or disable maintenance mode

By default, such a function in WordPress is located in a method of the WP_Upgrader class - WP_Upgrader::maintenance_mode(). That is, to run it, you need to create an instance of the class, that depends on another class WP_Upgrader_Skin. 

require_once ABSPATH . 'wp-admin/includes/class-wp-upgrader-skin.php';
require_once ABSPATH . 'wp-admin/includes/class-wp-upgrader.php';
$wp_upgrader = new WP_Upgrader( new class extends WP_Upgrader_Skin {
	public function feedback( $feedback, ...$args ) {} // reload method to do nothing
} );
$wp_upgrader->maintenance_mode( true );

// ---------------
// do your upgrade
// ---------------

$wp_upgrader->maintenance_mode( false );

It is not always convenient.

So let's write our own function that will allow us to conveniently enable and disable the maintenance (service) mode of the site:

/**
 * Enables or Disables the WP maintenance mode.
 *
 * @param string $action 'on' | 'off'
 *
 * @return void
 */
function wpkama_wp_maintenance_mode( $action = 'on' ){
	global $wp_filesystem;

	if( ! $wp_filesystem ){
		require_once ABSPATH . 'wp-admin/includes/file.php';

		WP_Filesystem();

		if ( 'direct' !== $wp_filesystem->method ) {
			/** @noinspection ForgottenDebugOutputInspection */
			wp_die( 'WP_Filesystem need to be direct type.' );
		}
	}

	$maintenance_file = $wp_filesystem->abspath() . '.maintenance';

	// Create maintenance file to signal that we are upgrading.
	if( 'on' === $action ){
		$maintenance_string = sprintf( '<?php $upgrading = %d; ?>', time() );

		$wp_filesystem->delete( $maintenance_file );
		$wp_filesystem->put_contents( $maintenance_file, $maintenance_string );
	}
	// Remove maintenance file, we're done with potential site-breaking changes.
	else {
		$wp_filesystem->delete( $maintenance_file );
	}

}

An example of the use of the function:

wpkama_wp_maintenance_mode( 'on' );

sleep(6); // simulate some actions

wpkama_wp_maintenance_mode( 'off' );

Changelog

Since 3.0.0 Introduced.

wp_maintenance() code WP 6.7.2

wp-includes/load.php 
function wp_maintenance() {
	// Return if maintenance mode is disabled.
	if ( ! wp_is_maintenance_mode() ) {
		return;
	}

	if ( file_exists( WP_CONTENT_DIR . '/maintenance.php' ) ) {
		require_once WP_CONTENT_DIR . '/maintenance.php';
		die();
	}

	require_once ABSPATH . WPINC . '/functions.php';
	wp_load_translations_early();

	header( 'Retry-After: 600' );

	wp_die(
		__( 'Briefly unavailable for scheduled maintenance. Check back in a minute.' ),
		__( 'Maintenance' ),
		503
	);
}

Admin Menu