README

Honey是一个用于Laravel的垃圾邮件防护包，提供蜜罐技术、IP封禁和美观简单的Recaptcha集成。停止垃圾邮件。使用Honey。

安装

您可以通过Composer安装Honey。

composer require lukeraymonddowning/honey

您应该使用以下Artisan命令发布Honey的配置文件

php artisan honey:install

最后，您应该运行数据库迁移，这将添加一个垃圾邮件表

php artisan migrate

Honey现已成功安装！

升级

我们在UPGRADE.md文件中记录了任何更改。

用法

使用Honey非常简单。前往您的blade文件中的<form>，并将<x-honey/>作为子元素添加。

<form action="{{ route('some.route') }}" method="POST">
    @csrf
    <input type="email" placeholder="Your email" required />
    <x-honey/>
    <button type="submit">Subscribe!</button>
</form>

现在，在路由文件中，将honey中间件添加到指向您的表单的路由中。

// routes/web.php

Route::post('/test', fn() => event(new RegisterInterest))
    ->middleware(['honey'])
    ->name('some.route');

就是这样！您的路由现在受到垃圾邮件的保护。如果您想更进一步，请继续阅读...

Recaptcha

Honey使您能够轻松地将Google的Recaptcha集成到您的Laravel网站中。我们与Recaptcha v3集成，以实现无缝且无形的机器人预防。以下是开始的方法。

首先，您需要从Google获取密钥对。您可以在以下位置获取您的密钥： https://g.co/recaptcha/v3。进入您的.env文件，并添加您的密钥对。

# .env

RECAPTCHA_SITE_KEY=YOUR_RECAPTCHA_SITE_KEY
RECAPTCHA_SECRET_KEY=YOUR_RECAPTCHA_SECRET_KEY

我们即将完成。前往您的blade文件，在<form>元素内添加<x-honey-recaptcha/>组件。我们将使用之前的示例

<form action="{{ route('some.route') }}" method="POST">
    @csrf
    <input type="email" placeholder="Your email" required />
    <x-honey/>
    <x-honey-recaptcha/> 
    <button type="submit">Subscribe!</button>
</form>

作为备注，您可以使用<x-honey-recaptcha/>与<x-honey/>一起使用，或者单独使用。您随意。然而，如果您同时使用这两个组件，可以简化为以下内容

<x-honey recaptcha/>

为了使您能够在Google控制台中跟踪不同的操作类型，您可以将操作属性传递给recaptcha blade组件。

<x-honey-recaptcha action="signup"/>

// Or...
<x-honey recaptcha="signup"/>

现在您有两个选项。您可以让Honey为您处理Recaptcha请求，并在检测到机器人时自动失败，或者您可以手动处理（尽管这基本上是魔法，所以不用担心）。

通过中间件

要使用Honey的内置中间件，将honey-recaptcha添加到路由的中间件堆栈中

// routes/web.php

Route::post('/test', fn() => event(new RegisterInterest))
    ->middleware(['honey', 'honey-recaptcha'])
    ->name('some.route');

同样，如果您只对Recaptcha感兴趣，您可以使用此功能独立于honey中间件。默认情况下，如果情况可疑，中间件将中止请求。

手动

Honey通过Honey Facade为您提供您可能需要的所有功能。要手动检查令牌，您可以执行以下操作

$token = request()->honey_recaptcha_token;
$response = Honey::recaptcha()->check($token);

响应将返回一个包含Recaptcha文档中定义的属性RecaptchaResponse对象的响应： https://developers.google.com/recaptcha/docs/v3。此类实现了ArrayAccess，因此您可以像处理JSON响应一样使用数组语法。

$token = request()->honey_recaptcha_token;
$score = Honey::recaptcha()->check($token)['score'];

如果您想根据配置的最小分数快速确定请求是否为垃圾邮件，可以在调用check方法后使用isSpam方法。

$token = request()->honey_recaptcha_token;
$probablyABot = Honey::recaptcha()->check($token)->isSpam();

自定义失败时的行为

默认情况下，当Honey通过其中间件堆栈检测到垃圾邮件时，它将以422状态码终止。当然，你可能希望做些完全不同的事情。没问题！只需在服务提供者的启动方法中告诉Honey它应该做什么即可。

public function boot()
{
    Honey::failUsing(function() {
        abort(404, "Move along. Nothing to see here...");
    });
}

钩子

Honey允许你在它因垃圾邮件攻击而失败之前执行回调。你可以注册任意数量的回调。要注册回调，请调用beforeFailing方法。

Honey::beforeFailing(fn() => Log::alert("A bot is trying to access our site. Red alert!"));

Honey还允许你在服务器上检查reCaptcha令牌之后进行挂钩。这在Livewire特质中用于在下次渲染时强制请求新的令牌。

Honey::recaptcha()->afterRequesting(fn($response) => Log::info("This user got a reCaptcha score of {$response['score']}"));

手动运行Honey检查

你可以使用门面助手手动运行在honey.php配置文件中定义的checks数组中的任何检查。

$noSpam = Honey::check(request()->all());

请注意，这不会为你失败，而是返回一个布尔值。如果你希望强制失败，可以这样做。

Honey::fail();

与Livewire集成

Honey提供开箱即用的Livewire支持。要开始使用，请将WithHoney特质添加到你的Livewire组件中。你不需要更改你的表单，一切都将正常工作。请注意，honey输入是延迟的，因此它们只有在调用操作后才会同步回服务器。以下是一个示例表单。

<form wire:submit.prevent="signup">
    @csrf
    <input type="email" placeholder="Your email" required />
    <x-honey/>
    <button type="submit">Subscribe!</button>
</form>

当表单提交并调用signup操作时，Honey输入将同步回你的组件。在你的组件中，你可以通过调用$this->honeyPasses()来检查Honey是否通过。请注意，在Livewire组件中，你的标准失败方法将不会被调用，因为用例非常不同。

Honey还支持Livewire的reCaptcha。同样，你的表单只需要包含reCaptcha组件或在<x-honey/>组件上包含recaptcha属性。

<form wire:submit.prevent="signup">
    @csrf
    <input type="email" placeholder="Your email" required />
    <x-honey recaptcha/>
    <button type="submit">Subscribe!</button>
</form>

你还需要将WithRecaptcha特质添加到你的Livewire组件中（即使你也在使用Honey）。你可以通过调用$this->recaptchaPasses()来检查reCaptcha是否成功。如果你使用WithHoney，则$this->honeyPasses()方法也会为你检查reCaptcha，因此不需要调用两个方法。

WithRecaptcha特质足够智能，能够在例如令牌检查通过但验证失败的情况下从浏览器请求新的令牌。

配置Honey

Honey使用一组很好的默认值构建，但我们理解通常一个大小难以适应所有情况。这就是为什么我们为你提供了大量的配置选项。你可以从honey.php配置文件中访问它们。让我们看看你可以使用的不同选项。

功能

你可以通过向features数组中添加或删除它们来简单地启用或禁用Honey提供的全局功能。以下是提供的功能。

垃圾邮件IP跟踪

启用时，Honey将向你的数据库添加一个spammers迁移。每次有人未能通过垃圾邮件检查时，他们的IP地址就会被添加到spammers表中。如果你不希望Honey跟踪此信息，只需禁用该功能即可。

全局阻止垃圾邮件

如果垃圾邮件IP跟踪已启用，Honey可以更进一步。默认情况下，它将注册全局中间件，该中间件将阻止在配置文件中定义的maximum_attempts中已达到的最大尝试次数的任何IP地址在spammers表中的IP地址。如果你希望有更细粒度的控制或希望完全删除此功能，只需禁用该功能即可。

环境

你可能不想在每个环境中运行Honey。Honey将只在指定在此数组中的环境中运行。你还可以通过调用disable方法手动禁用Honey。

Honey::disable();

检查

每次运行 honey 中间件或调用 Honey::check() 时，Honey 会遍历一系列检查以确定请求是否为垃圾邮件。您可以通过在 checks 数组中添加或删除项目来自定义要运行的检查。

用户被阻止的垃圾邮件检查

此功能需要启用 spammerIpTracking 功能才能生效。如果某个 IP 地址被记录为在配置文件中定义的 maximum_attempts 垃圾邮件尝试次数，则它将失败。

存在但为空的检查

当您包含 <x-honey/> blade 指令时，Honey 会向您的表单添加一个隐藏的输入。如果机器人填写此输入或从请求中删除输入，则此检查将失败。

最小经过时间检查

当您包含 <x-honey/> blade 指令时，Honey 会向您的表单添加一个包含当前时间的加密值的隐藏输入。如果表单提交速度超过在 minimum_time_passed 配置条目中定义的速度，或删除输入，则此检查将失败。

JavaScript 输入填写检查

当您包含 <x-honey/> blade 指令时，Honey 会向您的表单添加一个隐藏输入。它最初为空，但在 minimum_time_passed 配置条目中指定的超时后，JavaScript 会用加密值填充输入。如果输入已用不同的值填充，或没有值，则检查将失败。

最小经过时间

如果您启用了最小经过时间检查或 JavaScript 输入填写检查，这两个检查都将使用此值来确定，以秒为单位，从页面加载到可以提交表单之前应该经过的最短时间。提交时间比这更快的表单将失败垃圾邮件检查。

垃圾邮件阻止

如果您启用了 spammerIpTracking 功能，您可以在此处配置其选项。table_name 条目允许您更改数据库表名，如果它与您的应用程序中的其他内容冲突。maximum_attempts 条目定义了一个 IP 地址在阻止之前可以记录为垃圾邮件的最大次数。我们建议设置一个大于 1 的值，以应对偶尔的错误。

输入名称选择器

默认情况下，Honey 使用 static 驱动程序来决定输入名称。如果您想更改每个输入的名称，您可以在此处进行更改。我们建议从默认值更改这些值，以防止跨站点的学习机器人行为。

Recaptcha

在此处定义您的密钥对，如果您不想在 env 文件中定义它。您还可以更改用户必须从 Recaptcha 获得的最低分数（介于 0 和 1 之间），以避免被视为垃圾邮件。

测试

Honey 拥有一个完整的测试套件。自己去运行吧！

composer test

认证

创建此包的主要动力是在观看 Jefferey Way 在 Laracasts 上关于垃圾邮件预防的精彩课程后产生的。如果您没有 Laracasts 订阅，您应该订阅一个。

lukeraymonddowning / honey

维护者

详细信息

README

目录

安装

升级

用法

Recaptcha

通过中间件

手动

自定义失败时的行为

钩子

手动运行Honey检查

与Livewire集成

配置Honey

功能

垃圾邮件IP跟踪

全局阻止垃圾邮件

环境

检查

用户被阻止的垃圾邮件检查

存在但为空的检查

最小经过时间检查

JavaScript 输入填写检查

最小经过时间

垃圾邮件阻止

输入名称选择器

Recaptcha

测试

认证