Anvil
Anvil - The mobile companion for Laravel Forge. Available now. Download for iOS
Rappasoft

Configuration

Publishing Configuration

Publish the configuration file to customize all settings:

1php artisan vendor:publish --provider="Rappasoft\Lockout\LockoutServiceProvider" --tag=config

This will create config/lockout.php in your application.

Configuration Options

Basic Settings

enabled

Enable or disable lockout mode.

Default: env('APP_READ_ONLY', false)

1'enabled' => env('APP_READ_ONLY', false),

allow_login

Allow users to log in during lockout (only GET requests allowed after login).

Default: env('APP_READ_ONLY_LOGIN', false)

1'allow_login' => env('APP_READ_ONLY_LOGIN', false),

login_path / logout_path

Customize login and logout paths.

Default: 'login' / 'logout'

1'login_path' => 'login',
2'logout_path' => 'logout',

Request Type Configuration

locked_types

HTTP methods to block when lockout is enabled.

Default: ['post', 'put', 'patch', 'delete']

1'locked_types' => [
2    'post',
3    'put',
4    'patch',
5    'delete',
6],

pages

Specific GET request paths to block.

Default: []

1'pages' => [
2    'register',
3    'subscribe',
4],

whitelist

Whitelist specific method/path combinations.

Default: []

1'whitelist' => [
2    'post' => 'password/confirm',
3    'put' => 'profile/update',
4],

IP Management

ip_whitelist

Comma-separated list of IP addresses to whitelist (from .env).

Default: env('LOCKOUT_IP_WHITELIST', '')

1'ip_whitelist' => env('LOCKOUT_IP_WHITELIST', ''),

ip_whitelist_array

Array of IP addresses or CIDR ranges to whitelist.

Default: []

1'ip_whitelist_array' => [
2    '127.0.0.1',
3    '192.168.1.0/24',
4    '10.0.0.0/8',
5],

ip_blacklist

Comma-separated list of IP addresses to blacklist (from .env).

Default: env('LOCKOUT_IP_BLACKLIST', '')

1'ip_blacklist' => env('LOCKOUT_IP_BLACKLIST', ''),

ip_blacklist_array

Array of IP addresses or CIDR ranges to blacklist.

Default: []

1'ip_blacklist_array' => [
2    '192.168.1.50',
3    '10.0.0.100/24',
4],

Role-Based Access

allowed_roles

User roles that can bypass lockout.

Default: []

1'allowed_roles' => [
2    'admin',
3    'super-admin',
4],

Response Configuration

response_type

Type of response when request is blocked.

Options: 'abort', 'view', 'json'

Default: env('LOCKOUT_RESPONSE_TYPE', 'abort')

1'response_type' => env('LOCKOUT_RESPONSE_TYPE', 'abort'),

response_view

Blade view to render when response_type is 'view'.

Default: 'lockout::maintenance'

1'response_view' => 'lockout::maintenance',

response_message

Message to display in responses.

Default: 'Application is currently in read-only mode.'

1'response_message' => 'Application is currently in read-only mode.',

response_code

HTTP status code for blocked requests.

Default: 401 (HTTP_UNAUTHORIZED)

1'response_code' => 401,  // Use 503 for maintenance mode

Route Configuration

route_patterns

Route patterns to whitelist (supports wildcards).

Default: []

1'route_patterns' => [
2    'api/*',
3    'health',
4],

route_names

Route names to whitelist.

Default: []

1'route_names' => [
2    'health.check',
3    'api.status',
4],

API Configuration

api_enabled

Enable API-specific handling.

Default: env('LOCKOUT_API_ENABLED', true)

1'api_enabled' => env('LOCKOUT_API_ENABLED', true),

api_response_type

Response type for API requests.

Options: 'json', 'abort'

Default: 'json'

1'api_response_type' => 'json',

api_response_message

JSON response message for API requests.

Default:

1'api_response_message' => [
2    'message' => 'Application is currently in read-only mode.',
3    'status' => 'maintenance',
4],

Health Check

health_check_enabled

Enable the health check endpoint.

Default: env('LOCKOUT_HEALTH_CHECK_ENABLED', true)

1'health_check_enabled' => env('LOCKOUT_HEALTH_CHECK_ENABLED', true),

health_check_path

Path for the health check endpoint.

Default: env('LOCKOUT_HEALTH_CHECK_PATH', 'health')

1'health_check_path' => env('LOCKOUT_HEALTH_CHECK_PATH', 'health'),

Cache Configuration

cache_enabled

Enable caching of lockout status.

Default: env('LOCKOUT_CACHE_ENABLED', true)

1'cache_enabled' => env('LOCKOUT_CACHE_ENABLED', true),

cache_key

Cache key for lockout status.

Default: 'lockout.status'

1'cache_key' => 'lockout.status',

cache_ttl

Cache time-to-live in seconds.

Default: 60

1'cache_ttl' => 60,

Event Configuration

fire_events

Enable event firing for lockout actions.

Default: env('LOCKOUT_FIRE_EVENTS', true)

1'fire_events' => env('LOCKOUT_FIRE_EVENTS', true),

Environment Variables

All configuration can be set via environment variables:

 1# Basic
 2APP_READ_ONLY=true
 3APP_READ_ONLY_LOGIN=false
 4 
 5# IP Management
 6LOCKOUT_IP_WHITELIST=127.0.0.1,192.168.1.0/24
 7LOCKOUT_IP_BLACKLIST=192.168.1.50
 8 
 9# Response
10LOCKOUT_RESPONSE_TYPE=view
11LOCKOUT_RESPONSE_CODE=503
12 
13# API
14LOCKOUT_API_ENABLED=true
15 
16# Health Check
17LOCKOUT_HEALTH_CHECK_ENABLED=true
18LOCKOUT_HEALTH_CHECK_PATH=health
19 
20# Cache
21LOCKOUT_CACHE_ENABLED=true
22 
23# Events
24LOCKOUT_FIRE_EVENTS=true

Configuration Examples

Maintenance Mode Setup

1'enabled' => true,
2'response_type' => 'view',
3'response_code' => 503,
4'ip_whitelist_array' => [
5    '127.0.0.1',  // Your IP
6    '10.0.0.0/8',  // Internal network
7],
8'health_check_enabled' => true,
9'cache_enabled' => true,

API-Only Lockout

1'enabled' => true,
2'api_enabled' => true,
3'api_response_type' => 'json',
4'route_patterns' => [
5    'web/*',  // Allow web routes
6],
7'locked_types' => ['post', 'put', 'patch', 'delete'],

Role-Based Maintenance

1'enabled' => true,
2'allowed_roles' => [
3    'admin',
4    'maintenance',
5],
6'response_type' => 'view',
7'response_code' => 503,