DEV Community

Peter Fox
Peter Fox

Posted on • Originally published at Medium on

Laravel Tip: Customising Maintenance Mode

Photo by Dmitriy Demidov on Unsplash

I feel one of the lesser used features of Laravel is it’s maintenance mode. This can be used from the artisan console via the artian up or artisan down command. The idea of this functionality is at the point your application needs to be blocked from being used, you can display a simple page describing the website as down. For example, sometimes a database migration needs to be done before a new version can be deployed, these migrations might take a few minutes and you don’t want your customers using the app in the meantime. an option would be to put the application into maintenance mode, run the migrations and then return to normal operations afterwards.

The way maintenance mode works out of the box though is quite limited for most major application setups. The default configuration is to store a file on the disk which assumes that you have a single server serving your application or that you are willing to SSH into all of your servers to run the command.

What many may not be aware of though is that actually there are options to change the configuration or even implement your own driver.

Changing to the Cache driver

The config key is app.maintenance.driver with an option to set this to file or to cache. You may also configure which cache to use by setting, again, this defaults to the default cache if not set, but this could be useful if you wanted to use the database on a simple cross server setup.

There is one issue to think about with this setup though. Namely to consider if your cache store is accessed regularly, how would it impact application performance? Maintenance mode whether switched on or not is checked on each request which means latency between the cache and the servers could really impact your request times.

An example of this setup in your config would be:

Implementing your own driver

There is equally the option of building your own implementation. To do this we need to first create a class and implement the interface.

Within this class we now has to establish the mechanisms of enabling and disabling the maintenance mode as well as storing information about the maintenance mode. For example you may tell your driver to perform a maintenance mode with a particular status code or to use a particular view.

In this article we’re going to make something simple. We’re going to use the File storage system built into Laravel to make a more advanced file storage. This means we could store the file on a shared file system such as AWS S3.

We’ll do this with the following implementations.

The activate and deactivate methods is what responses to the artisan up and artisan down commands. The active method will be what is called to check if the website is in a downed state or not and if it is then the data method will be called to tell the application how to present the downed state.

Now that we have the working code for our custom maintenance mode, we only need to register it and set the value in the config.

We can add this to the AppServiceProvider’s register method as just a quick place to put this.

Then all we need to do is change the app.php config to make the application use our new custom driver for the maintenance mode feature.

When we do run artisan down we can actually see the contents of a file being stored called down.json. The contents of which you can see down below:

And that’s it. We can now use a filesystem to perform maintenance mode when ever we wish. We also have the knowledge to go further with this. While most the time the cache system is still the best way of accessing this mode. There’s no reason you can’t expand this technique to customise your own maintenance mode system to potentially rely on a third party service.


Hopefully in getting through this article you’ve now learnt a little bit more about the Laravel Framework and how to grow your app to suit your needs when it comes to the maintenance mode.

Something to bare in mind though when working with a custom maintenance mode is to keep your mechanisms simple. For example, if your new driver relies on a database that you’re going to take down for maintenance then you’ve created a conflict there. The same is possible of your cache of course so if you are going to customise your maintenance mode, make it work independent of your core app and make sure it’s able to handle lots of requests.

If you feel like playing around with the code in the project itself. You can find it here on GitHub.

I’m Peter Fox, a software developer in the UK who works with Laravel among other things. Thank you for reading my article, I’ve got several more on both Medium and If you want to know more about me, head over to I’m also now also Sponsorable on GitHub. If you’d like to encourage me to write more articles like this please do consider dropping a small one off donation.

Top comments (0)