README

Banhammer for Laravel 提供了一种非常简单的方法来通过 ID 和 IP 禁止任何模型。它还允许通过 IP 地址阻止请求。

被禁止的模型可以有一个过期日期，并将通过调度器自动解除禁止。

版本兼容性

安装

您可以通过 composer 安装此包

composer require mchev/banhammer

然后使用以下命令发布和运行迁移

有关 UUID 的信息，请参阅 UUIDs

php artisan vendor:publish --provider="Mchev\Banhammer\BanhammerServiceProvider" --tag="migrations"
php artisan migrate

您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="Mchev\Banhammer\BanhammerServiceProvider" --tag="config"

您可以在 config/ban.php 文件中定义表名、模型和 fallback_url。

用法

要使模型可禁止，请将 Mchev\Banhammer\Traits\Bannable 特性添加到模型中

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Mchev\Banhammer\Traits\Bannable;

class User extends Authenticatable
{
    use Bannable;
}

您可以在任何数量的模型上添加 Bannable 特性（Team、Group、User 等）。

禁止/解除禁止

简单禁止

$user->ban();

如果没有指定 expired_at 属性，则用户将永远被禁止。

IP 禁止

$user->ban([
	'ip' => $user->ip,
]);

完整

所有属性都是可选的

$model->ban([
	'created_by_type' => 'App\Models\User',
	'created_by_id' => 1,
	'comment' => "You've been evil",
	'ip' => "8.8.8.8",
	'expired_at' => Carbon::now()->addDays(7),
	'metas' => [
		'route' => request()->route()->getName(),
		'user_agent' => request()->header('user-agent')
	]
]);

简写

$user->banUntil('2 days');

检查模型是否被禁止。

您可以使用这些方法创建自定义中间件。

$model->isBanned();
$model->isNotBanned();

列出模型禁止

// All model bans
$bans = $model->bans()->get();

// Expired bans
$expired = $model->bans()->expired()->get();

// Not expired and permanent bans
$notExpired = $model->bans()->notExpired()->get();

过滤器

$bannedTeams = Team::banned()->get(); 
$notBannedTeams = Team::notBanned()->get();

除了 notBanned() 之外，您还可以使用 banned() 范围来过滤未禁止的模型： Team::banned(false)。这样，您可以使用 banned 范围，例如 spatie/laravel-query-builder 范围过滤器，而不是使用更复杂的方法来应用 banned 或 notBanned 范围。

解除禁止

$user->unban();

IP

禁止 IP

use Mchev\Banhammer\IP;

IP::ban("8.8.8.8");
IP::ban(["8.8.8.8", "4.4.4.4"]);

// Ban IP with expiration date
IP::ban("8.8.8.8", [], now()->addMinutes(10));

// Full
IP::ban(
    "8.8.8.8", 
    [
        "MetaKey1" => "MetaValue1",
        "MetaKey2" => "MetaValue2",
    ], 
    now()->addMinutes(10)
);

解除 IP 禁止

use Mchev\Banhammer\IP;

IP::unban("8.8.8.8");
IP::unban(["8.8.8.8", "4.4.4.4"]);

列出所有禁止的 IP

use Mchev\Banhammer\IP;

$ips = IP::banned()->get(); // Collection
$ips = IP::banned()->pluck('ip')->toArray(); // Array

元数据

使用元数据禁止 IP

use Mchev\Banhammer\IP;

IP::ban("8.8.8.8", [
	'route' => request()->route()->getName(),
	'user_agent' => request()->header('user-agent')
]);

元数据使用

$ban->setMeta('username', 'Jane');
$ban->getMeta('username'); // Jane
$ban->hasMeta('username'); // boolean
$ban->forgetMeta('username');

按元数据过滤

IP::banned()->whereMeta('username', 'Jane')->get();
// OR
$users->bans()->whereMeta('username', 'Jane')->get();
// OR
$users->whereBansMeta('username', 'Jane')->get();

阻止来自特定国家的访问

为了增强您应用程序的安全性，您可以通过在配置文件中启用国家阻止功能来限制来自特定国家的访问。按照以下简单步骤操作

打开您的 Banhammer 配置文件（config/ban.php）。
将 'block_by_country' 配置选项设置为 true 以启用基于国家的阻止。

'block_by_country' => true,

通过将国家代码添加到 'blocked_countries' 数组中，指定您要阻止的国家列表。

'blocked_countries' => ['FR', 'ES'],

通过配置这些设置，您可以有效地阻止来自指定国家的用户访问您的应用程序。这有助于通过防止来自您已识别为潜在风险的地区的未经请求的流量来提高您系统的安全性和完整性。

重要通知： Banhammer 包使用 ip-api.com 的免费版进行地理位置数据。请注意，它们端点的限制为单个 IP 地址每分钟 45 个 HTTP 请求。如果您超过此限制，您的请求将被限制，并且您可能会收到 429 HTTP 状态码，直到速率限制窗口重置。

开发者注意： 虽然 Banhammer 目前依赖于 ip-api.com 的免费版进行地理位置数据，但我愿意探索更好的替代方案。如果您有更健壮或更高效的解决方案的建议，或者如果您想贡献改进，请随时提交问题或提交拉取请求。

中间件

要防止被禁止的用户访问您应用程序的某些部分，只需在相关路由上添加 auth.banned 中间件。

Route::middleware(['auth.banned'])->group(function () {
    // ...
});

要防止被禁止的 IP 地址访问您应用程序的某些部分，只需在相关路由上添加 ip.banned 中间件。

Route::middleware(['ip.banned'])->group(function () {
    // ...
});

要阻止和注销被禁止的用户或 IP，请添加 logout.banned 中间件。

Route::middleware(['logout.banned'])->group(function () {
    // ...
});

如果您使用 logout.banned 中间件，则不需要累积其他中间件。

如果您希望在应用程序的每个 HTTP 请求上阻止 IP，请在您的 app/Http/Kernel.php 类的 $middleware 属性中列出 Mchev\Banhammer\Middleware\IPBanned。

调度器

⚠ 重要

为了能够自动删除过期的禁止，您必须在服务器上设置 cron 作业以运行 Laravel 定时作业。

运行调度器

在 Forge 上配置调度器

事件

如果实体被禁止，将触发 Mchev\Banhammer\Events\ModelWasBanned 事件。

如果实体被解禁，将触发 Mchev\Banhammer\Events\ModelWasUnbanned 事件。

其他

要手动解禁过期的禁止

use Mchev\Banhammer\Banhammer;

Banhammer::unbanExpired();

或者您可以使用以下命令

php artisan banhammer:unban

永久删除所有过期的禁止

use Mchev\Banhammer\Banhammer;

Banhammer::clear();

或者您可以使用以下命令

php artisan banhammer:clear

UUIDs

要使用 UUID，请确保发布并编辑迁移文件。

php artisan vendor:publish --provider="Mchev\Banhammer\BanhammerServiceProvider" --tag="migrations"

- $table->id();
+ $table->uuid('id');

然后您需要创建一个继承自 Mchev\Banhammer\Models\Ban 的模型。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Mchev\Banhammer\Models\Ban as BanhammerBan;

class Ban extends BanhammerBan
{
    use HasUuids;
}

尽管所需的大部分方法已经从基础模型中可用，但您可以在其中添加任何额外的功能。

最后，更新已发布的 ban.php 配置文件以加载您创建的模型。

    /*
    |--------------------------------------------------------------------------
    | Model Name
    |--------------------------------------------------------------------------
    |
    | Specify the model which you want to use as your Ban model.
    |
    */

-   'model' => \Mchev\Banhammer\Models\Ban::class,
+   'model' => \App\Models\YouBanClass::class,

从 1.x 升级到 2.0

要升级到 Banhammer 版本 2.0，请按照以下简单步骤操作

更新您的应用程序的 composer.json 文件中的包版本。

"require": {
    "mchev/banhammer": "^2.0"
}

在您的终端中运行以下命令

composer update mchev/banhammer

更新配置
1. 更新配置
  - 备份位于 config/ban.php 的旧配置文件。
  - 使用以下命令强制重新发布新配置
```
php artisan vendor:publish --provider="Mchev\Banhammer\BanhammerServiceProvider" --tag="config" --force
```
  - 审查新配置文件并做出任何必要的编辑。

测试

composer test

变更日志

请参阅变更日志了解最近更改的更多信息。

路线图 / 待办事项

Laravel 脉冲卡（禁止的 IP，按国家封锁启用等）。
按国家封锁功能

贡献

为了鼓励积极的协作，Banhammer 强烈鼓励提交拉取请求，而不仅仅是错误报告。只有标记为“准备审查”的拉取请求（不在“草案”状态）并且所有新功能的测试都通过时，才会审查拉取请求。在“草案”状态下留下的长期非活跃拉取请求将在几天后被关闭。

但是，如果您提交错误报告，您的报告应包含标题和对问题的清晰描述。您还应包括尽可能多的相关信息和演示问题的代码示例。错误报告的目标是使您和其他人能够轻松复制错误并开发解决方案。

请记住，错误报告是在希望有相同问题的其他人能够与你协作解决问题时创建的。不要期望错误报告会自动看到任何活动，或者其他人会立即修复它。

安全漏洞

请查看我们的安全策略，了解如何报告安全漏洞：我们的安全策略

鸣谢

受到来自cybercog的laravel-ban的启发

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。

mchev / banhammer

维护者

详细信息