README

SuperBan Laravel包是一个强大的工具，旨在通过高效管理和限制超过预定义请求限制的用户或客户端，来增强您应用程序的安全性和性能。此包特别适用于滥用或过多请求可能对您应用程序的稳定性和响应能力构成威胁的场景。

安装

您可以通过composer安装此包

composer require mane-olawale/superban

配置

此包可以在不进行任何配置的情况下使用，但您也可以根据需要更改某些设置。

首先通过运行将包配置发布到您的配置目录中

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

然后添加 SUPERBAN_DRIVER 到您的 .env 文件中，如下所示

SUPERBAN_DRIVER=redis

使用

全局禁止中间件

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

在提供的Laravel路由定义中，已将superban中间件应用于一组路由，指定参数100,3,2880。让我们分析一下这些参数的含义

100: 这表示在定义的时间框架内允许的最大请求数量。
3: 第二个参数表示允许指定数量的请求的时间框架的持续时间。在这种情况下，它设置为3分钟。
2880: 第三个参数定义了当用户或客户端超过允许的请求限制时对用户或客户端实施的禁止持续时间。在这个例子中，禁止持续时间为2880分钟，相当于2天。

总之，superban中间件已配置为对一组路由强制执行速率限制。用户或客户端在3分钟的时间窗口内允许最多100次请求。如果用户超过此限制，则将被禁止2880分钟（2天）。这种设置有助于控制和管理潜在的滥用或过多请求，从而有助于提高Laravel应用程序的整体安全性和稳定性。

注意：至关重要的是，当superban中间件应用于路由或路由组时，确保实施的禁止是普遍适用的。以下是一个特定路由禁止的示例。

特定路由禁止中间件

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

或者

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

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

在给定的Laravel路由定义中，superban_route中间件对每个路由强制执行速率限制和用户禁止。

默认值

如果没有或提供的参数少于superban和superban_route中间件，则假定默认值。

默认值设置为在2分钟的时间框架内允许200次请求，随后的禁止持续时间为1440分钟（相当于1天）。

这种方法确保了即使未显式定义自定义参数，中间件也能正常工作，在灵活性和易用性之间提供了平衡。

HTTP响应

当用户或客户端被禁止时，返回一个403禁止响应代码。响应的内容根据客户端期望的格式而变化。如果客户端期望JSON，则响应包含包含消息和禁止到期时间的JSON有效负载。否则，返回一个纯文本响应。

禁止用户的JSON响应

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);

“message”键提供了对禁止的易于理解的解释，“until”键指定禁止生效的日期和时间。另一方面，纯文本响应包含具有相同禁止详细信息的纯文本消息。这种方法确保响应格式符合客户端的期望，为暂时被禁止的用户提供清晰一致的信息。

禁止用户的文本响应

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

提供了一个纯文本消息，传达了对禁令的人类可读解释，就像在JSON响应中一样。此外，为了与JSON格式保持一致，HTTP响应头中包含了一个名为'banned-until'的自定义头。此头与JSON响应中的'until'键具有相同的目的，指示禁令有效的日期和时间。这种方法确保无论客户端期望的响应格式如何，都能收到关于临时禁令的清晰且一致的信息。

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;
});

Superban中的banResponseUsing方法允许您自定义在用户或客户端被禁用时发送的响应。此回调函数接受三个参数

$request: 代表当前的HTTP请求。您可以访问有关请求的信息，从而根据特定条件或请求属性动态自定义响应。
$until: 指示禁令有效的日期和时间。
$default: 代表Superban会生成的默认响应。这包括默认的HTTP状态码和如果未指定自定义响应则会发送的内容。

在提供的示例中，自定义响应是一个简单的文本响应“举手！”以及一个401 Unauthorized HTTP状态码。这展示了您如何完全自定义禁令响应以符合应用程序的要求，提供灵活地构建消息和状态码的能力，以适应您的特定用例。

许可协议

MIT许可协议（MIT）。有关更多信息，请参阅许可文件。

mane-olawale / superban

维护者

详细信息