Superban is a Laravel package that bans API clients for a specified period after they exceed a rate limit. It goes beyond Laravel's built-in rate limiter by keeping persistent ban records, supporting progressive escalation, and providing operational commands and events.
- PHP
^8.3 - Laravel
^12.0 || ^13.0
For Laravel 10 / 11 projects, use the ^1.0 line (latest 1.0.2).
composer require victorive/superbanPublish the configuration file:
php artisan vendor:publish --tag="superban-config"Publish translations (optional):
php artisan vendor:publish --tag="superban-lang"Publish database migrations if you want audit persistence (required for superban:list and superban:prune):
php artisan vendor:publish --tag="superban-migrations"
php artisan migrateKey environment variables:
| Variable | Default | Description |
|---|---|---|
SUPERBAN_ENABLED |
true |
Globally enable or disable enforcement. |
SUPERBAN_STORE |
null |
Cache store name; null uses the default cache store. Redis is recommended for production. |
SUPERBAN_PREFIX |
superban |
Prefix for cache/database keys. |
SUPERBAN_CRITERIA |
ip |
Identity criterion: ip, user_id, email, api_key, or a comma-separated composite such as ip,user_id. |
SUPERBAN_SCOPE |
global |
How bans are scoped: global, route, or route_name. |
See config/superban.php for allow/deny lists, escalation, response formatting, audit, shadow mode, and named limits.
The legacy inline syntax is still supported:
Route::middleware(['superban:100,2,720'])->group(function () {
// 100 max attempts, 2 minute decay window, 720 minute ban
});You can also reference a named limit from the config:
Route::middleware(['superban:api'])->group(function () {
// uses config('superban.limits.api')
});'superban' => [
'criteria' => 'ip', // ban by IP address
'criteria' => 'user_id', // ban by authenticated user id (falls back to ip for guests)
'criteria' => 'email', // ban by authenticated user email (falls back to ip for guests)
'criteria' => 'api_key', // ban by request header / query api_key
'criteria' => 'ip,user_id',// composite identity requiring both
],'superban' => [
'allowlist' => [
'enabled' => true,
'ips' => ['127.0.0.1', '10.0.0.0/8'],
'users' => ['1', '2'],
'emails' => ['admin@example.com'],
'routes' => ['health'],
],
'denylist' => [
'enabled' => true,
'ips' => ['192.0.2.0/24'],
'users' => ['99'],
],
],'superban' => [
'escalation' => [
'enabled' => true,
'ladder' => [5, 60, 1440], // minutes for 1st, 2nd, 3rd strike
'reset_after_minutes' => 1440,
'max_minutes' => 10080,
],
],use Victorive\Superban\DTO\Identity;
use Victorive\Superban\Facades\Superban;
// Manual ban
Superban::ban(new Identity('user_id', '42'), 60, 'abuse');
// Check / lift
if (Superban::isBanned(new Identity('user_id', '42'))) {
Superban::unban(new Identity('user_id', '42'));
}php artisan superban:ban user:42 --minutes=60 --reason=abuse
php artisan superban:unban user:42
php artisan superban:status user:42
php artisan superban:list
php artisan superban:prune --days=90Subscribe to these events in your application:
Victorive\Superban\Events\LimitExceededVictorive\Superban\Events\ClientBannedVictorive\Superban\Events\ClientUnbannedVictorive\Superban\Events\BanExpired
Events can be disabled via superban.events.
Use the fake helper to write deterministic tests:
use Victorive\Superban\DTO\Identity;
use Victorive\Superban\Facades\Superban;
public function test_banned_users_are_blocked(): void
{
$fake = Superban::fake();
Superban::ban(new Identity('user_id', '1'), 10);
$fake->assertBanned(new Identity('user_id', '1'));
}composer checkThis runs Pint, PHPStan, and PHPUnit. Individual commands:
vendor/bin/pint --test
vendor/bin/phpstan analyse
vendor/bin/phpunitSee UPGRADE.md for migration notes from 1.x to 2.0.
See CHANGELOG.md.
Contributions are welcome! Please open an issue or pull request.
The MIT License. See LICENSE.md.