Livewire Rate Limiting

https://github.com/danharrin/livewire-rate-limiting
Admin
A Laravel package that allows you to apply rate limiters to Livewire actions for throttling login...
Tokens:17,676
Snippets:107
Trust Score:9.2
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install livewire-rate-limiting via Composer

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/index.md

Install the package with Composer. Requires PHP ^8.0 and Laravel v9.x+.

```bash
composer require danharrin/livewire-rate-limiting
```

--------------------------------

### Basic hitRateLimiter() usage

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Records a failed login attempt manually using the default 60-second decay. This example is from the 'Basic' example section.

```php
public function failedLogin()
{
    $this->hitRateLimiter();
}
```

--------------------------------

### hitRateLimiter() with custom decay and component

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Records an attempt with a one-hour decay window under an explicit key component. This example is from the 'Non-trivial' example section.

```php
$this->hitRateLimiter(method: 'submit', decaySeconds: 3600, component: 'LoginForm');
```

--------------------------------

### getRateLimitKey() basic example

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Inspects the cache key used for the current method by passing the function name to getRateLimitKey().

```php
public function debugKey()
{
    dump($this->getRateLimitKey(__FUNCTION__));
}
```

--------------------------------

### TooManyRequestsException - Advanced Example

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

Example of inspecting all public properties and letting the framework render a 429 response when uncaught.

```APIDOC
## TooManyRequestsException - Advanced Example

### Description
Error handling / advanced — inspect all five public properties and let the framework render the 429 when uncaught.

### Code Example

```php
try {
    $this->rateLimit(3, method: 'submit');
} catch (TooManyRequestsException $exception) {
    // Public properties on the exception:
    logger('rate limit hit', [
        'component' => $exception->component,                  // e.g. App\Http\Livewire\Login
        'method'    => $exception->method,                     // e.g. 'submit'
        'ip'        => $exception->ip,                         // client IP
        'seconds'   => $exception->secondsUntilAvailable,      // exact seconds until the limiter resets
        'minutes'   => $exception->minutesUntilAvailable,      // ceil(seconds / 60)
    ]);

    // Bubble it: because the class extends Symfony's HttpException,
    // Laravel converts an uncaught instance into an HTTP 429 response.
    throw $exception;
}
```

```

--------------------------------

### TooManyRequestsException - Basic Example

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

Example of catching the exception and re-throwing it as a Livewire validation error.

```APIDOC
## TooManyRequestsException - Basic Example

### Description
Read the contextual data and re-throw as a Livewire validation error.

### Code Example

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

class Login extends Component
{
    use WithRateLimiting;

    public $secondsUntilAvailable;

    public function submit()
    {
        try {
            $this->rateLimit(10);
        } catch (TooManyRequestsException $exception) {
            $this->secondsUntilAvailable = $exception->secondsUntilAvailable;

            throw ValidationException::withMessages([
                'email' => "Please wait {$exception->minutesUntilAvailable} minutes before trying again.",
            ]);
        }

        // ... actual login logic
    }
}
```

```

--------------------------------

### clearRateLimiter() basic example

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Resets the rate limiter after successful authentication. The key is based on the calling method, component class, and IP address.

```php
public function authenticated()
{
    $this->clearRateLimiter(); // clears limiter keyed by {this class}|authenticated|{ip}
}
```

--------------------------------

### getRateLimitKey() non-trivial example

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Builds the same key outside the trait (e.g., in a queue job) to use Laravel's RateLimiter directly with identical semantics. It includes the necessary import and uses the same key format.

```php
use Illuminate\Support\Facades\RateLimiter;

$key = 'livewire-rate-limiter:' . sha1('LoginForm' . '|' . 'submit' . '|' . request()->ip());

RateLimiter::tooManyAttempts($key, 3); // same counter the trait would consult
```

--------------------------------

### Basic usage: rateLimit(10) in a Livewire component

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Example of using rateLimit() to allow 10 attempts per 60 seconds (default decay) on a submit action. The component uses the WithRateLimiting trait.

```php
namespace App\Http\Livewire\Login;

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

class Login extends Component
{
    use WithRateLimiting;

    public function submit()
    {
        $this->rateLimit(10); // 10 attempts per 60s (default decay)

        // ... actual login logic
    }
}
```

--------------------------------

### Override method and decay window with named arguments

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Example of calling rateLimit() with named arguments to override the method and decay window, and to specify a component identifier.

```php
$this->rateLimit(maxAttempts: 5, decaySeconds: 3600, method: 'submit', component: 'LoginForm');
```

--------------------------------

### getRateLimitKey

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/README.md

Get the cache key for a method's rate limiter.

```APIDOC
## getRateLimitKey

### Description
Get the cache key for a method's rate limiter.

### Method
`$this->getRateLimitKey()`

### Parameters
- **$method** (string) - Required - The name of the method that is being rate limited.
- **$component** (string|null) - Optional - The component class that is being rate limited. By default, this is set to the current component class.
```

--------------------------------

### Error handling: catch TooManyRequestsException and surface secondsUntilAvailable

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Example of catching the TooManyRequestsException thrown by rateLimit() and converting it to a validation error with the secondsUntilAvailable value.

```php
use DanHarrin\LivewireRateLimiting\Exceptions\TooManyRequestsException;
use Illuminate\Validation\ValidationException;

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.",
        ]);
    }

    // ... actual login logic
}
```

--------------------------------

### Rate limit submit action with rateLimit(10)

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/README.md

Rate limit the 'submit' action to 10 calls per minute. When exceeded, a TooManyRequestsException is thrown and the user gets a validation error with the seconds until the limit lifts.

```php
<?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.",
            ]);
        }
        
        // ...
    }
}
```

--------------------------------

### Import WithRateLimiting trait

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Import the WithRateLimiting trait into a PHP file to use it in a Livewire component.

```php
use DanHarrin\LivewireRateLimiting\WithRateLimiting;
```

--------------------------------

### Livewire rate limiting component methods (rateLimit, isRateLimited, etc.)

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/README.md

Use this reference when you need to call the rate limiting methods on a Livewire component. The methods include rateLimit(), isRateLimited(), hitRateLimiter(), clearRateLimiter(), and getRateLimitKey(), all with default arguments that rely on the calling method and component. rateLimit() throws TooManyRequestsException when the limit is exceeded.

```php
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 = null, // The name of the method that is being rate limited. By default, this is set to the method that `$this->rateLimit()` is called from.
    $component = null, // The component class that is being rate limited. By default, this is set to the current component class.
);

/**
 * Determine whether a Livewire method has reached `$maxAttempts` without incrementing its rate limiter.
 *
 * Use the same `$maxAttempts` value whenever checking or enforcing the same rate limiter.
 */
$this->isRateLimited(
    $maxAttempts, // The number of attempts allowed within the decay period.
    $method = null, // The name of the method that is being checked. By default, this is set to the method that `$this->isRateLimited()` is called from.
    $component = null, // The component class that is being checked. By default, this is set to the current component class.
);

/**
 * Hit a method's rate limiter without consequence.
 */
$this->hitRateLimiter(
    $method = null, // 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.
    $component = null, // The component class that is being rate limited. By default, this is set to the current component class.
);

/**
 * Clear a method's rate limiter.
 */
$this->clearRateLimiter(
    $method = null, // The name of the method that is being rate limited. By default, this is set to the method that `$this->clearRateLimiter()` is called from.
    $component = null, // The component class whose rate limiter should be cleared. By default, this is set to the current component class.
);

/**
 * Get the cache key for a method's rate limiter.
 */
$this->getRateLimitKey(
    $method, // The name of the method that is being rate limited.
    $component = null, // The component class that is being rate limited. By default, this is set to the current component class.
);
```

--------------------------------

### Build rate-limiter key with SHA-1 hash

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/index.md

Constructs the rate-limiter key as a SHA-1 hash of the concatenation '{component}|{method}|{client-IP}' prefixed with 'livewire-rate-limiter:'. Calls sharing the same component, method, and IP use the same counter.

```php
'livewire-rate-limiter:'.sha1($component.'|'.$method.'|'.request()->ip())
```

--------------------------------

### Apply WithRateLimiting trait to a Livewire component

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Apply the trait to a Livewire component class to enable rate limiting on its actions.

```php
class Login extends \Livewire\Component
{
    use \DanHarrin\LivewireRateLimiting\WithRateLimiting;
    // ...
}
```

--------------------------------

### getRateLimitKey() signature

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

The method signature for getRateLimitKey(), which builds a cache key based on component, method, and client IP. It uses a backtrace to resolve the method if null is passed.

```php
protected function getRateLimitKey($method, $component = null)
{
    $method ??= debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, limit: 2)[1]['function'];

    $component ??= static::class;

    return 'livewire-rate-limiter:'.sha1($component.'|'.$method.'|'.request()->ip());
}
```

--------------------------------

### Advanced usage: inspect all public properties and bubble exception for 429

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

Demonstrates catching the exception, logging all five public properties, and re-throwing it so Laravel converts it to an HTTP 429 response because the class extends Symfony's HttpException.

```php
try {
    $this->rateLimit(3, method: 'submit');
} catch (TooManyRequestsException $exception) {
    // Public properties on the exception:
    logger('rate limit hit', [
        'component' => $exception->component,                  // e.g. App\Http\Livewire\Login
        'method'    => $exception->method,                     // e.g. 'submit'
        'ip'        => $exception->ip,                         // client IP
        'seconds'   => $exception->secondsUntilAvailable,      // exact seconds until the limiter resets
        'minutes'   => $exception->minutesUntilAvailable,      // ceil(seconds / 60)
    ]);

    // Bubble it: because the class extends Symfony's HttpException,
    // Laravel converts an uncaught instance into an HTTP 429 response.
    throw $exception;
}
```

--------------------------------

### TooManyRequestsException constructor definition

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

Defines the constructor with four promoted properties: component, method, ip, and secondsUntilAvailable. All are untyped. The constructor sets minutesUntilAvailable by rounding up secondsUntilAvailable divided by 60, and calls the parent constructor with HTTP 429 and a formatted message.

```php
public function __construct(
    public $component,
    public $method,
    public $ip,
    public $secondsUntilAvailable,
)
```

--------------------------------

### Composer autoload PSR-4 mapping for DanHarrin\LivewireRateLimiting

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/index.md

Defines the PSR-4 autoload mapping for the package's namespace to the src directory.

```json
"autoload": {
    "psr-4": {
        "DanHarrin\\LivewireRateLimiting\\": "src"
    }
}
```

--------------------------------

### Parent constructor message format

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

The message passed to the parent HttpException constructor, interpolated with ip, method, component, and secondsUntilAvailable in that order.

```text
Too many requests from [%s] to method [%s] on component: [%s]. Retry in %d seconds.
```

--------------------------------

### getRateLimitKey()

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Generates the cache key used for rate limiting, based on the component, method, and client IP. It returns a string of the form `livewire-rate-limiter:<sha1>`. This method is useful for debugging or for directly interacting with Laravel's RateLimiter.

```APIDOC
## `getRateLimitKey()`

### Description
Generates the cache key used for rate limiting, based on the component, method, and client IP. It returns a string of the form `livewire-rate-limiter:<sha1>`. This method is useful for debugging or for directly interacting with Laravel's RateLimiter.

### Signature
```php
protected function getRateLimitKey($method, $component = null)
```

### Parameters
- **$method** (mixed) - Required - Method name component of the key. Passing `null` triggers the backtrace branch and resolves to the calling method name.
- **$component** (mixed) - Optional - Component class (or identifier) component of the key. Defaults to `static::class`.

### Return Type
string - The cache key in the format `livewire-rate-limiter:<sha1>`.

### Throws
None.

### Example
Basic — inspect the cache key used for the current method:
```php
public function debugKey()
{
    dump($this->getRateLimitKey(__FUNCTION__));
}
```

Non-trivial — build the same key outside the trait (e.g. in a queue job) so Laravel's `RateLimiter` can be addressed directly with identical semantics:
```php
use Illuminate\Support\Facades\RateLimiter;

$key = 'livewire-rate-limiter:' . sha1('LoginForm' . '|' . 'submit' . '|' . request()->ip());

RateLimiter::tooManyAttempts($key, 3); // same counter the trait would consult
```
```

--------------------------------

### rateLimit() method signature

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

The protected method signature for rateLimit() with default parameters. It resolves defaults, builds a key, checks if rate limited, throws TooManyRequestsException if so, otherwise hits the limiter.

```php
protected function rateLimit($maxAttempts, $decaySeconds = 60, $method = null, $component = null)
{
    $method ??= debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, limit: 2)[1]['function'];

    $component ??= static::class;

    $key = $this->getRateLimitKey($method, $component);

    if ($this->isRateLimited($maxAttempts, $method, $component))) {
        $ip = request()->ip();
        $secondsUntilAvailable = RateLimiter::availableIn($key);

        throw new TooManyRequestsException($component, $method, $ip, $secondsUntilAvailable);
    }

    $this->hitRateLimiter($method, $decaySeconds, $component);
}
```

--------------------------------

### rateLimit

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/README.md

Rate limit a Livewire method, `$maxAttempts` times every `$decaySeconds` seconds.

```APIDOC
## rateLimit

### Description
Rate limit a Livewire method, `$maxAttempts` times every `$decaySeconds` seconds.

### Method
`$this->rateLimit()`

### Parameters
- **$maxAttempts** (int) - Required - The number of times that the rate limit can be hit in the given decay period.
- **$decaySeconds** (int) - Optional - The length of the decay period in seconds. By default, this is a minute.
- **$method** (string|null) - Optional - The name of the method that is being rate limited. By default, this is set to the method that `$this->rateLimit()` is called from.
- **$component** (string|null) - Optional - The component class that is being rate limited. By default, this is set to the current component class.

### Throws
- `DanHarrin\LivewireRateLimiting\Exceptions\TooManyRequestsException`
```

--------------------------------

### hitRateLimiter() method signature

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

The protected method signature for hitRateLimiter(). It accepts optional $method, $decaySeconds, and $component parameters. The method uses debug_backtrace to determine the caller method if $method is null, defaults $component to the current class, and calls RateLimiter::hit() with the generated key and decay seconds.

```php
protected function hitRateLimiter($method = null, $decaySeconds = 60, $component = null)
{
    $method ??= debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, limit: 2)[1]['function'];

    $component ??= static::class;

    $key = $this->getRateLimitKey($method, $component);

    RateLimiter::hit($key, $decaySeconds);
}
```

--------------------------------

### hitRateLimiter

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/README.md

Hit a method's rate limiter without consequence.

```APIDOC
## hitRateLimiter

### Description
Hit a method's rate limiter without consequence.

### Method
`$this->hitRateLimiter()`

### Parameters
- **$method** (string|null) - Optional - 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** (int) - Optional - The length of the decay period in seconds. By default, this is a minute.
- **$component** (string|null) - Optional - The component class that is being rate limited. By default, this is set to the current component class.
```

--------------------------------

### getRateLimitKey

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Generates a unique rate limit key for the given method and component.

```APIDOC
## getRateLimitKey

### Description
Generates a unique rate limit key for the given method and component.

### Method
getRateLimitKey

### Parameters
- **$method** (mixed) - Required - The method name to generate a key for.
- **$component** (mixed) - Optional - The component class name. Defaults to the current component class.

### Behavior
Used by other methods to resolve the rate limit key.
```

--------------------------------

### Default resolution of method and component parameters

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Shows the default resolution logic used by trait methods to determine the calling method and component class.

```php
$method ??= debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, limit: 2)[1]['function'];
$component ??= static::class;
```

--------------------------------

### Explicit method and component usage of isRateLimited()

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Checks the limiter for a specific method ('submit') and component ('LoginForm') without incrementing. If blocked, adds an error message.

```php
$blocked = $this->isRateLimited(3, method: 'submit', component: 'LoginForm');

if ($blocked) {
    $this->addError('email', 'Too many attempts. Please retry later.');
}
```

--------------------------------

### Throw TooManyRequestsException from rateLimit() when limiter has max attempts

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/errors.md

The only throw site in the package. When the limiter for the key has reached max attempts, it throws TooManyRequestsException with the component, method, client IP, and seconds until available. The hit is not counted until after this check passes, so the first max attempts are allowed and the exception is thrown on the (max+1)-th call.

```php
if ($this->isRateLimited($maxAttempts, $method, $component)) {
    $ip = request()->ip();
    $secondsUntilAvailable = RateLimiter::availableIn($key);

    throw new TooManyRequestsException($component, $method, $ip, $secondsUntilAvailable);
}
```

--------------------------------

### rateLimit()

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Rate limits a Livewire component method. Throws TooManyRequestsException when the limit is exceeded, otherwise increments the rate limiter.

```APIDOC
## `rateLimit()`

### Description
Rate limits a Livewire component method. Throws TooManyRequestsException when the limit is exceeded, otherwise increments the rate limiter.

### Method
`rateLimit` (PHP method)

### Signature
```php
protected function rateLimit($maxAttempts, $decaySeconds = 60, $method = null, $component = null)
```

### Parameters
- **$maxAttempts** (mixed) - Required - Maximum number of hits allowed within the decay period. When the limiter already records `$maxAttempts` or more hits, the method throws instead of hitting.
- **$decaySeconds** (mixed) - Optional (default: `60`) - Length of the decay window in seconds. Passed through to `RateLimiter::hit($key, $decaySeconds)`, and thus controls how long a hit remains counted.
- **$method** (mixed) - Optional (default: `null` → caller method name via backtrace) - Name of the component method being rate limited. Forms part of the limiter key.
- **$component** (mixed) - Optional (default: `null` → `static::class`) - Component class (or identifier) being rate limited. Forms part of the limiter key.

### Return Type
None declared; returns nothing on success (`void`). On failure it throws — it never returns a value.

### Throws
- **DanHarrin\LivewireRateLimiting\Exceptions\TooManyRequestsException** - When `RateLimiter::tooManyAttempts($key, $maxAttempts)` returns `true` — i.e. the limiter for `{component}|{method}|{ip}` already has `$maxAttempts` recorded hits. The exception is constructed with `$secondsUntilAvailable = RateLimiter::availableIn($key)`.

### Behavior
(1) resolves defaults, (2) builds the key, (3) if `isRateLimited()` → throw; (4) otherwise `hitRateLimiter($method, $decaySeconds, $component)` — so each allowed call increments the counter. A fresh limiter allows the first `$maxAttempts` calls, and the next call within the decay window throws.

### Examples

Basic — allow `10` attempts per minute on a `submit` action:

```php
namespace App\Http\Livewire\Login;

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

class Login extends Component
{
    use WithRateLimiting;

    public function submit()
    {
        $this->rateLimit(10); // 10 attempts per 60s (default decay)

        // ... actual login logic
    }
}
```

Error handling — catch the exception and surface its `secondsUntilAvailable` as a validation error:

```php
use DanHarrin\LivewireRateLimiting\Exceptions\TooManyRequestsException;
use Illuminate\Validation\ValidationException;

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.",
        ]);
    }

    // ... actual login logic
}
```

Non-trivial option — override both the `$method` (so the limiter key is not derived from the calling method) and the decay window, using named arguments:

```php
$this->rateLimit(maxAttempts: 5, decaySeconds: 3600, method: 'submit', component: 'LoginForm');
```

**Livewire/Volt note**: In a Volt anonymous component, `static::class` resolves to the anonymous class name, which is unstable per request. Pass an explicit `$component` identifier, as done in `tests/views/volt-component.blade.php` (`component: 'VoltComponent'`).

Related: `isRateLimited()` (check without incrementing), `hitRateLimiter()` (increment unconditionally).
```

--------------------------------

### Basic usage: catch TooManyRequestsException and re-throw as validation error

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

Shows how to catch the exception in a Livewire component, store the secondsUntilAvailable property, and throw a ValidationException with a message using minutesUntilAvailable. The rateLimit method is called with 10 attempts.

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

class Login extends Component
{
    use WithRateLimiting;

    public $secondsUntilAvailable;

    public function submit()
    {
        try {
            $this->rateLimit(10);
        } catch (TooManyRequestsException $exception) {
            $this->secondsUntilAvailable = $exception->secondsUntilAvailable;

            throw ValidationException::withMessages([
                'email' => "Please wait {$exception->minutesUntilAvailable} minutes before trying again.",
            ]);
        }

        // ... actual login logic
    }
}
```

--------------------------------

### isRateLimited() method signature

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

The protected method signature for isRateLimited(). It uses debug_backtrace to determine the calling method name if not provided, and defaults the component to the current class. It returns the result of RateLimiter::tooManyAttempts().

```php
protected function isRateLimited($maxAttempts, $method = null, $component = null)
{
    $method ??= debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, limit: 2)[1]['function'];

    $component ??= static::class;

    $key = $this->getRateLimitKey($method, $component);

    return RateLimiter::tooManyAttempts($key, $maxAttempts);
}
```

--------------------------------

### isRateLimited

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/README.md

Determine whether a Livewire method has reached `$maxAttempts` without incrementing its rate limiter.

```APIDOC
## isRateLimited

### Description
Determine whether a Livewire method has reached `$maxAttempts` without incrementing its rate limiter.

### Method
`$this->isRateLimited()`

### Parameters
- **$maxAttempts** (int) - Required - The number of attempts allowed within the decay period.
- **$method** (string|null) - Optional - The name of the method that is being checked. By default, this is set to the method that `$this->isRateLimited()` is called from.
- **$component** (string|null) - Optional - The component class that is being checked. By default, this is set to the current component class.
```

--------------------------------

### isRateLimited

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Checks if the current action is rate limited.

```APIDOC
## isRateLimited

### Description
Checks if the current action is rate limited.

### Method
isRateLimited

### Parameters
- **$method** (mixed) - Optional - The method name to check. Defaults to the calling method name.
- **$component** (mixed) - Optional - The component class name. Defaults to the current component class.

### Behavior
Resolves its key via getRateLimitKey().
```

--------------------------------

### Import TooManyRequestsException

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

Use this import statement to include the TooManyRequestsException class in your PHP file.

```php
use DanHarrin\LivewireRateLimiting\Exceptions\TooManyRequestsException;
```

--------------------------------

### TooManyRequestsException::__construct

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

Constructor for the TooManyRequestsException class. It accepts component, method, IP, and seconds until available, and sets a minutes-until-available property. It calls the parent constructor with a 429 status and a formatted message.

```APIDOC
## Constructor

```php
public function __construct(
    public $component,
    public $method,
    public $ip,
    public $secondsUntilAvailable,
)
```

### Description
Creates a new TooManyRequestsException instance. The constructor promotes the four parameters to public properties and sets `$minutesUntilAvailable` to the ceiling of `$secondsUntilAvailable / 60`. It then calls the parent constructor with HTTP status 429 and a formatted message.

### Parameters
- **$component** (mixed) - Required - Component class (or identifier) on which the rate limit was hit. Stored as public property `$component`.
- **$method** (mixed) - Required - Name of the action method that hit the rate limit. Stored as public property `$method`.
- **$ip** (mixed) - Required - Client IP that hit the rate limit (the value of `request()->ip()` captured by `rateLimit()`). Stored as public property `$ip`.
- **$secondsUntilAvailable** (mixed) - Required - Seconds remaining until the limit is lifted (the value of `RateLimiter::availableIn($key)` captured by `rateLimit()`). Stored as public property `$secondsUntilAvailable`.

### Behavior
- Sets `$this->minutesUntilAvailable = ceil($this->secondsUntilAvailable / 60)`.
- Calls `parent::__construct(429, sprintf(...))` with the message: `Too many requests from [%s] to method [%s] on component: [%s]. Retry in %d seconds.` interpolated with `$this->ip`, `$this->method`, `$this->component`, `$this->secondsUntilAvailable` in that order.

### Return Type
None (constructor).

### Throws
None directly. The parent constructor (`Symfony\Component\HttpKernel\Exception\HttpException`) may rethrow `$previous` behavior per Symfony, which is outside this package's source.
```

--------------------------------

### Catch TooManyRequestsException from rateLimit()

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/README.md

Catch the TooManyRequestsException thrown by rateLimit() to access details about the rate limit event. The exception provides properties for the component class, user IP, method name, and the remaining time until the limit resets (in minutes and seconds).

```php
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.
}
```

--------------------------------

### TooManyRequestsException Constructor

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

The constructor for the TooManyRequestsException class. It accepts the component, method, IP, and seconds until available, and sets the minutesUntilAvailable property and the HTTP status code to 429.

```APIDOC
## TooManyRequestsException Constructor

### Description
Constructs a new TooManyRequestsException instance with HTTP status 429 and a human-readable message.

### Method
Constructor

### Signature
```php
public function __construct(
    public $component,
    public $method,
    public $ip,
    public $secondsUntilAvailable,
)
```

### Parameters
- **$component** (mixed) - Required - The Livewire component name or identifier.
- **$method** (string) - Required - The method name that was rate limited.
- **$ip** (string) - Required - The IP address of the client.
- **$secondsUntilAvailable** (int) - Required - The number of seconds until the rate limit resets.

### Properties
- **$minutesUntilAvailable** (float) - The number of minutes until available, calculated as ceil($secondsUntilAvailable / 60).

### Behavior
- Sets the HTTP status code to 429 (Too Many Requests).
- Sets the message to: `Too many requests from [ip] to method [method] on component: [component]. Retry in [seconds] seconds.`

### Example
```php
throw new TooManyRequestsException(
    component: 'App\\Livewire\\ContactForm',
    method: 'submit',
    ip: '127.0.0.1',
    secondsUntilAvailable: 30,
);
```
```

--------------------------------

### Basic usage of isRateLimited()

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Checks if the current method's limiter has reached the maximum attempts (3) without incrementing. Used to conditionally disable a resend button.

```php
public function resendDisabled(): bool
{
    return $this->isRateLimited(3); // limiter for this method, 3 attempts max
}
```

--------------------------------

### hitRateLimiter

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Increments the rate limiter counter for the current action.

```APIDOC
## hitRateLimiter

### Description
Increments the rate limiter counter for the current action.

### Method
hitRateLimiter

### Parameters
- **$method** (mixed) - Optional - The method name to hit. Defaults to the calling method name.
- **$component** (mixed) - Optional - The component class name. Defaults to the current component class.

### Behavior
Resolves its key via getRateLimitKey().
```

--------------------------------

### clearRateLimiter() with explicit method and component

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Clears a specific limiter that was enforced under an explicit method name, matching a prior rateLimit call with method: 'submit' and component: 'LoginForm'.

```php
$this->clearRateLimiter(method: 'submit', component: 'LoginForm');
```

--------------------------------

### clearRateLimiter() signature

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

The method signature for clearRateLimiter(), which clears the rate limiter for a given method and component. It uses a backtrace to determine the calling method if not provided, and defaults the component to the current class.

```php
protected function clearRateLimiter($method = null, $component = null)
{
    $method ??= debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, limit: 2)[1]['function'];

    $component ??= static::class;

    $key = $this->getRateLimitKey($method, $component);

    RateLimiter::clear($key);
}
```

--------------------------------

### rateLimit

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Rate limits the current component action. Throws TooManyRequestsException if the limit is exceeded.

```APIDOC
## rateLimit

### Description
Rate limits the current component action. Throws TooManyRequestsException if the limit is exceeded.

### Method
rateLimit

### Parameters
- **$maxAttempts** (mixed) - Required - Maximum number of attempts allowed.
- **$decaySeconds** (mixed) - Optional - Number of seconds before the limit resets. Defaults to 60.
- **$method** (mixed) - Optional - The method name to rate limit. Defaults to the calling method name.
- **$component** (mixed) - Optional - The component class name. Defaults to the current component class.

### Behavior
Delegates to isRateLimited(), hitRateLimiter(), and getRateLimitKey(). Throws TooManyRequestsException if rate limited.
```

--------------------------------

### TooManyRequestsException class signature

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

The full class definition. It extends HttpException and is constructed with a 429 status code and a message built from the provided arguments. The minutesUntilAvailable property is calculated from secondsUntilAvailable.

```php
namespace DanHarrin\LivewireRateLimiting\Exceptions;

use Symfony\Component\HttpKernel\Exception\HttpException;

class TooManyRequestsException extends HttpException
{
    public $minutesUntilAvailable;

    public function __construct(
        public $component,
        public $method,
        public $ip,
        public $secondsUntilAvailable,
    ) {
        $this->minutesUntilAvailable = ceil($this->secondsUntilAvailable / 60);

        parent::__construct(429, sprintf(
            'Too many requests from [%s] to method [%s] on component: [%s]. Retry in %d seconds.',
            $this->ip,
            $this->method,
            $this->component,
            $this->secondsUntilAvailable,
        ));
    }
}
```

--------------------------------

### Resolve default $method via debug_backtrace

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/index.md

Used to automatically determine the calling method name when $method is not explicitly provided. Requires PHP 8.0+ due to the named argument 'limit: 2'. Passing an explicit $method skips the backtrace.

```php
$method ??= debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, limit: 2)[1]['function'];
```

--------------------------------

### TooManyRequestsException - Public Properties

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

Lists the public properties of the TooManyRequestsException class, including their types, how they are set, and descriptions.

```APIDOC
## TooManyRequestsException - Public Properties

### Description
All declared or promoted public properties are untyped.

### Properties

| Property | Type | Set by | Description |
|----------|------|--------|-------------|
| `$component` | mixed (untyped) | constructor promotion | Component class (or identifier) the rate limit was hit within. |
| `$method` | mixed (untyped) | constructor promotion | Name of the method that hit the rate limit. |
| `$ip` | mixed (untyped) | constructor promotion | IP address of the user who hit the rate limit. |
| `$secondsUntilAvailable` | mixed (untyped) | constructor promotion | Seconds until the rate limit is lifted (mirrors `RateLimiter::availableIn()`). |
| `$minutesUntilAvailable` | mixed (untyped) | constructor body (`ceil($secondsUntilAvailable / 60)`) | Minutes until the rate limit is lifted, rounded up. Read this instead of a 60-division when you need a whole-minute value. |

```

--------------------------------

### TooManyRequestsException - Inherited API

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/TooManyRequestsException.md

Documents the methods inherited from Symfony's HttpException that are available on TooManyRequestsException instances.

```APIDOC
## TooManyRequestsException - Inherited API

### Description
Not defined in this package's source — provided by the parent class `Symfony\Component\HttpKernel\Exception\HttpException`.

### Methods

- `getStatusCode(): int` — returns the HTTP status code; `429` for instances constructed by `rateLimit()`.
- `getHeaders(): array` — returns the response headers array passed to the parent constructor.
- `setHeaders(array $headers): void` — replaces the headers.

The exception is an instance of `Symfony\Component\HttpKernel\Exception\HttpExceptionInterface` and of `Throwable`, and carries the message/status returned by the constructor above.

```

--------------------------------

### clearRateLimiter

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Clears the rate limiter counter for the current action.

```APIDOC
## clearRateLimiter

### Description
Clears the rate limiter counter for the current action.

### Method
clearRateLimiter

### Parameters
- **$method** (mixed) - Optional - The method name to clear. Defaults to the calling method name.
- **$component** (mixed) - Optional - The component class name. Defaults to the current component class.

### Behavior
Resolves its key via getRateLimitKey().
```

--------------------------------

### TooManyRequestsException

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/README.md

Exception thrown when a rate limit is exceeded.

```APIDOC
## TooManyRequestsException

### Description
Exception thrown when a rate limit is exceeded.

### Properties
- **$component** (string) - Class of the component that the rate limit was hit within.
- **$ip** (string) - IP of the user that has hit the rate limit.
- **$method** (string) - Name of the method that has hit the rate limit.
- **$minutesUntilAvailable** (int) - Number of minutes until the rate limit is lifted, rounded up.
- **$secondsUntilAvailable** (int) - Number of seconds until the rate limit is lifted.
```

--------------------------------

### Catch TooManyRequestsException to handle rate limit with custom message

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/errors.md

Catches the specific TooManyRequestsException from the rate limiter. The exception provides the secondsUntilAvailable property for a user-friendly retry message. Use this when you need to access the remaining wait time or handle the exception locally.

```php
use DanHarrin\LivewireRateLimiting\Exceptions\TooManyRequestsException;

try {
    $this->rateLimit(10);
} catch (TooManyRequestsException $exception) {
    throw \Illuminate\Validation\ValidationException::withMessages([
        'email' => "Slow down! Please wait another {$exception->secondsUntilAvailable} seconds to log in.",
    ]);
}
```

--------------------------------

### clearRateLimiter()

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/api-reference/WithRateLimiting.md

Clears the rate limiter for a given method and component. It resolves the method name from the caller if not provided, and uses the component class by default. This is typically called after successful authentication to reset the throttling window.

```APIDOC
## `clearRateLimiter()`

### Description
Clears the rate limiter for a given method and component. It resolves the method name from the caller if not provided, and uses the component class by default. This is typically called after successful authentication to reset the throttling window.

### Signature
```php
protected function clearRateLimiter($method = null, $component = null)
```

### Parameters
- **$method** (mixed) - Optional - Method name whose limiter is cleared. Defaults to the caller method name via backtrace.
- **$component** (mixed) - Optional - Component class (or identifier) whose limiter is cleared. Defaults to `static::class`.

### Return Type
void

### Throws
None.

### Example
Basic — reset the limiter after successful authentication:
```php
public function authenticated()
{
    $this->clearRateLimiter(); // clears limiter keyed by {this class}|authenticated|{ip}
}
```

Non-trivial — clear a specific limiter that was enforced under an explicit method name (matching `$this->rateLimit(3, method: 'submit')`):
```php
$this->clearRateLimiter(method: 'submit', component: 'LoginForm');
```
```

--------------------------------

### Catch HttpExceptionInterface to handle rate limit and other HTTP exceptions

Source: https://github.com/danharrin/livewire-rate-limiting/blob/2.x/_autodocs/errors.md

Catch the Symfony parent interface HttpExceptionInterface, which includes TooManyRequestsException and any other Symfony HttpException. The code comment shows that getStatusCode() returns 429 for the rate limit case. Use when you want to handle all HTTP exceptions uniformly.

```php
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;

try {
    $this->rateLimit(10);
} catch (HttpExceptionInterface $exception) {
    // $exception->getStatusCode() === 429
}
```
Tokens:
Raw