README.md

This package allows you to apply rate limiters to Laravel Livewire actions. This is useful for throttling login attempts and other brute force attacks, reducing spam, and more.

Installation

You can use Composer to install this package into your application:

composer require danharrin/livewire-rate-limiting

This package requires at least Laravel v8.x, when rate limiting improvements were introduced.

This package is tested to support the file and redis cache drivers, but not array.

Usage

Apply the DanHarrin\LivewireRateLimiting\WithRateLimiting trait to your Livewire component:

<?php

namespace App\Http\Livewire\Login;

use DanHarrin\LivewireRateLimiting\WithRateLimiting;
use Livewire\Component;

class Login extends Component
{
    use WithRateLimiting;
    
    // ...
}

In this example, we will set up rate limiting on the submit action.

The user will only be able to call this action 10 times every minute.

If this limit is exceeded, a TooManyRequestsException will be thrown. The user is presented with a validation error and instructed how long they have until the limit is lifted:

<?php

namespace App\Http\Livewire\Login;

use DanHarrin\LivewireRateLimiting\Exceptions\TooManyRequestsException;
use DanHarrin\LivewireRateLimiting\WithRateLimiting;
use Illuminate\Validation\ValidationException;
use Livewire\Component;

class Login extends Component
{
    use WithRateLimiting;
    
    public function submit()
    {
        try {
            $this->rateLimit(10);
        } catch (TooManyRequestsException $exception) {
            throw ValidationException::withMessages([
                'email' => "Slow down! Please wait another {$exception->secondsUntilAvailable} seconds to log in.",
            ]);
        }
        
        // ...
    }
}

API Reference

Component Methods

use DanHarrin\LivewireRateLimiting\WithRateLimiting;

/**
 * Rate limit a Livewire method, `$maxAttempts` times every `$decaySeconds` seconds.
 * 
 * @throws DanHarrin\LivewireRateLimiting\Exceptions\TooManyRequestsException
 */
$this->rateLimit(
    $maxAttempts, // The number of times that the rate limit can be hit in the given decay period.
    $decaySeconds = 60, // The length of the decay period in seconds. By default, this is a minute.
    $method, // The name of the method that is being rate limited. By default, this is set to the method that `$this->rateLimit()` is called from.
);

/**
 * Hit a method's rate limiter without consequence.
 */
$this->hitRateLimiter(
    $method, // The name of the method that is being rate limited. By default, this is set to the method that `$this->hitRateLimiter()` is called from.
    $decaySeconds = 60, // The length of the decay period in seconds. By default, this is a minute.
);

/**
 * Clear a method's rate limiter.
 */
$this->clearRateLimiter(
    $method, // The name of the method that is being rate limited. By default, this is set to the method that `$this->clearRateLimiter()` is called from.
);

Exceptions

use DanHarrin\LivewireRateLimiting\Exceptions\TooManyRequestsException;

try {
    $this->rateLimit(10);
} catch (TooManyRequestsException $exception) {
    $exception->component; // Class of the component that the rate limit was hit within.
    $exception->ip; // IP of the user that has hit the rate limit.
    $exception->method; // Name of the method that has hit the rate limit.
    $exception->minutesUntilAvailable; // Number of minutes until the rate limit is lifted, rounded up.
    $exception->secondsUntilAvailable; // Number of seconds until the rate limit is lifted.
}

Need Help?

🐞 If you spot a bug with this package, please submit a detailed issue, and wait for assistance.

🤔 If you have a question or feature request, please start a new discussion.

🔐 If you discover a vulnerability within the package, please review our security policy.