Download the PHP package milenmk/laravel-rate-limiting without Composer

Laravel Advanced Rate Limiting Package

An advanced rate limiting package for Laravel with exponential backoff, custom messages, and built-in Blade components. This package provides comprehensive protection against DDoS attacks, brute force attempts, and other malicious activities while maintaining a positive user experience for legitimate users.

Features

• Multi-layered protection with configurable limits for different authentication endpoints
• Intelligent backoff strategies (linear, Fibonacci, and exponential)
• Granular limit types (global, per-email, per-IP, per-session, per-username+IP)
• Progressive user feedback with proactive warnings before lockouts
• Context-aware messaging with intelligent suggestions based on the situation
• Built-in Blade components for error and warning messages
• Comprehensive logging and monitoring capabilities
• Flexible configuration with easy enable/disable controls

Essentially, this package takes Laravel's basic rate limiting capabilities and extends them with sophisticated features specifically tailored for authentication security, making it much easier to implement robust protection against brute force attacks without having to build all these features yourself.

Architecture

The system is built around a dedicated service provider that implements a configuration-driven approach:

• Separation of concerns: Rate limiting logic is isolated from application logic
• Configuration-driven design: All limiters are defined in a single, maintainable configuration array
• Extensible architecture: New limiters and limit types can be added with minimal code changes
• Performance optimized: Uses Laravel's cache system with efficient key generation

Requirements

• PHP 8.2 or higher
• Laravel 10.x, 11.x, or 12.x

Installation

You can install the package via Composer:

Publish Configuration

Publish the configuration file:

This will create a config/rate-limiting.php file where you can customize all rate limiting settings.

Publish Environment Variables Template

Publish the environment variables template:

This will create a .env.rate-limiting.example file with all available environment variables that you can copy to your .env file.

Publish Views (Optional)

If you want to customize the Blade components, you can publish the views:

This will publish the views to resources/views/vendor/milenmk/laravel-rate-limiting/.

Supported Endpoints

The package protects the following authentication endpoints:

Growth Strategies

The system supports three distinct backoff strategies to balance security with user experience.

Key Concept: Rate limiting delays are only applied to attempts that EXCEED the configured maximum. For example, if the limit is set to 5 attempts, the first 5 failed attempts will show normal validation errors. Rate limiting delays begin with the 6th attempt (1st excess attempt) and increase according to the chosen strategy.

Strategy Comparison

Important: Rate limiting only applies to attempts that EXCEED the configured maximum. The table below shows delay times for attempts beyond the limit. The delay time of 60 min specified in the table is the maximum suspension time set in the configuration file (default to 60 min).

Example: Consider a user making repeated failed login attempts with Fibonacci strategy and a limit of 5 attempts:

• Attempts 1-5: Normal failed attempts, no rate limiting applied
• 6th attempt (1st excess): User is blocked for 1 minute
• 7th attempt (2nd excess): After waiting 1 minute, if they fail again, blocked for 2 minutes
• 8th attempt (3rd excess): After waiting 2 minutes, if they fail again, blocked for 3 minutes
• 9th attempt (4th excess): After waiting 3 minutes, if they fail again, blocked for 5 minutes
• 10th attempt (5th excess): After waiting 5 minutes, if they fail again, blocked for 8 minutes

This gradual increase in waiting time effectively deters automated attacks while remaining manageable for legitimate users who occasionally make mistakes.

Strategy Selection Guide

• Linear: Predictable, gentle escalation. Best for development/testing environments or when user experience is prioritized over security.

• Fibonacci ⭐ Recommended: Provides an optimal balance between user experience and security. Grows more aggressively than linear but remains reasonable for legitimate users who make mistakes.

• Exponential: Maximum security with aggressive escalation. Use only for highly sensitive endpoints or when under active attack.

Limit Types

Each endpoint supports multiple limit types that can be independently configured:

Registration Limits

• Global: System-wide registration attempts (recommended: enabled with high limits ~150+)
• Email: Per-email address attempts (prevents account enumeration)
• IP: Per-IP address attempts (prevents distributed attacks from single source)

Login Limits

• Global: System-wide login attempts (recommended: disabled to avoid impacting legitimate users)
• Username+IP: Per-username and IP combination (prevents targeted attacks)
• IP: Per-IP address attempts (prevents brute force from single source)

Forgot Password Limits

• Global: System-wide password reset attempts (recommended: disabled)
• Email: Per-email address attempts (prevents email flooding)
• IP: Per-IP address attempts (prevents abuse)

Two-Factor Authentication Limits

• Global: System-wide 2FA attempts (recommended: disabled)
• Session: Per-session attempts (most effective for 2FA)
• IP: Per-IP address attempts (additional protection)

Configuration

Environment Variables

The package includes a comprehensive .env.rate-limiting.example file with all available configuration options. Copy the relevant variables to your .env file and adjust as needed:

Username Resolution Configuration

The package provides flexible username field resolution for the username_ip rate limiter:

Simple Configuration (Most Users)

Set the field name in your .env file:

Advanced Configuration (Custom Logic)

For complex scenarios, define a custom resolver in your AppServiceProvider:

Fortify Integration (Automatic)

If Laravel Fortify is installed, the package automatically uses Fortify's configured username field. No additional configuration needed.

Configuration Examples

Basic Configuration

Suitable for most applications with standard security requirements:

Balanced Security Configuration (Recommended)

Provides optimal security-to-usability ratio for production environments:

Maximum Security Configuration

For high-risk environments or during active attacks:

Development Configuration

For development and testing environments:

Global Limiters

Global limiters provide system-wide protection but require careful consideration:

Benefits

• System-wide protection: Prevents overwhelming the entire system
• Resource protection: Protects database and cache resources
• DDoS mitigation: Effective against distributed attacks

Considerations

• Legitimate user impact: May block legitimate users during high-traffic periods
• False positives: Normal usage spikes may trigger limits
• Shared hosting: Multiple applications may compete for the same limits

Recommendations

• Registration: Enable with high limits (150+ attempts) to prevent spam
• Login: Generally disable to avoid impacting legitimate users
• Forgot Password: Usually unnecessary; per-email limits are sufficient
• Two-Factor: Session-based limits are more appropriate

Usage

Built-in Blade Components

The package includes ready-to-use Blade components for displaying rate limit messages. No need to create these components yourself - they are automatically available after package installation.

Error Messages

Display rate limit errors when limits are exceeded:

Lock-down timer

By default, when locked is applied, a countdown timer is displayed showing the remaining time until unblocking. You can customize the countdown format by setting the RATE_LIMITING_SHOW_WAIT_COUNTER property in your application .env file. Default value is true

Warning Messages

Display proactive warnings when users are approaching limits:

The warning component automatically displays session-based warnings when users are approaching their rate limits.

Complete Integration Example

Here's how to integrate both error and warning messages in an authentication form:

Component Properties

Both components accept the following properties:

• field (error-message only): The error field name (default: '')
• message (warning-message only): Custom message to display (default: '')
• title: The title/heading for the message (default: null)
• class: CSS classes to apply (default: 'my-2 p-2')

Automatic Integration

The package automatically integrates with Laravel's authentication system and works seamlessly with or without Laravel Fortify. No additional setup is required - rate limiting will be applied to:

• Registration attempts
• Login attempts
• Password reset requests
• Two-factor authentication attempts

Username Field Resolution

The package uses an intelligent hybrid approach to resolve username fields:

1. Custom Resolver (Advanced): Define a custom callback for complex logic
2. Fortify Integration (Automatic): Uses Fortify's username field if installed
3. Configurable Field (Simple): Set username_field in config (default: 'email')
4. Smart Fallback (Automatic): Tries common field names (email, username, login, etc.)

Message Customization

The system provides intelligent, context-aware messages that adapt based on the situation:

Error Message Examples

• Login: "Too many login attempts with this username from your location. Please wait 5 minutes before trying again. Consider resetting your password if you've forgotten it, or contact support if you believe this is an error."

• Registration: "Too many registration attempts from your location. Please wait 3 minutes before trying again. Please verify all required fields are filled correctly and try again later."

• Two-Factor: "Too many two-factor authentication attempts for this session. Please wait 8 minutes before trying again. If you're having trouble with your authenticator, try using a recovery code instead."

Warning Message Examples

• Login Warning: "You have 2 attempt(s) remaining before a temporary lockout. If you've forgotten your password, consider using the 'Reset Password' link below."

• Registration Warning: "You have 1 attempt(s) remaining before a temporary lockout. Please double-check your information before submitting."

• Two-Factor Warning: "You have 2 attempt(s) remaining before a temporary lockout. Double-check your authenticator app or recovery code."

Custom Messages

The system supports three types of customizable messages:

1. Error Messages

Error messages are shown when rate limits are exceeded:

2. Warning Messages

Warning messages are shown when users are approaching rate limits:

3. Suggestion Messages

Suggestion messages are appended to error messages to provide helpful guidance:

Message Placeholders

• :minutes - Automatically replaced with wait time in minutes (error messages)
• :attempts - Automatically replaced with remaining attempts count (warning messages)

Smart Suggestion Logic

The system automatically selects appropriate suggestions based on context:

• Login & Two-Factor: Uses different suggestions for high attempts (≥3) vs low attempts (<3)
• Registration & Forgot Password: Uses consistent suggestions regardless of attempt count
• Fallback: Provides default suggestions if specific ones aren't configured

User Experience Flow

Progressive User Feedback

The system provides a progressive feedback experience that guides users through rate limiting scenarios:

Normal Operation

1. Successful attempts: No rate limiting messages shown
2. Failed attempts: Standard validation errors displayed

Approaching Limits (2 or fewer attempts remaining)

1. Warning displayed: "You have 2 attempt(s) remaining before a temporary lockout."
2. Context-specific guidance: Appropriate suggestions based on the endpoint
3. Proactive help: Encourages correct action before lockout

Rate Limit Exceeded

1. Clear error message: Explains what happened and how long to wait
2. Helpful suggestions: Context-aware guidance for resolution
3. Recovery options: Suggests alternative actions (password reset, support contact)

Example User Journey (Login with 5 attempt limit)

Benefits of Progressive Feedback

• Prevents frustration: Users get warnings before being locked out
• Reduces support burden: Clear guidance helps users self-resolve issues
• Maintains security: All security protections remain fully effective
• Improves conversion: Users are less likely to abandon the process

Monitoring and Logging

When RATE_LIMITING_LOG_VIOLATIONS=true, the package logs detailed information about violations:

Monitoring Best Practices

1. Regular log review: Monitor for unusual patterns or attack attempts
2. Alert configuration: Set up alerts for high violation rates
3. Performance monitoring: Track cache usage and response times
4. User feedback: Monitor support requests related to access issues

Performance Considerations

• Cache efficiency: Uses Laravel's cache system with optimized key structures
• Minimal overhead: Processing only occurs when limits are approached
• Memory management: Configurable maximum suspension times prevent indefinite cache growth
• Scalability: Designed to handle high-traffic applications

Security Best Practices

1. Regular monitoring: Review logs for attack patterns and adjust limits accordingly
2. Limit tuning: Fine-tune based on legitimate user behavior patterns
3. HTTPS enforcement: Always use HTTPS to prevent session hijacking
4. IP whitelisting: Consider whitelisting trusted IP ranges for administrative access
5. Configuration review: Periodically review and update rate limiting configurations
6. Incident response: Have procedures for quickly adjusting limits during attacks

Customization

Custom Blade Components

If you need to customize the appearance of the error and warning components, publish the views and modify them:

Then edit the files in resources/views/vendor/rate-limiting/components/.

You can include them in your blade files as follows:

Adding New Limiters

The system is designed for easy extension. To add a new limiter:

1. Add to configuration array in RateLimitingServiceProvider:

2. Add configuration in config/rate-limiting.php:

Troubleshooting

Common Issues

Legitimate users being blocked

• Solution: Increase attempt limits or switch from exponential to Fibonacci/linear growth
• Prevention: Monitor user behavior patterns and adjust limits accordingly

Rate limiting not working

• Check: Ensure RATE_LIMITING_ENABLED=true in your .env file
• Check: Verify the specific limiter is enabled (e.g., RATE_LIMITING_LOGIN_ENABLED=true)
• Check: Confirm cache is working properly

Messages not displaying

• Check: Ensure you're using the correct component names (<x-error-message> and <x-warning-message>)
• Check: Verify the field parameter matches the error key (rate_limit)

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Milen Karaganski
• All Contributors

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

Support My Work

If this package saves you time, you can support ongoing development:
👉 Become a Patron

Other Packages

Check out my other Laravel packages:

• Laravel GDPR Cookie Manager - GDPR-compliant cookie consent management with user preference tracking
• Laravel Blacklist - A Laravel package for blacklist validation of user input
• Laravel Email Change Confirmation - Secure email change confirmation system
• Laravel GDPR Exporter - GDPR-compliant data export functionality
• Laravel Locations - Add Countries, Cities, Areas, Languages and Currencies models to your Laravel application
• Laravel Datatables and Forms - Easy to use package to create datatables and forms for Livewire components

License

This package is licensed under the MIT License. See the LICENSE file for more details.

Disclaimer

This package is provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or noninfringement.

The author(s) make no guarantees regarding the accuracy, reliability, or completeness of the code, and shall not be held liable for any damages or losses arising from its use.

Please ensure you thoroughly test this package in your environment before deploying it to production.