PHPackages                             mane-olawale/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. [Security](/categories/security)
4. /
5. mane-olawale/superban

ActiveLibrary[Security](/categories/security)

mane-olawale/superban
=====================

A Laravel package for for banning suspicious HTTP clients.

v0.1(2y ago)2488MITPHPPHP ^8.0

Since Dec 22Pushed 2y ago1 watchersCompare

[ Source](https://github.com/Mane-Olawale/superban)[ Packagist](https://packagist.org/packages/mane-olawale/superban)[ Docs](https://github.com/mane-olawale/superban)[ RSS](/packages/mane-olawale-superban/feed)WikiDiscussions main Synced yesterday

READMEChangelog (1)Dependencies (5)Versions (2)Used By (0)

SuperBan Laravel Package
========================

[](#superban-laravel-package)

[![Github](https://github.com/Mane-Olawale/superban/actions/workflows/tests.yml/badge.svg)](https://github.com/Mane-Olawale/superban)[![Total Downloads](https://camo.githubusercontent.com/661db3aa2c3470a9985c123445ee882a83e1ec13cab55ff9efcc02e434ccf4f1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d616e652d6f6c6177616c652f737570657262616e)](https://packagist.org/packages/mane-olawale/superban)[![Latest Stable Version](https://camo.githubusercontent.com/16b8b0ba3041062b7ef968ad66a3ffe0e4553d817410e26f8cb77c95f459af05/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d616e652d6f6c6177616c652f737570657262616e)](https://packagist.org/packages/mane-olawale/superban)[![License](https://camo.githubusercontent.com/993277ca32280748ea3201c3437b0ce1e0cd53ded6303efdf9cdc43aa20e5a2d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6d616e652d6f6c6177616c652f737570657262616e)](https://packagist.org/packages/mane-olawale/superban)

The SuperBan Laravel package is a powerful tool designed to enhance your application's security and performance by efficiently managing and restricting users or clients who exceed predefined request limits. This package is particularly useful in scenarios where abusive or excessive requests can pose a threat to your application's stability and responsiveness.

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

[](#installation)

You can install the package via composer:

```
composer require mane-olawale/superban
```

Configuration
-------------

[](#configuration)

This package can be used without any configuration, but you can as well change something to what you prefer.

First publish the package config to your config directory by running

```
php artisan vendor:publish --provider="ManeOlawale\Superban\SuperbanServiceProvider" --tag="superban.config"
```

Then add `SUPERBAN_DRIVER` to your .env like so:

```
SUPERBAN_DRIVER=redis
```

Usage
-----

[](#usage)

### Global banning middleware

[](#global-banning-middleware)

```
Route::middleware(['superban:100,3,2880'])->group(function () {
    Route::post('/audio', function () {
        // ...
    });

    Route::post('/video', function () {
        // ...
    });
});
```

In the provided Laravel route definition, the `superban` middleware has been applied to a group of routes, specifying the parameters `100,3,2880`. Let's break down what each of these parameters signifies:

- **`100`:** This represents the maximum number of allowed requests within the defined time frame.
- **`3`:** The second argument denotes the duration of the time frame in which the specified number of requests is allowed. In this case, it is set to 3 minutes.
- **`2880`:** The third argument defines the duration of the ban imposed on the user or client in case they exceed the allowed request limit. In this example, the ban lasts for 2880 minutes, which is equivalent to 2 days.

In summary, the `superban` middleware has been configured to enforce rate limiting on the group of routes. Users or clients are allowed a maximum of 100 requests within a 3-minute time window. If a user exceeds this limit, they will be banned for 2880 minutes (2 days). This setup helps to control and mitigate potential abuse or excessive requests, contributing to the overall security and stability of the Laravel application.

> **Note:** Crucially, the `superban` middleware, when applied to an route or group, ensures that the resulting ban is universally enforced. Below is a example of a route specific ban.

### Route specific banning middleware

[](#route-specific-banning-middleware)

```
Route::middleware(['superban_route:100,3,2880'])->group(function () {
    Route::post('/audio', function () {
        // ...
    });

    Route::post('/video', function () {
        // ...
    });
});
```

**`OR`**

```
Route::post('/audio', function () {
    // ...
})->middleware(['superban_route:100,3,2880']);

Route::post('/video', function () {
    // ...
})->middleware(['superban_route:100,3,2880']);
```

In the given Laravel route definition, the `superban_route` middleware enforces rate limiting and user banning on a per-route basis.

Default value
-------------

[](#default-value)

If no or fewer arguments are explicitly provided for the `superban` and `superban_route` middleware, default values will be assumed.

The defaults are set to allow 200 requests within a 2-minute time frame, with a subsequent ban duration of 1440 minutes (equivalent to 1 day).

This approach ensures that the middleware is functional even when custom parameters are not explicitly defined, providing a balance between flexibility and ease of use.

HTTP response
-------------

[](#http-response)

When a user or client is banned, a `403 Forbidden` response code is returned. The content of the response varies based on the client's expected format. If the client expects JSON, the response contains a JSON payload with a message and the ban expiration timestamp. Otherwise, a plain text response is returned.

### JSON Response for Banned Users:

[](#json-response-for-banned-users)

```
response()->json([
    'message' => 'Sorry, you\'re temporarily banned. Please return after Dec 22, 2023, 10:57 pm.',
    'until' => '2023-12-22 22:57:28'
], 403);
```

The `message` key provides a human-readable explanation of the ban, and the `until` key specifies the date and time until which the ban is effective. On the other hand, the text response includes a plain text message with the same ban details. This approach ensures that the response format aligns with the client's expectations, providing a clear and consistent message for users who are temporarily banned.

### Text Response for Banned Users:

[](#text-response-for-banned-users)

```
response(
    'Sorry, you\'re temporarily banned. Please return after Dec 22, 2023, 10:57 pm.',
    403,
    [
        'banned-until' => '2023-12-22 22:57:28'
    ]
);
```

A plain text message is provided, conveying a human-readable explanation of the ban, just like in the JSON response. Additionally, to maintain consistency with the JSON format, a custom header named 'banned-until' is included in the HTTP response headers. This header serves the same purpose as the 'until' key in the JSON response, indicating the date and time until which the ban is effective. This approach ensures that clients, regardless of their expected response format, receive clear and consistent information about the temporary ban.

### Custom Ban Response Handling in Superban

[](#custom-ban-response-handling-in-superban)

```
use Illuminate\Http\Request;
use Illuminate\Support\Carbon;
use ManeOlawale\Superban\Superban;

Superban::banResponseUsing(function (Request $request, Carbon $until, $default) {
    if (/* Check something */) {
        return response('Hands up!', 401);
    }
    return $default;
});
```

The `banResponseUsing` method in Superban allows you to customize the response that is sent when a user or client is banned. This callback function takes three parameters:

1. **`$request`:** Represents the current HTTP request. You can access information about the request, allowing for dynamic response customization based on specific conditions or request attributes.
2. **`$until`:** Indicates the date and time until which the ban is effective.
3. **`$default`:** Represents the default response that Superban would generate. This includes the default HTTP status code and content that would be sent if a custom response is not specified.

In the provided example, the custom response is a simple text response of 'Hands up!' with a `401 Unauthorized` HTTP status code. This showcases how you can completely customize the ban response to fit your application's requirements, providing flexibility in crafting messages and status codes tailored to your specific use case.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

22

—

LowBetter than 21% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity15

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity37

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

924d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4cdd5ab20a519718723a826066fab0fcb28bf76bd8fd68a4220d82545ef494e7?d=identicon)[mane\_olawale](/maintainers/mane_olawale)

---

Top Contributors

[![Mane-Olawale](https://avatars.githubusercontent.com/u/47121750?v=4)](https://github.com/Mane-Olawale "Mane-Olawale (10 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[illuminate/encryption

The Illuminate Encryption package.

9630.7M325](/packages/illuminate-encryption)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M345](/packages/psalm-plugin-laravel)[laravel-chronicle/core

Tamper-evident audit ledger for Laravel applications.

1213.2k3](/packages/laravel-chronicle-core)

PHPackages © 2026

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