Get your next remote job on LaraJobs.
1 comment 1 contributor Edit on GitHub Laravel

Master Laravel's maintenance mode

Master Laravel's maintenance mode

Enabling Laravel’s maintenance mode

When it’s time to update your app or change a few things on the server, switching to maintenance mode is super handy. And yet, I always forget it exists. 🤦‍♂️

The maintenance mode is like putting a “Be right back!” sign on your website. To get this going in Laravel, it’s as simple as running a command:

php artisan down

What if you want to give users a heads up that the site will be back shortly? Just add a refresh option:

php artisan down --refresh=15

This will tell the user’s browser to reload the page after 15 seconds.

Laravel’s maintenance mode in action.

Sneaking past maintenance mode

Now, here’s a cool trick. You can bypass maintenance mode with a secret token. Create a token using:

php artisan down --secret="your-secret-token"

Visit your app’s URL with the token appended (http://example.test/WeHrMT6odmCLXWkE for example), and you’ll get a bypass cookie.

And if you prefer Laravel to create a token for you, version 10.35 lets you do this:

php artisan down --with-secret

Just remember, keep that secret simple and URL-friendly.

Pre-rendering Laravel’s maintenance view

Want to avoid errors when users hit your site mid-update? You can pre-render a maintenance view that shows up instantly:

php artisan down --render="errors::503"

This is served up before Laravel fully boots, so it’s quick to the draw.

(The 503 HTTP code means “Service Unavailable,” hence the need to render this error page.)

Redirects during maintenance

Maybe you’d rather redirect users elsewhere while you tidy up. No problem:

php artisan down --redirect=/

This steers visitors to wherever you specify.

Disabling maintenance mode

All done? Great, let’s bring your app back with:

php artisan up

And just like that, you’re live again!

Customize Laravel’s maintenance page

You’re the boss when it comes to how your maintenance page looks. Set up your own template at resources/views/errors/503.blade.php and make it your own.

What about queued jobs during maintenance mode?

Worry not; queued jobs are put on pause in maintenance mode. They’ll pick up right where they left off once you’re back in action.

Why use the maintenance mode in the real-world?

Laravel’s maintenance mode can be extremely useful when, for instance, deploying applications in production.

Here’s a simplified version of the deploy script of this blog before I switched to zero downtime deployments:

cd /path/to/project
# Put the blog down and show a pre-rendered page for a 503 response.
php artisan down --render="errors::503"
git pull origin main
composer install --no-interaction --no-suggest --prefer-dist --optimize-autoloader
php artisan migrate --force
php artisan config:cache
# …
npm i
npm run dev
# Deployment is finished, let's put the blog back up.
php artisan up

As you can see, to avoid people sumbling upon various errors while the code changes, composer install runs, or the database is updated, I put the blog down and show a custom 503 (Service Unavailable) page.

Now, since I’m using Ploi to handle my deployments with zero downtime, this trick isn’t needed anymore. But for those running in legacy environments, I think you’ll find it handy.

1 comment

Kareem Aladawy
Kareem Aladawy 2mos ago

Very much appreciated!

Get help or share something of value with other readers!

Great deals for enterprise developers
The latest community links

Recommended articles

20+ Laravel best practices, tips and tricks to use in 2024

Learning a framework can be overwhelming, but time and execution will make you a master. Here are some best practices to help you toward your goal.

9 testing best practices for Laravel in 2024

Are you familiar with testing? Good. Here are a bunch of best practices to help you level up even more!

How does Laravel work? A crystal clear explanation.

Discover my step by step and simple explanation of how Laravel makes your life easier.

7 Laravel RESTful APIs best practices for 2024

Master the art of crafting RESTful APIs with Laravel thanks to these best practices.

Laravel interview questions and answers for 2024

Nailing a Laravel job interview can be a daunting task, but with the right preparation and mindset, you can set yourself up for success.

3 crucial Laravel architecture best practices for 2024

Explore Laravel's default architecture to simplify collaboration, compatibility, and onboarding.

12 Laravel security best practices for 2024

Secure your Laravel app: protect sensitive files, keep your packages and Laravel updated, use policies, validate input, and more.

A complete history of Laravel's versions (2011-2024)

What's the current version of Laravel? Is there any LTS release you can rely on? And what about the history of the framework? Let's find out!

- / -