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.0(2mo ago)00MITPHPPHP ^8.1CI passing Since Mar 5Pushed 2mo 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 1mo ago READMEChangelogDependencies (8)Versions (2)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 35 — LowBetter than 79% of packages Maintenance86 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity42 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 Unknown Total 1 Last Release 68d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/28b9d5133d636438b0e778c04526a3e20854a9ffbab9831883694fe016c7752d?d=identicon)[axvi](/maintainers/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 [barryvdh/laravel-ide-helper Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion. 14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k12.1M99](/packages/laravel-pulse)[spatie/laravel-enum Laravel Enum support 3655.4M31](/packages/spatie-laravel-enum)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9682.1M97](/packages/roots-acorn)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 255.2k](/packages/aedart-athenaeum)[interaction-design-foundation/laravel-geoip Support for multiple Geographical Location services. 17221.0k3](/packages/interaction-design-foundation-laravel-geoip) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)