Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
118 lines (89 sloc) 3.41 KB

Maintenance Mode

You can run shells from the ROOT dir as /bin/cake [shell] [command] (or .\bin\cake [shell] [command] for Windows).

Warning: This tool should not be used if the DB connection or your application goes down completely due to upgrades. There it would fail hard. It should only be used for soft maintenance work.

MaintenanceMode Shell

This should be the preferred way of enabling and disabling the maintenance mode for your website.


  • status
  • activate
  • deactivate
  • whitelist [{ip}] [-r]
  • reset

Example usage

cake Setup.MaintenanceMode activate
// Optionally whitelist your IP:
cake Setup.MaintenanceMode whitelist YOURIP
// Optionally whitelist your IP and activate the debug mode for when you access the application:
cake Setup.MaintenanceMode whitelist YOURIP --debug
// ... Do your work ...
cake Setup.MaintenanceMode deactivate

Tip: Your deploy script (e.g. sh script) can contain those commands. One at the beginning, the other at the end.

MaintenanceMiddleware (CakePHP 3.3+)

This should then be the preferred way of triggering the maintenance mode display, as it can way cleaner short-circuit the dispatching.

In your src/Application.php:

use Setup\Middleware\MaintenanceMiddleware;

	 * @param \Cake\Http\MiddlewareQueue $middleware The middleware queue to setup.
	 * @return \Cake\Http\MiddlewareQueue The updated middleware.
	public function middleware($middleware) {


Make sure you have a template file in APP . 'Template' . DS . 'Error' . DS named maintenance.ctp.


  • 'className' => View::class,
  • 'templatePath' => 'Error',
  • 'statusCode' => 503,
  • 'templateLayout' => false,
  • 'templateFileName' => 'maintenance',
  • 'templateExtension' => '.ctp',
  • 'contentType' => 'text/html'

Those can be used to adjust the content of the maintenance mode page.

Maintenance Dispatching Filter (deprecated)

Just add this in your bootstrap:

use Setup\Routing\Filter\MaintenanceFilter;

DispatcherFactory::add(new MaintenanceFilter());

You might want to wrap it with

if (php_sapi_name() !== 'cli') {}

to only add this filter for non CLI requests.

This filter has a very limited customization way. You can only adjust the string __d('setup', 'Maintenance work').

Maintenance Component

This component adds functionality on top:

  • A flash message shows you if you are currently whitelisted in case maintenance mode is active (and you just don't see it due to the whitelisting).

Setup Component

The Setup component adds some additional goodies on top:

You can set the maintenance mode via URL, if you quickly need to jump into it again:

// append to the URL
// optionally with timeout

With time in minutes for infinite time. It will automatically whitelist this IP, as you could not deactivate it again otherwise.


In productive mode you need a pwd, though, on top: ?pwd={YOURPWD}.

For security reasons you need to change the password, once used. Also, deactivate the URl access completely by removing the config pwd, when not in use, to prevent brute force guesses.

Extra Sugar

You can shell alias the MaintenanceShell for less typing in your bootstrap_cli.php:

use Cake\Console\ShellDispatcher;

// Custom shell aliases
ShellDispatcher::alias('m', 'Setup.MaintenanceMode'); // Or any other alias