PHPackages axvi/laravel-maintenance - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. axvi/laravel-maintenance ActiveLibrary[Utility & Helpers](/categories/utility) axvi/laravel-maintenance ======================== Advanced maintenance mode management for Laravel — IP whitelisting, named bypass tokens, scheduled windows, and more. v1.0.1(3w ago)021MITPHPPHP ^8.1CI passing Since Mar 5Pushed 5mo agoCompare [ Source](https://github.com/axvilab/laravel-maintenance)[ Packagist](https://packagist.org/packages/axvi/laravel-maintenance)[ Docs](https://github.com/axvilab/laravel-maintenance)[ RSS](/packages/axvi-laravel-maintenance/feed)WikiDiscussions master Synced 1w ago READMEChangelog (1)Dependencies (16)Versions (3)Used By (0) axvi/laravel-maintenance ======================== [](#axvilaravel-maintenance) > Advanced maintenance mode management for Laravel 10, 11 and 12. [![Latest Version on Packagist](https://camo.githubusercontent.com/beac0a57c56591132197ed8c92e507c9150c41f511b9b0ec892b32cc6067f793/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f617876692f6c61726176656c2d6d61696e74656e616e63652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/axvi/laravel-maintenance)[![License](https://camo.githubusercontent.com/8cc23c0c4edbd0ef95d5e6687330fe0a615a7872d95a4eb42e5746b6dd9dd89c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f617876692f6c61726176656c2d6d61696e74656e616e63652e7376673f7374796c653d666c61742d737175617265)](LICENSE.md) Features -------- [](#features) - IP address whitelisting with optional expiration - Multiple named bypass tokens (cookie for web, header for APIs, URL bypass) - Scheduled maintenance windows with auto-disable - Beautiful, customizable 503 page with countdown timer - Database-driven — works seamlessly across multiple servers - Built-in cache layer — avoids DB queries on every request - Exclude paths from maintenance (health checks, webhooks, etc.) - Configurable database connection and table names - Artisan commands for full CLI management - Events: `MaintenanceModeEnabled`, `MaintenanceModeDisabled`, `MaintenanceBypassGranted` - Automatically replaces Laravel's built-in maintenance middleware Requirements ------------ [](#requirements) PHP 8.1PHP 8.2PHP 8.3PHP 8.4PHP 8.5**Laravel 10**yesyesyesyes—**Laravel 11**—yesyesyesyes**Laravel 12**—yesyesyesyesInstallation ------------ [](#installation) ``` composer require axvi/laravel-maintenance ``` Run migrations: ``` php artisan migrate ``` Migrations are loaded automatically. If you need to customize them: ``` php artisan vendor:publish --tag=maintenance-migrations ``` Optionally publish the config: ``` php artisan vendor:publish --tag=maintenance-config ``` Optionally publish the 503 view: ``` php artisan vendor:publish --tag=maintenance-views ``` Configuration ------------- [](#configuration) After publishing, the config file is located at `config/maintenance.php`: ``` return [ // Database connection (null = default) 'connection' => env('MAINTENANCE_DB_CONNECTION', null), // Customize table names 'tables' => [ 'settings' => 'maintenance_settings', 'ips' => 'maintenance_ips', 'tokens' => 'maintenance_tokens', ], // Cache maintenance state to avoid DB queries on every request 'cache' => [ 'enabled' => true, 'store' => null, // null = default cache store 'ttl' => 60, // seconds ], // URL patterns that should never be blocked by maintenance mode 'except' => [ // 'api/health', // 'webhook/*', ], // Bypass route settings 'bypass_route' => [ 'enabled' => true, 'prefix' => 'maintenance', // GET /maintenance/{token} ], // Middleware settings 'middleware' => [ 'cookie_name' => 'laravel_maintenance', 'cookie_lifetime' => 43200, // minutes (12 hours) 'header_name' => 'X-Maintenance-Token', ], // Response settings 'response' => [ 'status' => 503, 'retry_after' => 60, 'refresh' => null, 'view' => 'maintenance::503', ], ]; ``` Usage ----- [](#usage) ### Enable maintenance mode [](#enable-maintenance-mode) ``` # Basic php artisan maintenance:down # With message, IP whitelist and secret token php artisan maintenance:down \ --message="We'll be back in 30 minutes" \ --allow=192.168.1.1 \ --secret=my-secret-token \ --ends-at="2025-01-01 03:00:00" ``` ### Disable maintenance mode [](#disable-maintenance-mode) ``` php artisan maintenance:up ``` ### Check status [](#check-status) ``` php artisan maintenance:status ``` ### Manage IPs [](#manage-ips) ``` php artisan maintenance:ip add 192.168.1.50 --label="Dev machine" php artisan maintenance:ip add 10.0.0.1 --expires-at="2025-06-01 00:00:00" php artisan maintenance:ip remove 192.168.1.50 php artisan maintenance:ip list ``` ### Manage tokens [](#manage-tokens) ``` # Add with auto-generated UUID token php artisan maintenance:token add dev-token # Add with explicit token value php artisan maintenance:token add dev-token abc123 # Add with expiration php artisan maintenance:token add temp-token --expires-at="2025-06-01 00:00:00" php artisan maintenance:token revoke dev-token php artisan maintenance:token list ``` ### Bypass methods [](#bypass-methods) **URL bypass (web)** Visit `https://yourapp.com/maintenance/{secret-token}` — sets a bypass cookie valid for 12 hours. The route prefix is configurable via `bypass_route.prefix` in the config. You can also disable URL bypass entirely by setting `bypass_route.enabled` to `false`. **Header bypass (API)** ``` X-Maintenance-Token: my-secret-token ``` The header name is configurable via `middleware.header_name` in the config. ### Exclude paths [](#exclude-paths) Some URLs should always be accessible, even during maintenance. Add patterns to the `except` array: ``` 'except' => [ 'api/health', 'webhook/*', 'telescope*', ], ``` Supports wildcards via Laravel's `Request::is()`. ### Caching [](#caching) By default, the package caches the maintenance state and IP whitelist to avoid database queries on every HTTP request. The cache is automatically invalidated when you enable/disable maintenance or modify the IP whitelist. To disable caching: ``` 'cache' => [ 'enabled' => false, ], ``` To use a specific cache store (e.g. Redis): ``` 'cache' => [ 'enabled' => true, 'store' => 'redis', 'ttl' => 30, ], ``` ### Programmatic usage [](#programmatic-usage) ``` use Axvi\Maintenance\Facades\Maintenance; // Check status Maintenance::isDown(); // Enable / disable Maintenance::enable([ 'message' => 'Deploying v2.0', 'retry_after' => 120, 'ends_at' => '2025-01-01 03:00:00', ]); Maintenance::disable(); // Manage IPs Maintenance::addIp('192.168.1.1', 'Office', now()->addHours(6)); Maintenance::removeIp('192.168.1.1'); // Manage tokens Maintenance::addToken('deploy', 'my-secret', now()->addDay()); Maintenance::revokeToken('deploy'); // Full status array $status = Maintenance::getStatus(); // Flush cache manually Maintenance::flushCache(); ``` ### Events [](#events) EventProperties`MaintenanceModeEnabled``string $message`, `?string $endsAt``MaintenanceModeDisabled`—`MaintenanceBypassGranted``string $type` (ip/cookie/header/url), `string $value```` use Axvi\Maintenance\Events\MaintenanceModeEnabled; Event::listen(MaintenanceModeEnabled::class, function ($event) { // Notify the team via Slack, etc. }); ``` How it works ------------ [](#how-it-works) This package replaces Laravel's built-in `PreventRequestsDuringMaintenance` middleware with its own `CheckMaintenanceMode` middleware. The bypass check order is: 1. **Excluded paths** — URLs matching `except` patterns are always allowed 2. **IP whitelist** — if the request IP is in the `maintenance_ips` table (cached) 3. **Cookie** — if the request has a valid bypass cookie 4. **Header** — if the request has a valid token in the `X-Maintenance-Token` header 5. **503 response** — HTML page with countdown (or JSON for API requests) All state is stored in the database, so maintenance mode works consistently across multiple application servers. Lookups are cached to minimize performance impact. Testing ------- [](#testing) ``` composer test ``` Or directly: ``` vendor/bin/phpunit ``` License ------- [](#license) MIT — see [LICENSE.md](LICENSE.md). ### Health Score 37 — LowBetter than 81% of packages Maintenance81 Actively maintained with recent releases Popularity9 Limited adoption so far Community6 Small or concentrated contributor base Maturity45 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~139 days Total 2 Last Release 27d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/21087087?v=4)[axvi](/maintainers/axvi)[@axvi](https://github.com/axvi) --- Top Contributors [![axvidev](https://avatars.githubusercontent.com/u/264813077?v=4)](https://github.com/axvidev "axvidev (1 commits)") --- Tags laravelmaintenance503 maintenance modemaintenance-page ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/axvi-laravel-maintenance/health.svg) ``` [![Health](https://phpackages.com/badges/axvi-laravel-maintenance/health.svg)](https://phpackages.com/packages/axvi-laravel-maintenance) ``` ### Alternatives [mike-bronner/laravel-model-caching Automatic caching for Eloquent models. 2.4k161.4k2](/packages/mike-bronner-laravel-model-caching)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 265.2k](/packages/aedart-athenaeum)[forjedio/inertia-table Backend-driven dynamic tables for Laravel + Inertia.js 272.0k](/packages/forjedio-inertia-table)[psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel)[api-platform/laravel API Platform support for Laravel 58190.1k21](/packages/api-platform-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)