{"id":13669240,"url":"https://github.com/awjudd/maintenance-mode","last_synced_at":"2025-04-06T03:09:02.578Z","repository":{"id":23906974,"uuid":"27287014","full_name":"awjudd/maintenance-mode","owner":"awjudd","description":"An enhanced maintenance mode for Laravel.","archived":false,"fork":false,"pushed_at":"2020-03-15T11:33:17.000Z","size":180,"stargazers_count":120,"open_issues_count":0,"forks_count":21,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-11-13T13:03:14.037Z","etag":null,"topics":["laravel","laravel-5-package","laravel-package","laravel5","maintenance-mode","maintenance-page","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awjudd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-11-29T00:46:01.000Z","updated_at":"2024-07-12T14:21:16.000Z","dependencies_parsed_at":"2022-08-22T11:31:19.215Z","dependency_job_id":null,"html_url":"https://github.com/awjudd/maintenance-mode","commit_stats":null,"previous_names":["misterphilip/maintenance-mode"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awjudd%2Fmaintenance-mode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awjudd%2Fmaintenance-mode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awjudd%2Fmaintenance-mode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awjudd%2Fmaintenance-mode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awjudd","download_url":"https://codeload.github.com/awjudd/maintenance-mode/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427006,"owners_count":20937201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["laravel","laravel-5-package","laravel-package","laravel5","maintenance-mode","maintenance-page","php"],"created_at":"2024-08-02T08:01:07.334Z","updated_at":"2025-04-06T03:09:02.562Z","avatar_url":"https://github.com/awjudd.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# Enhanced Laravel Maintenance Mode\n\nThis package is a drop-in replacement for Laravel's maintenance mode. The following versions are supported: \n\n* Laravel 5.0 - 5.2, please use the [1.0 branch](https://github.com/MisterPhilip/maintenance-mode/tree/1.0). \n* There are currently no plans to support Laravel 5.3 - 5.4. \n* Laravel 5.5 - 5.8, please use the [1.3 branch](https://github.com/MisterPhilip/maintenance-mode/tree/1.3)\n* Laravel 6.0, please use the [2.0 branch](https://github.com/MisterPhilip/maintenance-mode/tree/2.0). Note that 5.5+ \n_can_ work with the 2.0 branch, but it is not guaranteed to be backwards compatible. \n\n\nFeatures include:\n - Allowing custom maintenance messages to be shown to users\n - Including a timestamp of when the application went down\n - Exempting select users via custom exemption classes\n - Firing an event for when the application goes down\n - Dynamically selecting the view to be shown on down command\n\n## Table of Contents\n\n  1. [Installation](#installation)\n  1. [Changes from 1.0](#changes-from-1.0)\n  1. [Usage](#usage)\n  1. [Configuration](#configuration)\n    1. [Default Configuration](#default-configuration)\n    1. [Overriding Defaults](#overriding-defaults)\n  1. [Exemptions](#exemptions)\n    1. [Default Exemptions](#default-exemptions)\n      1. [IP Whitelist](#ip-whitelist)\n      1. [Environment Whitelist](#environment-whitelist)\n    1. [Creating a New Exemption](#creating-a-new-exemption)\n  1. [Views](#views)\n    1. [Application Down](#application-down)\n    1. [Maintenance Notification](#maintenance-notification)\n  1. [Events](#events)\n\n## Installation\n\nRun the following command to install the latest:\n```bash\n$ composer require \"misterphilip/maintenance-mode:~2.0\"\n```\n\nOr, if you prefer installing it manually, within `composer.json` add the following line to the end of the `require` section:\n\n```json\n\"misterphilip/maintenance-mode\": \"~2.0\"\n```\n\nAnd then run the Composer install command:\n\n```bash\n$ composer install\n```\n\nLaravel _should_ automatically install the Service Providers, but verify they exist within the `config/app.php` file.\nIf they do not, add `MisterPhilip\\MaintenanceMode\\MaintenanceModeServiceProvider::class,` and\n`MisterPhilip\\MaintenanceMode\\MaintenanceCommandServiceProvider::class,` to the end of the\n`$providers` array in your `config/app.php`:\n\n```php\n'providers' =\u003e [\n\n    /*\n     * Application Service Providers...\n     */\n     App\\Providers\\AppServiceProvider::class,\n     App\\Providers\\EventServiceProvider::class,\n     App\\Providers\\RouteServiceProvider::class,\n\n     ...\n\n     MisterPhilip\\MaintenanceMode\\MaintenanceModeServiceProvider::class,\n     MisterPhilip\\MaintenanceMode\\MaintenanceCommandServiceProvider::class,\n],\n```\n\nFinally, in `app/Http/Kernel.php` replace the current MaintenanceMode Middleware\n\n```php\n\\Illuminate\\Foundation\\Http\\Middleware\\CheckForMaintenanceMode::class,\n```\n\nwith\n\n```php\n\\MisterPhilip\\MaintenanceMode\\Http\\Middleware\\CheckForMaintenanceMode::class,\n```\n\n\n## Changes from 1.0\n\nSince Laravel 5.3, messages are now allowed in the default `artisan down` command, as well as adding an option for the\n`Retry-After` HTTP header. Because of this it should be noted that the syntax to call the `artisan down` command has\nchanged from the 1.0 branch to better match Laravel's default command.\n\nAdditionally, we've changed the\n`MaintenanceModeEnabled` event to no longer use the `info` property, but instead have separate properties for each piece\nof information. See more in the [events section](#events).\n\n## Usage\n\nThis package overwrites the default `artisan down` command, with more options:\n\n```bash\n$ php artisan down [--message=MESSAGE] [--retry=RETRY] [--view=VIEW] [--allow*=ALLOW]\n```\n\nFor example,\n\n```bash\n$ php artisan down --message=\"We're currently upgrading our system! Please check back later.\"\n```\n\nwould show users a message of \"We're doing some routine maintenance! Be back soon!\". If you don't pass in a\nmessage, the default \"We're currently working on the site, please try again later\" will\ndisplay to the users. Of course this default is configurable via a language string.\n\nYou can also change the view that is shown each time you run the `artisan down` command via the `--view=[VIEW]` option:\n\n```bash\n$ php artisan down --message=\"Be back in a few!\" --view=\"errors/maintenance\"\n```\n\nAnd of course you can use the default `--retry` option as well:\n\n```bash\n$ php artisan down --message=\"Be back in a few!\" --view=\"errors/maintenance\" --retry=60\n```\n\nTo bring your application back online, run the normal app up command:\n\n```bash\n$ php artisan up\n```\n\n**NOTE:** by default, two [exemptions](#exemptions) enabled, which means that if you run\nyour development server locally (127.0.0.1) _or_ you have `APP_ENV=local` in your `.env` file, you will _not_ see the\nmaintenance page. You can remove these exemptions via the [configuration](#overriding-defaults).\n\n## Configuration\n\nThis package is a drop-in replacement for the default maintenance mode provided with Laravel 5. This means\nthat you do not have to do any configuration out-of-the-box. However, if you'd like to tweak some of the\nsettings, there are a number of configuration values that are available to make this package a better fit\nfor your application.\n\n### Default Configuration\n\nBelow are the default configuration options and a short description on each. Don't worry, all of this\ninformation is within the configuration file too!\n\n  - `view` (string)\n    - The view to show to users when maintenance mode is currently enabled. This can be temporarily overridden when\n    the command is called via the `--view` option\n    - Defaults to `maintenancemode::app-down`\n  - `notification-styles` (boolean)\n    - Include CSS styling with the optional [maintenance notification](#maintenance-notification) view\n    - Defaults to `true`\n  - `inject.global` (boolean)\n    - Enable or disable global visibility to maintenance mode variables (accessible in all views)\n    - Defaults to `true`\n  - `inject.prefix` (string)\n    - Prefix the maintenance mode variables to prevent view variable name collisions\n    - Defaults to `MaintenanceMode`\n  - `language-path` (string)\n    - The path to the maintenance mode language strings.\n    - Defaults to `maintenancemode::defaults`\n  - `exempt-ips` (string array)\n    - An array of IP address that will always be exempt from the application down page\n    - Defaults to `['127.0.0.1']`\n  - `exempt-ips-proxy` (boolean)\n    - Use [proxies](http://symfony.com/doc/current/components/http_foundation/trusting_proxies.html)\n    to get the user's IP address\n    - Defaults to `false`\n  - `exempt-environments` (string array)\n    - An array of environment names that will always be exempt from the application down page\n    - Defaults to `['local']`\n  - `exemptions` (string array)\n    - A list of the exemption classes to execute. *See [Exemptions](#exemptions)*\n    - Defaults to:\n```php\n    '\\MisterPhilip\\MaintenanceMode\\Exemptions\\IPWhitelist',\n    '\\MisterPhilip\\MaintenanceMode\\Exemptions\\EnvironmentWhitelist',\n```\n\n### Overriding Defaults\n\nIf you need to override the default configuration values, run the following command:\n\n```bash\n$ php artisan vendor:publish --provider=\"MisterPhilip\\MaintenanceMode\\MaintenanceModeServiceProvider\" --tag=\"config\"\n```\n\nNow you can edit the values at `config/maintenancemode.php`.\n\n## Exemptions\n\nExemptions allow for select users to continue to use the application like normal based on a specific\nset of rules. Each of these rule sets are defined via a class which is then executed against.\n\n### Default Exemptions\n\nBy default, an IP whitelist and an application environment whitelist are included with this package\nto get you off the ground running. Additionally, more examples are provided for various types of\nexemptions that might be useful to your application.\n\n##### IP Whitelist\n\nThis exemption allows you to check the user's IP address against a whitelist. This is useful for\nalways including your office IP(s) so that your staff doesn't see the maintenance page. This is similar\nto the `allow` option that is offered in Laravel 5.6+ (and is backported to 5.5 with this package), however\nthe `allow` option requires you to pass the IPs every time, vs. this method allows for you to have IPs stored\nin the configuration. Both methods can be used with each other, e.g. a static internal network should always be\nallowed via the config, while an additional IP for a vendor or remote employee can temporarily be added via the\n`allow` option.\n\nConfiguration values included with this exemption are:\n\n  - `exempt-ips` - An array of IP addresses that will not see the maintenance page\n  - `exempt-ips-proxy` - Set to `true` if you have IP proxies setup\n\n##### Environment Whitelist\n\nThis exemption allows you to check if the current environment matches against a whitelist. This is\nuseful for local development where you might not want to see the maintenance page.\n\nConfiguration values included with this exemption are:\n\n  - `exempt-environments` - An array of environments that will not display the maintenance page\n\n### Creating a new exemption\n\nSetting up a new exemption is simple:\n\n  1. Create a new class and extend `MisterPhilip\\MaintenanceMode\\Exemptions\\MaintenanceModeExemption`.\n  You might consider creating these files in `app\\Exemptions` or `app\\Infrastructure\\Maintenance`, but\n  you're free to place them where you want.\n  2. This class must include an `isExempt` method. This method should return `true` if the user should\n  not see the maintenance page. If this returns `false`, it indicates that the user does not match\n  your ruleset and other exceptions should be checked.\n  3. Add the full class name to the `exemptions` array in the configuration file.\n\nBelow is an template to use for a new exemption class `SampleExemption`:\n\n```php\n\u003c?php namespace App\\Exemptions;\n\nuse MisterPhilip\\MaintenanceMode\\Exemptions\\MaintenanceModeExemption;\n\nclass SampleExemption extends MaintenanceModeExemption\n{\n    /**\n     * Execute the exemption check\n     *\n     * @return bool\n     */\n    public function isExempt()\n    {\n        return true; // or false\n    }\n}\n```\n\n## Views\n\nThere are 2 views included with this package: an \"application down\" page that replaces the current \"Be\nright back!\" page, and a \"maintenance notification\" which is a notification bar that tells exempted users\nthat the application is in maintenance mode.\n\nYou can also publish these views so that you can edit them easily. The command below will publish the views\nto `resources/views/vendor/maintenancemode/*`. Once published be sure to change the config values (`view`)\nto point to the new file location.\n\n```bash\n$ php artisan vendor:publish --provider=\"MisterPhilip\\MaintenanceMode\\MaintenanceModeServiceProvider\" --tag=\"views\"\n```\n\n### Application Down\n\n![Default maintenance page](examples/screenshots/maintenance-mode-page.png \"Default maintenance page\")\n*The default maintenance page, `maintenancemode::app-down`*\n\nIncluded is a default view that displays your custom message and a timestamp for your users. To change this page,\nupdate the `view` configuration value to point to the new view. The following variables are available for\nyou to use:\n\n  - `$MaintenanceModeEnabled` - Check to see if the maintenance mode is enabled\n  - `$MaintenanceModeMessage` - The message that should be displayed to users (either the one passed via\n  the command call, or the default from the language file)\n  - `$MaintenanceModeTimestamp` - The timestamp from when the application went into maintenance mode\n\n**NOTE**: If you've changed the `inject.prefix` configuration value, you'll need to reflect this change in the\nvariable names above. For example, if `inject.prefix = \"Foobar\"`, your view variables would be `$FoobarEnabled`,\n`$FoobarMessage`, and `$FoobarTimestamp`.\n\n**NOTE**: By default, these variables are available in all views. To disable this functionality and have it\nonly inject variables on the maintenance page, change the `inject.global` configuration value to `false`.\n\nYou can also temporarily override the view shown by passing in the `--view` option when calling the `artisan down`\ncommand. E.g. if you wanted to use the default `errors/503.blade.php` view, you could call:\n\n```bash\n$ php artisan down --view=\"error/503\"\n```\n\n### Maintenance Notification\n\n![Maintenance notification](examples/screenshots/maintenance-mode-notification.png \"Maintenance notification\")\n*The optional maintenance notification, `maintenancemode::notification`*\n\nWe've included a maintenance notification for users that want to include a notice to those that are exempt\nfrom seeing the maintenance page. We've found that as an admin, it's helpful to know when your application\nis in maintenance mode in the event that you've forgotten to disable it or it was turned on automatically.\n\nYou can enable this notification by placing the following code within your main blade layouts file(s):\n\n```php\n@include('maintenancemode::notification')\n```\n\n## Events\n\nThis package [fires an event](https://laravel.com/docs/master/events),\n`MisterPhilip\\MaintenanceMode\\Events\\MaintenanceModeEnabled`, whenever the application goes down for maintenance,\nand `MisterPhilip\\MaintenanceMode\\Events\\MaintenanceModeDisabled` when it is brought back up. You can add your own\nlisteners in your events Service Provider. By default this is located at `app/providers/EventServiceProvider.php`.\nYou can find several example listeners in the [events examples](examples/events), including logging when the\napplication went down or up, and updating [Statuspage](https://www.statuspage.io) via the\n[checkitonus/php-statuspage-sdk](https://github.com/checkitonus/php-statuspage-sdk) package.\n\n```php\nprotected $listen = [\n    'MisterPhilip\\MaintenanceMode\\Events\\MaintenanceModeEnabled' =\u003e [\n        'App\\Listeners\\UpdateStatusPageMaintenanceStarted',\n    ],\n    'MisterPhilip\\MaintenanceMode\\Events\\MaintenanceModeDisabled' =\u003e [\n        'App\\Listeners\\UpdateStatusPageMaintenanceEnded',\n    ],\n    // ..\n];\n```\n\nThe original `message`, `time` the app went down, `retry` length, `view`, and `allowed` are all properties available on both events.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawjudd%2Fmaintenance-mode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawjudd%2Fmaintenance-mode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawjudd%2Fmaintenance-mode/lists"}