README

A robust solution for managing maintenance mode in Laravel applications with fine-grained control and elegant customization

📖 Table of Contents

Introduction
Key Features
Installation
Configuration
4.1 Middleware Setup
4.2 Publishing Assets
4.3 Configuration Options
Usage
5.1 Artisan Commands
5.2 Helper Functions
5.3 Bypass Mechanism
Customization
Contributing
License
Author

🌟 Introduction

The Laravel Maintenance Mode package provides enterprise-grade maintenance mode management for Laravel applications. Features include environment-based configuration, granular access control, and seamless integration with Laravel's ecosystem.

🚩 Key Features

⚡ Instant toggle via Artisan commands
🔐 Role-based access control
🛣 Route/URL whitelisting
🎭 Customizable maintenance pages
📊 Environment variable sync
👮 Middleware access control
🔍 Real-time status checks

🚀 Installation

composer require tsrgtm/maintenance-mode

🛠 Configuration

Middleware Setup

Global registration (Laravel 11+) in bootstrap/app.php:

use Tsrgtm\MaintenanceMode\Middleware\MaintenanceModeMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(MaintenanceModeMiddleware::class);
})

Route-specific registration:

Route::get('/admin', fn() => view('admin'))->middleware(MaintenanceModeMiddleware::class);

Publishing Assets

php artisan vendor:publish --tag=config
php artisan vendor:publish --tag=views

Configuration Options

config/maintenance.php:

return [
    'enabled' => env('MAINTENANCE_MODE', false),
    'view' => 'maintenance::default',
    'allowed_routes' => ['login', 'status'],
    'allowed_urls' => ['/api/healthcheck'],
];

Option	Type	Default	Description
enabled	bool	`false`	Maintenance mode status
view	string	`maintenance::default`	Blade template path
allowed_routes	array	`[]`	Accessible route names during maintenance
allowed_urls	array	`[]`	Accessible URL paths during maintenance

🎮 Usage

Artisan Commands

# Toggle maintenance mode
php artisan maintenance:toggle true   # Enable
php artisan maintenance:toggle false  # Disable

# Check status
php artisan maintenance:status

Helper Functions

use Tsrgtm\MaintenanceMode\Helpers\{setMaintenanceMode, isMaintenanceMode};

// Enable maintenance mode
setMaintenanceMode(true);

// Check status
if (isMaintenanceMode()) {
    // Maintenance mode logic
}

Bypass Mechanism

Add to User model:

class User extends Authenticatable
{
    public function canBypassMaintenance(): bool
    {
        return $this->is_admin || $this->hasRole('maintenance-tech');
    }
}

🎨 Customization

Create custom view:

resources/views/vendor/maintenance/custom.blade.php

Update configuration:

'view' => 'vendor.maintenance.custom',

Example view:

@extends('layouts.app') @section('content')
<div class="container">
  <h1>🔧 Scheduled Maintenance</h1>
  <p>We expect to be back by {{ $estimatedTime }}</p>
  <div class="alert alert-info">Contact support: support@example.com</div>
</div>
@endsection

🤝 Contributing

Fork the repository
Create feature branch: git checkout -b feature/new-feature
Commit changes: git commit -m 'Add new feature'
Push to branch: git push origin feature/new-feature
Open Pull Request

📜 License

MIT License - See LICENSE for details.

👤 Author

Tusar Gautam
GitHub Profile • Email

tsrgtm / maintenance-mode

Maintainers

Details