#Laravel Lockout v6.0: A Complete Maintenance Mode Solution

#What's New in v6.0

#🚀 Laravel 11 & 12 Support

The package now fully supports Laravel 11 and Laravel 12, ensuring compatibility with the latest Laravel features and improvements. We've updated all dependencies and tested thoroughly to ensure seamless integration.

Requirements:

• PHP 8.2+
• Laravel 11.x or 12.x

#🎯 10 Powerful New Features

#1. IP Whitelist & Blacklist

Control access at the IP level with support for both individual IPs and CIDR notation.

 1// In config/lockout.php
 2'ip_whitelist_array' => [
 3    '127.0.0.1',           // Single IP
 4    '192.168.1.0/24',      // CIDR range
 5    '10.0.0.0/8',          // Large network
 6],
 7 
 8'ip_blacklist_array' => [
 9    '192.168.1.50',        // Block specific IP
10    '10.0.0.100/24',       // Block network range
11],

Use Cases:

• Allow your team's IPs during maintenance
• Block malicious IPs even when lockout is disabled
• Grant access to specific networks (e.g., office VPN)

Environment Variables:

1LOCKOUT_IP_WHITELIST=127.0.0.1,192.168.1.0/24
2LOCKOUT_IP_BLACKLIST=192.168.1.50

#2. Role-Based Exceptions

Allow specific user roles to bypass lockout, perfect for admin access during maintenance.

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

Supported Role Systems:

• Laravel Bouncer (hasRole() method)
• Spatie Permission (hasRole() method)
• Simple role attributes ($user->role)
• Roles relationships ($user->roles collection)

Example:

1// User with admin role can access during lockout
2$user = User::find(1);
3$user->role = 'admin';
4 
5// This user can now make POST/PUT/DELETE requests
6// even when lockout is enabled

#3. Custom Response Types

Choose how blocked requests are handled with three response types.

Abort (Default):

1'response_type' => 'abort',
2'response_code' => 401,  // or 503 for maintenance mode
3'response_message' => 'Application is currently in read-only mode.',

JSON Response:

1'response_type' => 'json',

Returns:

1{
2    "message": "Application is currently in read-only mode."
3}

View Response:

1'response_type' => 'view',
2'response_view' => 'lockout::maintenance',

Publish and customize the view:

1php artisan vendor:publish --tag=lockout-views

#4. Route Patterns & Names

Whitelist entire route groups or specific named routes.

Route Patterns:

1'route_patterns' => [
2    'api/*',              // All API routes
3    'admin/*',            // All admin routes
4    'health',             // Health check
5],

Route Names:

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

#5. API-Specific Handling

Automatic API detection with dedicated JSON responses.

1'api_enabled' => true,
2'api_response_type' => 'json',
3'api_response_message' => [
4    'message' => 'Application is in maintenance mode.',
5    'status' => 'maintenance',
6],

The package automatically detects API requests by:

• Accept: application/json header
• Routes starting with api/
• Routes in the api middleware group

#6. Health Check Endpoint

Built-in health check endpoint for monitoring systems.

Default Endpoint:

1GET /health

Response:

1{
2    "status": "ok",
3    "timestamp": "2025-01-15T10:30:00Z",
4    "lockout_enabled": true
5}

Customization:

1'health_check_enabled' => true,
2'health_check_path' => 'health',  // Customize path

#7. Cache Integration

Improve performance with configurable caching.

1'cache_enabled' => true,
2'cache_key' => 'lockout.status',
3'cache_ttl' => 60,  // seconds

Benefits:

• Reduces config lookups
• Improves response time
• Configurable TTL

Clear Cache:

1php artisan cache:clear
2# Or when enabling/disabling:
3php artisan lockout:enable --clear-cache

#8. Event System

Listen to lockout events for logging, monitoring, or custom actions.

Available Events:

• Rappasoft\Lockout\Events\LockoutEnabled
• Rappasoft\Lockout\Events\LockoutDisabled
• Rappasoft\Lockout\Events\RequestBlocked

Example Listener:

 1use Rappasoft\Lockout\Events\RequestBlocked;
 2use Illuminate\Support\Facades\Log;
 3 
 4class LogBlockedRequests
 5{
 6    public function handle(RequestBlocked $event)
 7    {
 8        Log::warning('Request blocked', [
 9            'path' => $event->request->path(),
10            'method' => $event->request->method(),
11            'ip' => $event->request->ip(),
12            'reason' => $event->reason,
13        ]);
14    }
15}

Register in EventServiceProvider:

1protected $listen = [
2    RequestBlocked::class => [
3        LogBlockedRequests::class,
4    ],
5];

#9. Artisan Commands

Manage lockout from the command line.

Enable Lockout:

1php artisan lockout:enable
2php artisan lockout:enable --clear-cache

Disable Lockout:

1php artisan lockout:disable
2php artisan lockout:disable --clear-cache

Check Status:

1php artisan lockout:status

Output:

 1Lockout Status:
 2─────────────────
 3Enabled: Yes
 4Cached: Yes
 5
 6Configuration:
 7  Allow Login: Yes
 8  Locked Types: post, put, patch, delete
 9  Response Type: abort
10  Health Check: Yes
11  Cache Enabled: Yes

#10. Graceful Degradation

Beautiful maintenance view included out of the box.

The package includes a professional maintenance view that you can customize:

1php artisan vendor:publish --tag=lockout-views

Edit resources/views/vendor/lockout/maintenance.blade.php to match your brand.

#Migration Guide

#From v5.0 to v6.0

1. Update Dependencies:

   1composer update rappasoft/lockout

2. Publish Updated Config:

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

3. Review New Configuration: Check config/lockout.php for new options and customize as needed.

4. Update Tests: If you have custom tests, they should continue to work. The default response code remains 401 for backward compatibility.

#Real-World Examples

#Example 1: Maintenance Mode with Team Access

 1// config/lockout.php
 2'enabled' => true,
 3'response_type' => 'view',
 4'response_code' => 503,
 5'ip_whitelist_array' => [
 6    '127.0.0.1',           // Your IP
 7    '192.168.1.0/24',      // Office network
 8    '10.0.0.0/8',          // VPN network
 9],
10'allowed_roles' => [
11    'admin',
12    'maintenance',
13],
14'health_check_enabled' => true,

#Example 2: 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'],

#Example 3: Emergency Lockdown

1'enabled' => true,
2'response_type' => 'abort',
3'response_code' => 503,
4'ip_whitelist_array' => [
5    '127.0.0.1',  // Only localhost
6],
7'health_check_enabled' => true,
8'fire_events' => true,  // Log all blocked requests

#Best Practices

1. Always Whitelist Your IP First Before enabling lockout, add your IP to the whitelist to ensure you can still access the application.

2. Use Health Check for Monitoring Configure your monitoring tools (e.g., UptimeRobot, Pingdom) to check the /health endpoint.

3. Enable Caching in Production Improve performance by enabling cache for lockout status.

4. Use Events for Logging Listen to RequestBlocked events to track blocked requests and identify issues.

5. Customize Response for Better UX Use view responses for web requests and JSON for API requests.

6. Test in Staging First Always test lockout configuration in a staging environment before using in production.

#Testing

The package includes comprehensive test coverage with 77 tests covering:

• ✅ All HTTP methods (GET, POST, PUT, PATCH, DELETE)
• ✅ IP whitelist/blacklist with CIDR support
• ✅ Role-based exceptions
• ✅ Route patterns and names
• ✅ API detection and responses
• ✅ Cache integration
• ✅ Event system
• ✅ Health check endpoint
• ✅ Edge cases and error handling

Run tests:

1composer test

#Performance

With caching enabled, the package adds minimal overhead:

• Without Cache: ~0.5ms per request
• With Cache: ~0.1ms per request

The cache is automatically invalidated when you use the Artisan commands with --clear-cache.

#Security Considerations

1. IP Whitelist Security:

   • Use CIDR notation carefully
   • Regularly review whitelisted IPs
   • Consider using VPN IPs for team access

2. Role-Based Access:

   • Only grant exceptions to trusted roles
   • Regularly audit role assignments
   • Use least privilege principle

3. Health Check:

   • The health endpoint is always accessible
   • Consider adding authentication if sensitive
   • Monitor for abuse

#What's Next?

We're already planning v7.0 with even more features:

• Scheduled lockout (cron-based)
• Database-driven configuration
• Queue job exceptions
• Rate limiting integration
• Multi-environment support
• Webhook notifications

#Conclusion

Laravel Lockout v6.0 is a complete maintenance mode solution that gives you fine-grained control over your application's access during maintenance, updates, or emergencies. With 10 new features, Laravel 11/12 support, and comprehensive test coverage, it's ready for production use.

Get Started:

1composer require rappasoft/lockout

Documentation:

• GitHub Repository
• Full Documentation

Support:

• GitHub Issues
• Discussions

Happy coding! 🚀