Toggle maintenance mode in Laravel using web routes

As a web developer, it’s important to keep your website up to date and running smoothly. However, sometimes you need to perform maintenance on your site and you don’t want your users to see any errors or downtime. That’s where Laravel’s maintenance mode comes in handy.

Laravel’s maintenance mode allows you to put your website into a state where it is only accessible to authorized users, such as admins or developers. This allows you to perform updates or make changes to your site without disrupting your users’ experience.

Enabling maintenance mode using CLI

To enable maintenance mode, you simply need to run the following command in your terminal:

php artisan down

This will create a maintenance mode “lock” file in your storage directory, which will prevent any users from accessing your site.

ℹ️ Note
The lock file is named "down" and it will be created in the storage/framework directory.

If you need to access your website while it’s in maintenance mode, you can use the --secret option to specify a secret endpoint that will create a browser session allowing you to bypass the maintenance mode:

php artisan down --secret=secret-route-to-allow-certain-users-to-access-the-application

You can then access your site by appending the secret route to your site’s URL:

https://example.com/secret-route-to-allow-certain-users-to-access-the-application

Once you’ve finished your maintenance tasks, you can simply run the following command to disable maintenance mode:

php artisan up

This will remove the maintenance mode lock file and allow all users to access your site again.

Enabling maintenance mode using web endpoints

The above method is fine and it works well. However, it is not convenient as you would need to SSH into your server to run the commands.

To manage maintenance mode from your browser, you can add custom routes to your routes/web.php file.

To enable maintenance mode, you can add the following route:

Route::get(
    '/enable-maintenance-mode',
    function () {
        Artisan::call( 'down', [
            '--secret' => 'allow-certain-users-to-access-the-application-using-this-secret',
        ] );

        dd( Artisan::output() );
    }
);

Notice that we are using the Artisan::call() method to run the down command. We are also passing the --secret option to specify a secret route that will create a browser session allowing you to bypass the maintenance mode.

To disable maintenance mode, you can add the following route:

Route::get(
    '/disable-maintenance-mode',
    function () {
        Artisan::call( 'up' );
        dd(Artisan::output());
    }
);

Bounce: Custom maintenance mode page

The default maintenance mode page is not that great.

It does the job but it does not provide any extra information to the user about why the website is down, when it will up again.

If you want to display a custom maintenance mode page, you can use the --render option to specify a view that will be displayed to your users:

php artisan down --render=custom-view

or using the Artisan::call() method:

Route::get(
    '/enable-maintenance-mode',
    function () {
        Artisan::call( 'down', [
            '--secret' => 'allow-certain-users-to-access-the-application-using-this-secret',
            '--render' => 'custom-view',
        ] );

        dd( Artisan::output() );
    }
);