PHPackages                             piusadams/superban - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. piusadams/superban

ActiveLibrary[Authentication & Authorization](/categories/authentication)

piusadams/superban
==================

A Laravel package to ban users by IP address, email address, or id.

05PHP

Since Dec 21Pushed 2y ago1 watchersCompare

[ Source](https://github.com/Adams-Ijachi/superban)[ Packagist](https://packagist.org/packages/piusadams/superban)[ RSS](/packages/piusadams-superban/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

SuperBan
========

[](#superban)

The package provides a middleware called `superban` that you can use to ban users from your application. The middleware checks if the user is banned and if so, it throws a `UserBannedException` which you can catch in your `app/Exceptions/Handler.php` file and redirect the user to a page of your choice.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require piusadams/superban
```

You can manually add the service provider to the `providers` array in `config/app.php`:

```
'providers' => [
    // ...
    PiusAdams\SuperBan\Providers\SuperBanServiceProvider::class,
];
```

Discover the package: You can publish the config file with:

```
php artisan vendor:publish --provider="PiusAdams\SuperBan\Providers\SuperBanServiceProvider"
```

This is the contents of the published config file:

```
return [
    'cache_driver' => env('SUPERBAN_CACHE_DRIVER', 'file'),
    'identity_key' => env('SUPERBAN_IDENTITY_KEY', 'ip'),
];
```

The `cache_driver` option is the cache store that will be used to store the keys. The default is `file` but you can change it to any of the cache stores that Laravel supports.

The `identity_key` option is the key that will be used to identify the user. The default is `ip` but you can change it to `email` or `id`, and if the user is logged in, the middleware will use the user's email or ID to identify the user.

How it works
------------

[](#how-it-works)

The laravel `RateLimiter` class is used by the middleware to count how many times the user tries to access the resource within a certain time period. If the user goes beyond the limit, the middleware creates a key based on the user's Email, ID or IP address and saves it in the cache for that time period. The middleware then looks for the key in the cache and if it finds it, it raises a `UserBannedException`.

Example
-------

[](#example)

The `superban` middleware takes 3 parameters:

1. The number of tries the user has before he gets banned
2. The number of minutes the user can try the route before he gets banned
3. The number of minutes the user is banned

```
Route::get('/home', 'HomeController@index')->middleware('superban:2,3,5');
```

In the above example, the user can try to access the `/home` route 2 times in 3 minutes before he gets banned for 5 minutes.

Testing
-------

[](#testing)

```
vendor/bin/phpunit
```

The command above will run the tests for the package.

1. `testSuperBanMiddlewareBansUsersAfterTries` - This test checks if the middleware bans the user after the number of tries is exceeded.
2. `testSuperBanMiddlewareLiftsBanAfterBanTime` - This test checks if the middleware lifts the ban after the ban time is exceeded.
3. `testSuperBanMiddlewareWorksForMultipleRoutes` - This test checks if the middleware works for multiple routes.
4. `testSuperBanMiddlewareWorksForMultipleRoutesAndLiftsBanAfterBanTime` - This test checks if the middleware works for multiple routes and lifts the ban after the ban time is exceeded.
5. `testCacheStoreIsSet` - This test checks if the cache store is set.
6. `testFileCacheStoreIsUsed` - This test checks if the file cache store is used.
7. `testSuperBanServiceIsBannedReturnsTrue` - This test checks if the `isBanned` method of the `SuperBanService` class returns true when the user is banned.
8. `testSuperBanServiceIsBannedReturnsFalse` - This test checks if the `isBanned` method of the `SuperBanService` class returns false when the user is not banned.

Exceptions
----------

[](#exceptions)

The package throws 2 exceptions:

1. `UserBannedException` - This exception is thrown when the user is banned with a status code of 403.

###  Health Score

13

—

LowBetter than 1% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity4

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity20

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/906df55edd6e02280f56bb3d2a98d8696bceeedcf545636bdc356a3d33fadbbf?d=identicon)[Adams-Ijachi](/maintainers/Adams-Ijachi)

### Embed Badge

![Health badge](/badges/piusadams-superban/health.svg)

```
[![Health](https://phpackages.com/badges/piusadams-superban/health.svg)](https://phpackages.com/packages/piusadams-superban)
```

###  Alternatives

[namshi/jose

JSON Object Signing and Encryption library for PHP.

1.8k99.6M101](/packages/namshi-jose)[league/oauth1-client

OAuth 1.0 Client Library

99698.8M106](/packages/league-oauth1-client)[bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

2.8k2.9M88](/packages/bezhansalleh-filament-shield)[gesdinet/jwt-refresh-token-bundle

Implements a refresh token system over Json Web Tokens in Symfony

70516.4M35](/packages/gesdinet-jwt-refresh-token-bundle)[league/oauth2-google

Google OAuth 2.0 Client Provider for The PHP League OAuth2-Client

41721.2M118](/packages/league-oauth2-google)[illuminate/auth

The Illuminate Auth package.

9327.3M1.0k](/packages/illuminate-auth)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)