wp_maintenance()
Stops the site from functioning and displays a message about maintenance (the site is in development mode).
Looks for the .maintenance file in the root of WordPress (next to the wp-admin folder). This file contains a global PHP variable $upgrading, with the value ― a unix timestamp (1374363082) (usually, when this file was created).
If the file exists and the value of the variable $upgrading does not exceed 10 minutes from the current time, then when visiting any page of the site, WP will display a message about the site's maintenance.
By default, this functionality is used during the update of WordPress code or plugins. But it can also be used in other cases, for example, when you need the site to be in an inaccessible state during a "live" code update, so that the code is not accidentally executed by a visitor's visit while the visitor sees a message that the site is temporarily unavailable.
The maximum duration of maintenance mode is 10 minutes.
The function triggers at a very early stage of WordPress loading, before the constant SHORTINIT.
If the time has expired, but the global variable $upgrading is specified in .maintenance, then a message appears in the WP admin panel (see: maintenance_nag()):
An automated WordPress update has failed to complete - please attempt the update again now.
This is apparently related to the fact that the time in the variable is checked against the time in the database when WP was updated.
The default placeholder text can be replaced. To do this, you need to create a file maintenance.php in the directory wp-content. In this file, you need to describe the placeholder page according to all HTML rules.
Use wp_is_maintenance_mode() to check if you are in update mode.
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.
Returns
null. Outputs the placeholder text and stops the script (site) execution.
Usage
wp_maintenance();
Examples
#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 Option 2: Create an empty file Done! Refresh the page and see the maintenance message:.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();
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();
#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.
#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. |