Getting started
Complete Installation first. This walkthrough adds maintenance mode without enabling administration routes or requiring a database.
Confirm that the commands are loaded
Run this from your application's root:
bin/cake maintenance_mode statusA fresh installation reports that maintenance mode is disabled. This reads the status; it does not take the application offline.
Add the middleware
In src/Application.php, import the middleware:
use Cake\Routing\Middleware\RoutingMiddleware;
use Setup\Middleware\MaintenanceMiddleware;Add this line to your existing middleware() method before RoutingMiddleware and authentication. Keep ErrorHandlerMiddleware earlier in the queue:
$middlewareQueue->insertBefore(RoutingMiddleware::class, new MaintenanceMiddleware());Create templates/Error/maintenance.php in your application. This template is required; the plugin does not ship a fallback page:
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Maintenance</title></head>
<body><h1>Temporarily unavailable</h1><p>Please try again later.</p></body>
</html>The middleware renders it with HTTP 503 and no layout by default.
Try it locally
Activate maintenance in a disposable local application:
bin/cake maintenance_mode activateRequests now receive HTTP 503 without reaching the application's downstream handler. Finish by restoring normal service:
bin/cake maintenance_mode deactivateTo keep access for your own IP, whitelist it before activation. Use the IP seen by your application, especially behind a reverse proxy:
bin/cake maintenance_mode whitelist 127.0.0.1
bin/cake maintenance_mode whitelist ::1The whitelist applies to matching clients only. To test the maintenance page from that same client, remove the entry first:
bin/cake maintenance_mode whitelist 127.0.0.1 --remove
bin/cake maintenance_mode whitelist ::1 --removeThe status and whitelist files live under tmp/. CLI and web processes must see the same directory and have suitable permissions. With several hosts, deploy the state consistently or place it on a shared filesystem; local files do not coordinate the fleet.
Choose another feature
Healthchecks can inspect your environment through CLI or web endpoints. Console tools include database inspection and destructive reset commands; read their scope before using them. The web backend requires explicit route enablement and your application's access control.
Debugging helpers such as prd() and vd() load with the plugin bootstrap and print only while debug is enabled. The plugin does not make administration endpoints safe to expose publicly.