awjudd/maintenance-mode

An enhanced maintenance mode for Laravel.

Enhanced Laravel Maintenance Mode

This package is a drop-in replacement for Laravel's maintenance mode. The following versions are supported:

• Laravel 5.0 - 5.2, please use the 1.0 branch.
• There are currently no plans to support Laravel 5.3 - 5.4.
• Laravel 5.5 - 5.8, please use the 1.3 branch
• Laravel 6.0, please use the 2.0 branch. Note that 5.5+ can work with the 2.0 branch, but it is not guaranteed to be backwards compatible.

Features include:

• Allowing custom maintenance messages to be shown to users
• Including a timestamp of when the application went down
• Exempting select users via custom exemption classes
• Firing an event for when the application goes down
• Dynamically selecting the view to be shown on down command

Table of Contents

1. Installation
2. Changes from 1.0
3. Usage
4. Configuration 1. Default Configuration 1. Overriding Defaults
5. Exemptions 1. Default Exemptions
   1. IP Whitelist
   2. Environment Whitelist 1. Creating a New Exemption
6. Views 1. Application Down 1. Maintenance Notification
7. Events

Installation

Run the following command to install the latest:

$ composer require "misterphilip/maintenance-mode:~2.0"

Or, if you prefer installing it manually, within composer.json add the following line to the end of the require section:

"misterphilip/maintenance-mode": "~2.0"

And then run the Composer install command:

$ composer install

Laravel should automatically install the Service Providers, but verify they exist within the config/app.php file. If they do not, add MisterPhilip\MaintenanceMode\MaintenanceModeServiceProvider::class, and MisterPhilip\MaintenanceMode\MaintenanceCommandServiceProvider::class, to the end of the $providers array in your config/app.php:

'providers' => [

    /*
     * Application Service Providers...
     */
     App\Providers\AppServiceProvider::class,
     App\Providers\EventServiceProvider::class,
     App\Providers\RouteServiceProvider::class,

     ...

     MisterPhilip\MaintenanceMode\MaintenanceModeServiceProvider::class,
     MisterPhilip\MaintenanceMode\MaintenanceCommandServiceProvider::class,
],

Finally, in app/Http/Kernel.php replace the current MaintenanceMode Middleware

\Illuminate\Foundation\Http\Middleware\CheckForMaintenanceMode::class,

with

\MisterPhilip\MaintenanceMode\Http\Middleware\CheckForMaintenanceMode::class,

Changes from 1.0

Since Laravel 5.3, messages are now allowed in the default artisan down command, as well as adding an option for the Retry-After HTTP header. Because of this it should be noted that the syntax to call the artisan down command has changed from the 1.0 branch to better match Laravel's default command.

Additionally, we've changed the MaintenanceModeEnabled event to no longer use the info property, but instead have separate properties for each piece of information. See more in the events section.

Usage

This package overwrites the default artisan down command, with more options:

$ php artisan down [--message=MESSAGE] [--retry=RETRY] [--view=VIEW] [--allow*=ALLOW]

For example,

$ php artisan down --message="We're currently upgrading our system! Please check back later."

would show users a message of "We're doing some routine maintenance! Be back soon!". If you don't pass in a message, the default "We're currently working on the site, please try again later" will display to the users. Of course this default is configurable via a language string.

You can also change the view that is shown each time you run the artisan down command via the --view=[VIEW] option:

$ php artisan down --message="Be back in a few!" --view="errors/maintenance"

And of course you can use the default --retry option as well:

$ php artisan down --message="Be back in a few!" --view="errors/maintenance" --retry=60

To bring your application back online, run the normal app up command:

$ php artisan up

NOTE: by default, two exemptions enabled, which means that if you run your development server locally (127.0.0.1) or you have APP_ENV=local in your .env file, you will not see the maintenance page. You can remove these exemptions via the configuration.

Configuration

This package is a drop-in replacement for the default maintenance mode provided with Laravel 5. This means that you do not have to do any configuration out-of-the-box. However, if you'd like to tweak some of the settings, there are a number of configuration values that are available to make this package a better fit for your application.

Default Configuration

Below are the default configuration options and a short description on each. Don't worry, all of this information is within the configuration file too!

• view (string)
  • The view to show to users when maintenance mode is currently enabled. This can be temporarily overridden when the command is called via the --view option
  • Defaults to maintenancemode::app-down
• notification-styles (boolean)
  • Include CSS styling with the optional maintenance notification view
  • Defaults to true
• inject.global (boolean)
  • Enable or disable global visibility to maintenance mode variables (accessible in all views)
  • Defaults to true
• inject.prefix (string)
  • Prefix the maintenance mode variables to prevent view variable name collisions
  • Defaults to MaintenanceMode
• language-path (string)
  • The path to the maintenance mode language strings.
  • Defaults to maintenancemode::defaults
• exempt-ips (string array)
  • An array of IP address that will always be exempt from the application down page
  • Defaults to ['127.0.0.1']
• exempt-ips-proxy (boolean)
  • Use proxies to get the user's IP address
  • Defaults to false
• exempt-environments (string array)
  • An array of environment names that will always be exempt from the application down page
  • Defaults to ['local']
• exemptions (string array)
  • A list of the exemption classes to execute. See Exemptions
  • Defaults to:

    '\MisterPhilip\MaintenanceMode\Exemptions\IPWhitelist',
    '\MisterPhilip\MaintenanceMode\Exemptions\EnvironmentWhitelist',

Overriding Defaults

If you need to override the default configuration values, run the following command:

$ php artisan vendor:publish --provider="MisterPhilip\MaintenanceMode\MaintenanceModeServiceProvider" --tag="config"

Now you can edit the values at config/maintenancemode.php.

Exemptions

Exemptions allow for select users to continue to use the application like normal based on a specific set of rules. Each of these rule sets are defined via a class which is then executed against.

Default Exemptions

By default, an IP whitelist and an application environment whitelist are included with this package to get you off the ground running. Additionally, more examples are provided for various types of exemptions that might be useful to your application.

IP Whitelist

This exemption allows you to check the user's IP address against a whitelist. This is useful for always including your office IP(s) so that your staff doesn't see the maintenance page. This is similar to the allow option that is offered in Laravel 5.6+ (and is backported to 5.5 with this package), however the allow option requires you to pass the IPs every time, vs. this method allows for you to have IPs stored in the configuration. Both methods can be used with each other, e.g. a static internal network should always be allowed via the config, while an additional IP for a vendor or remote employee can temporarily be added via the allow option.

Configuration values included with this exemption are:

• exempt-ips - An array of IP addresses that will not see the maintenance page
• exempt-ips-proxy - Set to true if you have IP proxies setup

Environment Whitelist

This exemption allows you to check if the current environment matches against a whitelist. This is useful for local development where you might not want to see the maintenance page.

Configuration values included with this exemption are:

• exempt-environments - An array of environments that will not display the maintenance page

Creating a new exemption

Setting up a new exemption is simple:

1. Create a new class and extend MisterPhilip\MaintenanceMode\Exemptions\MaintenanceModeExemption. You might consider creating these files in app\Exemptions or app\Infrastructure\Maintenance, but you're free to place them where you want.
2. This class must include an isExempt method. This method should return true if the user should not see the maintenance page. If this returns false, it indicates that the user does not match your ruleset and other exceptions should be checked.
3. Add the full class name to the exemptions array in the configuration file.

Below is an template to use for a new exemption class SampleExemption:

<?php namespace App\Exemptions;

use MisterPhilip\MaintenanceMode\Exemptions\MaintenanceModeExemption;

class SampleExemption extends MaintenanceModeExemption
{
    /**
     * Execute the exemption check
     *
     * @return bool
     */
    public function isExempt()
    {
        return true; // or false
    }
}

Views

There are 2 views included with this package: an "application down" page that replaces the current "Be right back!" page, and a "maintenance notification" which is a notification bar that tells exempted users that the application is in maintenance mode.

You can also publish these views so that you can edit them easily. The command below will publish the views to resources/views/vendor/maintenancemode/*. Once published be sure to change the config values (view) to point to the new file location.

$ php artisan vendor:publish --provider="MisterPhilip\MaintenanceMode\MaintenanceModeServiceProvider" --tag="views"

Application Down

The default maintenance page, maintenancemode::app-down

Included is a default view that displays your custom message and a timestamp for your users. To change this page, update the view configuration value to point to the new view. The following variables are available for you to use:

• $MaintenanceModeEnabled - Check to see if the maintenance mode is enabled
• $MaintenanceModeMessage - The message that should be displayed to users (either the one passed via the command call, or the default from the language file)
• $MaintenanceModeTimestamp - The timestamp from when the application went into maintenance mode

NOTE: If you've changed the inject.prefix configuration value, you'll need to reflect this change in the variable names above. For example, if inject.prefix = "Foobar", your view variables would be $FoobarEnabled, $FoobarMessage, and $FoobarTimestamp.

NOTE: By default, these variables are available in all views. To disable this functionality and have it only inject variables on the maintenance page, change the inject.global configuration value to false.

You can also temporarily override the view shown by passing in the --view option when calling the artisan down command. E.g. if you wanted to use the default errors/503.blade.php view, you could call:

$ php artisan down --view="error/503"

Maintenance Notification

The optional maintenance notification, maintenancemode::notification

We've included a maintenance notification for users that want to include a notice to those that are exempt from seeing the maintenance page. We've found that as an admin, it's helpful to know when your application is in maintenance mode in the event that you've forgotten to disable it or it was turned on automatically.

You can enable this notification by placing the following code within your main blade layouts file(s):

@include('maintenancemode::notification')

Events

This package fires an event, MisterPhilip\MaintenanceMode\Events\MaintenanceModeEnabled, whenever the application goes down for maintenance, and MisterPhilip\MaintenanceMode\Events\MaintenanceModeDisabled when it is brought back up. You can add your own listeners in your events Service Provider. By default this is located at app/providers/EventServiceProvider.php. You can find several example listeners in the events examples, including logging when the application went down or up, and updating Statuspage via the checkitonus/php-statuspage-sdk package.

protected $listen = [
    'MisterPhilip\MaintenanceMode\Events\MaintenanceModeEnabled' => [
        'App\Listeners\UpdateStatusPageMaintenanceStarted',
    ],
    'MisterPhilip\MaintenanceMode\Events\MaintenanceModeDisabled' => [
        'App\Listeners\UpdateStatusPageMaintenanceEnded',
    ],
    // ..
];

The original message, time the app went down, retry length, view, and allowed are all properties available on both events.

maintenance-mode's Issues

Laravel 5.8 removed --allow option

is there a way to use this option with our package. I have installed it but its not working. none of your --options are available. Can you please let me know if its compatible with Laravel 5.8 +

Thank you

Allow HTML?

Hi there - thanks for a handy library! Would it be possible to allow HTML in future versions? Would love to be able to link up the email address used in the down message.

support laravel 5.4.8 not installable

I am unable to install for laravel 5.4.8 in my project saying:
** Installation request for laravel/framework (locked at v5.4.8, required as 5.4.*) -> satisfiable by laravel/framework[v5.4.8].
- Installation request for misterphilip/maintenance-mode ^1.0 -> satisfiable by misterphilip/maintenance-mode[1.0.0, 1.0.1, 1.0.2, 1.0.3].**

Currently uses L4 configuration method?

I notice the package is currently using the config file path structure of Laravel 4. publish:config isn't a thing any more unfortunately and the way things are generally done now with configuration files is by having say, maintenancemode.php in the root config folder and then environment-specific things are put in the env file.

Any plans to change to this new method?

No hint path defined for [maintenancemode].

Installed and added lines to kernel and config.php like instructed.
using laravel 5.0.31. Tried to solve this but no succes.

InvalidArgumentException in FileViewFinder.php line 112:
No hint path defined for [maintenancemode].

in FileViewFinder.php line 112
at FileViewFinder->getNamespaceSegments('maintenancemode::app-down') in FileViewFinder.php line 88
at FileViewFinder->findNamedPathView('maintenancemode::app-down') in FileViewFinder.php line 74
at FileViewFinder->find('maintenancemode::app-down') in Factory.php line 145
at Factory->make('maintenancemode::app-down', array('MaintenanceModeEnabled' => true, 'MaintenanceModeTimestamp' => object(Carbon), 'MaintenanceModeMessage' => 'maintenancemode::defaults..message'), array()) in helpers.php line 591
at view('maintenancemode::app-down', array('MaintenanceModeEnabled' => true, 'MaintenanceModeTimestamp' => object(Carbon), 'MaintenanceModeMessage' => 'maintenancemode::defaults..message')) in CheckForMaintenanceMode.php line 132
at CheckForMaintenanceMode->handle(object(Request), object(Closure)) in Pipeline.php line 125
at Pipeline->Illuminate\Pipeline{closure}(object(Request))
at call_user_func(object(Closure), object(Request)) in Pipeline.php line 101
at Pipeline->then(object(Closure)) in Kernel.php line 115
at Kernel->sendRequestThroughRouter(object(Request)) in Kernel.php line 84
at Kernel->handle(object(Request)) in index.php line 53

Call to undefined method Illuminate\Events\Dispatcher::fire()

Package Version: 1.3.*
Laravel Version: 5.8

When running the artisan command:

php artisan down/up

the following error is displayed:

Call to undefined method Illuminate\Events\Dispatcher::fire()

According to this issue

In versions prior to Laravel 5.7, this method class name was fire but with Laravel 5.8, it is now dispatch.

In StartMaintenanceCommand.php change line 53 from:

Event::fire(new MaintenanceModeEnabled($payload['time'], $payload['message'], $payload['view'], $payload['retry'], $payload['allowed']));

To

Event::dispatch(new MaintenanceModeEnabled($payload['time'], $payload['message'], $payload['view'], $payload['retry'], $payload['allowed']));

And in EndMaintenanceCommand.php line 47 from:

Event::fire(new MaintenanceModeDisabled($data['time'], $data['message'], $data['view'], $data['retry']));

To

Event::dispatch(new MaintenanceModeDisabled($data['time'], $data['message'], $data['view'], $data['retry']));

These changes resolve the problem in the command line.

Laravel 5.3

Hi again! Do you know when you might be able to update this for Laravel 5.3? (I know it was just announced today, so not trying to be a pest, just curious. I can't upgrade my app to 5.3 because of this dependency, so looking forward to a new version.)

Also, is there anything I can do to help get you there faster?

role based exemptions

is that possible to exempt users by their roles instead of IP address?

Let say allow everyone with role Admin have access during down time and anyone else just see the error page.

Is that possible?

Incorrect IP when in maintenance mode

Laravel 5.5
Site is behind proxy

When using https://github.com/fideloper/TrustedProxy I get 2 different IP addresses

When the site is up, I get the correct IP inside a normal controller using $request->getClientip()

When I put the site into maintenence and look at the IP from https://github.com/MisterPhilip/maintenance-mode/blob/master/src/MisterPhilip/MaintenanceMode/Exemptions/IPWhitelist.php#L25 I get the proxy ip. I was expecting the same IP as $request->getClientip()

L5.5 $this->app['auth']->user() returning NULL

I'm trying to make an exemption to the Auth user but $this->app['auth']->user() is returning me NULL

my class is inside App\Exemptions

<?php
namespace App\Exemptions;

use Auth, Config;
use MisterPhilip\MaintenanceMode\Exemptions\MaintenanceModeExemption;

/**
 * Class AdminRule
 *
 * Checks to see if the user have the 'Admin' role
 */
class AdminRule extends MaintenanceModeExemption
{
    /**
     * Execute the exemption check
     *
     * @return bool
     */
    public function isExempt()
    {
        dd($this->app['auth']->user());
        return true;
    }
}

my maintenancemode.php exemptions array looks like this:

'exemptions' => [

        /*
         * IPWhitelist exempts users with the IPs matched in the "exempt-ips" config
         */
//        MisterPhilip\MaintenanceMode\Exemptions\IPWhitelist::class,

        /*
         * EnvironmentWhitelist exempts installations with environments matched in the "exempt-environments" config
         */
//        MisterPhilip\MaintenanceMode\Exemptions\EnvironmentWhitelist::class,

        /*
         * AdminRule exempts users who have the role 'Admin'
         */
        App\Exemptions\AdminRule::class,
    ],

I've commented MisterPhilip\MaintenanceMode\Exemptions\IPWhitelist::class, and MisterPhilip\MaintenanceMode\Exemptions\EnvironmentWhitelist::class, just for test purposes

Laravel: 5.5.44
PHP: 7.2.10

Thanks!

Don't turn down de app

The app don't turn down when launh php artisan down, all like good, but app don't out of service!

Cannot install on Laravel 5.8 "Conclusion: remove nesbot/carbon 2.16.0"

Hi,

I'm on Laravel 5.8, when trying to install this package I have an error related to the version of Carbon (see attached screenshot)

Thanks for help!

Suggestion: Fire an event that can be hooked into

Just a thought, an event that fires when you take the site down would be really handy. As far as I know Laravel doesn't have one by default, but it could allow sites that run mostly via web sockets to send off a "site shutting down" message to users, that kind of thing.

Support for Laravel 5.7

As the title suggests, love your package but need support for it for Laravel 5.7

-Thanks

ip exclude not working

i put my ip like

'exempt-ips' => ['123.88.456.157'],

but i still see the maintenance mode

Update based off of Taylor's recent commits

Wait for completion of package development before fixing

Add support for Laravel 6.0

Exception index 'view' not found

In CheckForMaintenanceMode.php the above error is thrown at line 104. Viewing in debug mode there is no view index in the $data array.

Adding

if( ! isset($data['view']))
{
$data['view'] = $this->app['config']->get('maintenance mode.view');
}

after line 80 cures the problem.

Possible

It is possible to have a subscribe form on the maintenance mode? If yes how?