jarir-ahmed/kill-switch

A framework-agnostic PHP kill-switch package using PSR-15 middleware. Returns a maintenance page when enabled.

v1.0.0 2026-07-19 08:11 UTC

Requires

• php: ^8.0
• nyholm/psr7: ^1.7
• psr/http-factory: ^1.0
• psr/http-message: ^1.0 || ^2.0
• psr/http-server-middleware: ^1.0

Requires (Dev)

• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^9.5 || ^10.0

MIT

• Jarir Ahmed

Published on Packagist.org on 2026-07-19 08:14 UTC

README

Kill Switch

A framework-agnostic PHP kill-switch package using PSR-15 middleware. When enabled, every request returns a 503 maintenance page with the message "We are In Maintenance Mode".

Installation

composer require jarir-ahmed/kill-switch

Requirements

• PHP >= 8.0
• psr/http-message
• psr/http-server-middleware
• psr/http-factory

Usage

Configuration

The kill switch state is checked in this priority order:

1. Environment variable — KILL_SWITCH_ENABLED (true / false)
2. File — configurable path, contents must match file_enabled_value (default: 1)
3. Database — DSN + table + column, toggled externally

PSR-15 Middleware (Any Framework)

use JarirAhmed\KillSwitch\KillSwitch\KillSwitchManager;
use JarirAhmed\KillSwitch\KillSwitch\KillSwitchMiddleware;
use JarirAhmed\KillSwitch\KillSwitch\MaintenanceResponder;
use Nyholm\Psr7\Factory\Psr17Factory;

$config = [
    'env_var' => 'KILL_SWITCH_ENABLED',
    'file_path' => __DIR__ . '/../storage/kill-switch.txt',
    'file_enabled_value' => '1',
    'db' => [
        'connection' => 'mysql:host=localhost;dbname=app',
        'table' => 'settings',
        'column' => 'enabled',
        'id' => 1,
    ],
    'view_path' => null,
    'message' => 'We are In Maintenance Mode',
    'retry_after' => 3600,
];

$manager = new KillSwitchManager($config);

$responseFactory = new Psr17Factory();
$responder = new MaintenanceResponder($config, $responseFactory);
$middleware = new KillSwitchMiddleware($manager, $responder);

// Add to your PSR-15 middleware stack
$stack->add($middleware);

Toggle Methods

Env Variable

# Enable
export KILL_SWITCH_ENABLED=true

# Disable
export KILL_SWITCH_ENABLED=false

Or in .env:

KILL_SWITCH_ENABLED=true

File

# Enable
echo "1" > storage/kill-switch.txt

# Disable
echo "0" > storage/kill-switch.txt

Database

UPDATE settings SET enabled = 1 WHERE id = 1;
UPDATE settings SET enabled = 0 WHERE id = 1;

Laravel Integration

Step 1: Publish Config (Optional)

php artisan vendor:publish --provider="JarirAhmed\KillSwitch\KillSwitch\Laravel\KillSwitchServiceProvider" --tag=kill-switch-config

Step 2: Register Middleware

In app/Http/Kernel.php:

protected $middleware = [
    \JarirAhmed\KillSwitch\KillSwitch\Laravel\KillSwitchLaravelMiddleware::class,
];

Step 3: Configure

Edit config/kill-switch.php:

return [
    'env_var' => 'KILL_SWITCH_ENABLED',
    'file_path' => storage_path('kill-switch.txt'),
    'file_enabled_value' => '1',
    'db' => [
        'connection' => env('DB_CONNECTION'),
        'table' => 'settings',
        'column' => 'kill_switch_enabled',
        'id' => 1,
    ],
    'view_path' => resource_path('views/maintenance.html'),
    'message' => 'We are In Maintenance Mode',
    'retry_after' => 3600,
];

Custom Maintenance Page

Place your custom HTML at the configured view_path. The default template is at:

resources/views/maintenance.html

Testing

vendor/bin/phpunit

License

MIT