PHPackages                             saksham/laravel-maintenance-signal - 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. [Logging & Monitoring](/categories/logging)
4. /
5. saksham/laravel-maintenance-signal

ActiveLibrary[Logging & Monitoring](/categories/logging)

saksham/laravel-maintenance-signal
==================================

Adds a configurable HTTP header to Laravel maintenance mode responses.

v1.0.0(today)00MITPHPPHP ^8.1CI passing

Since Jun 26Pushed todayCompare

[ Source](https://github.com/sakshamgorey/laravel-maintenace-signal)[ Packagist](https://packagist.org/packages/saksham/laravel-maintenance-signal)[ RSS](/packages/saksham-laravel-maintenance-signal/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (4)Versions (2)Used By (0)

Laravel Maintenance Signal
==========================

[](#laravel-maintenance-signal)

Adds a configurable HTTP header to Laravel maintenance mode responses so uptime monitors can distinguish planned maintenance from real outages.

Why this exists
---------------

[](#why-this-exists)

A plain `503 Service Unavailable` is ambiguous. External monitors cannot reliably know whether the app is intentionally in Laravel maintenance mode or actually broken.

`503` without the header means real outage or unknown failure.

`503` with the header means planned Laravel maintenance.

This package adds the header only on Laravel maintenance responses by replacing Laravel's maintenance middleware with a small subclass.

Installation
------------

[](#installation)

```
composer require saksham/laravel-maintenance-signal
```

Publish config
--------------

[](#publish-config)

```
php artisan vendor:publish --tag=maintenance-signal-config
```

Usage
-----

[](#usage)

### Laravel 11, 12, and 13

[](#laravel-11-12-and-13)

In `bootstrap/app.php`, replace Laravel's default maintenance middleware with the package middleware:

```
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
use Saksham\MaintenanceSignal\Http\Middleware\PreventRequestsDuringMaintenance as MaintenanceSignalMiddleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->use([
            \Illuminate\Foundation\Http\Middleware\InvokeDeferredCallbacks::class,
            \Illuminate\Http\Middleware\TrustProxies::class,
            \Illuminate\Http\Middleware\HandleCors::class,
            MaintenanceSignalMiddleware::class,
            \Illuminate\Http\Middleware\ValidatePostSize::class,
            \Illuminate\Foundation\Http\Middleware\TrimStrings::class,
            \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
        ]);
    })
    ->create();
```

### Laravel 10

[](#laravel-10)

In `app/Http/Kernel.php`, replace:

```
\Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance::class,
```

with:

```
\Saksham\MaintenanceSignal\Http\Middleware\PreventRequestsDuringMaintenance::class,
```

Configuration
-------------

[](#configuration)

```
MAINTENANCE_SIGNAL_ENABLED=true
MAINTENANCE_SIGNAL_HEADER=X-Laravel-Maintenance-Mode
MAINTENANCE_SIGNAL_VALUE=active
```

Default config:

```
return [
    'enabled' => env('MAINTENANCE_SIGNAL_ENABLED', true),
    'header' => env('MAINTENANCE_SIGNAL_HEADER', 'X-Laravel-Maintenance-Mode'),
    'value' => env('MAINTENANCE_SIGNAL_VALUE', 'active'),
];
```

Example response
----------------

[](#example-response)

```
php artisan down --retry=60 --refresh=15
```

```
HTTP/1.1 503 Service Unavailable
Retry-After: 60
Refresh: 15
X-Laravel-Maintenance-Mode: active
```

Uptime monitor examples
-----------------------

[](#uptime-monitor-examples)

Generic logic:

```
if status == 503 and header X-Laravel-Maintenance-Mode == active:
    suppress alert
else if status >= 500:
    alert

```

Better Stack:

```
Treat a 503 response with X-Laravel-Maintenance-Mode: active as planned maintenance.
Alert on 5xx responses missing that header.

```

UptimeRobot:

```
Use a keyword/header monitor where available, or route webhook alerts through the generic logic above.

```

Pingdom:

```
Use a custom check or alert integration that inspects response headers before notifying.

```

AI agents:

```
Agents that triage incidents can treat X-Laravel-Maintenance-Mode: active as planned maintenance instead of an unknown outage.

```

Generic curl:

```
curl -I https://example.com
```

Expected:

```
HTTP/2 503
x-laravel-maintenance-mode: active
```

Security note
-------------

[](#security-note)

This header only says the application is intentionally in maintenance mode. It does not expose secrets, paths, exception details, or server internals.

Testing
-------

[](#testing)

```
composer test
```

License
-------

[](#license)

MIT

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance100

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

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/90107977?v=4)[Saksham Gorey](/maintainers/sakshamgorey)[@sakshamgorey](https://github.com/sakshamgorey)

---

Top Contributors

[![sakshamgorey](https://avatars.githubusercontent.com/u/90107977?v=4)](https://github.com/sakshamgorey "sakshamgorey (3 commits)")

---

Tags

composerlaravelmonitoringphpuptime

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/saksham-laravel-maintenance-signal/health.svg)

```
[![Health](https://phpackages.com/badges/saksham-laravel-maintenance-signal/health.svg)](https://phpackages.com/packages/saksham-laravel-maintenance-signal)
```

###  Alternatives

[spatie/laravel-health

Monitor the health of a Laravel application

87411.3M153](/packages/spatie-laravel-health)[api-platform/laravel

API Platform support for Laravel

59156.3k11](/packages/api-platform-laravel)[spatie/laravel-flare

Send Laravel errors to Flare

111.2M6](/packages/spatie-laravel-flare)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

119.2k](/packages/tomshaw-electricgrid)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)