README

cakephp-stop-spam 是一个 CakePHP 插件，允许您使用由 stopforumspam.org 提供的服务和 API 检查用户名、电子邮件地址或 IP 地址是否被报告为垃圾邮件发送者。

你喜欢这个插件吗？它的开发花费了我很多时间。请考虑进行捐赠：哪怕只是一杯咖啡也足够了！谢谢。

• 安装
  • 旧版 CakePHP 和 PHP 版本的安装
    • 对于 PHP 7.2 和 CakePHP 4 或更高版本
    • 对于 PHP 5.6 和 CakePHP 3 或更高版本
• 如何使用
  • 请求检测器
  • 如何创建验证规则
  • 如何配置缓存
• 版本控制

安装

您可以通过 composer 安装插件

$ composer require --prefer-dist mirko-pagliai/cakephp-stop-spam

然后您需要加载插件。有关如何加载插件的更多信息，请参阅食谱。

简单来说，您可以执行 shell 命令来启用插件

bin/cake plugin load StopSpam

这将更新您的应用程序的引导方法。

旧版 CakePHP 和 PHP 版本的安装

最近的包和主分支需要至少 CakePHP 5.0 和 PHP 8.1，且当前代码的开发基于这些以及后续版本的 CakePHP 和 PHP。然而，仍然有一些分支与先前版本的 CakePHP 和 PHP 兼容。

对于 PHP 7.2 和 CakePHP 4 或更高版本

需要至少 PHP >=7.2 和 CakePHP ^4.0 的 php7.2 分支。

在这种情况下，您也可以安装这个包

$ composer require --prefer-dist mirko-pagliai/cakephp-stop-spam:dev-php7.2

请注意，从 2024 年 1 月 7 日起，php7.2 分支将不再更新（除了安全补丁），并且它与 1.1.8 版本匹配。

对于 PHP 5.6 和 CakePHP 3 或更高版本

需要至少 PHP 5.6 和 CakePHP 3 的 cakephp3 分支。

在这种情况下，您也可以安装这个包

$ composer require --prefer-dist mirko-pagliai/cakephp-stop-spam:dev-cakephp3

请注意，从 2021 年 5 月 7 日起，cakephp3 分支将不再更新（除了安全补丁），并且它与 1.1.3 版本匹配。

如何使用

在实例化类之后，您可以使用 email()、ip() 和 username() 方法指定要验证的值，最后使用 verify() 方法获取结果。示例

$SpamDetector = new SpamDetector();
$SpamDetector->email('test@example.com')
    ->ip('8.8.8.8')
    ->username('mirko');
$result = $SpamDetector->verify();

verify() 方法如果 至少有一个参数 被报告为垃圾邮件发送者，则返回 false，否则返回 true。换句话说，verify() 方法验证它不是垃圾邮件发送者。

如果 API 返回错误（例如，如果您指定了一个无效的 IP 地址，或在任何情况下生成了一个无法解释的请求），则将抛出异常。

email()、ip() 和 username() 方法是可链式的，可以多次调用，或者您也可以传递多个参数。示例（email() 方法被多次调用，而 ip() 方法使用多个参数）

$SpamDetector = new SpamDetector();
$SpamDetector->email('test@example.com');
$SpamDetector->email('anothermail@example.com');
$SpamDetector->ip('8.8.8.8', '8.8.4.4');
$result = $SpamDetector->verify();

请求检测器

该插件还增加了is('spammer')请求检测器。此检测器检查用户的IP地址是否被报告为垃圾邮件发送者。无论服务器请求在何处可访问，都可以使用检测器。例如：

class PagesController extends AppController
{
    /**
     * A "view" action for PagesController
     */
    public function view()
    {
		$isSpammer = $this->getRequest()->is('spammer');

		if ($isSpammer) {
			throw new InternalErrorException('Ehi, you are a spammer! Get out of my site!');
		}

		// ...
	}
}

检测器检查用户客户端的IP地址是否被报告为垃圾邮件发送者。这正如上述所描述的。如果IP地址未被报告，检测器将使用会话来存储控制结果。

这非常方便且快速。它避免了代码的重复，并且通过使用会话来记住结果，甚至不需要使用缓存。

如何创建验证规则

该插件还可以用作验证规则。以下是一个例子：

class ContactUsForm extends Form
{
    protected function _buildValidator(Validator $validator)
    {
	    //some rules for my form...

        $validator->add('email', [
            'notSpammer' => [
                'message' => 'Sorry, this email address has been reported as a spammer!',
                'rule' => function ($value, $context) {
                    return (new SpamDetector())->email($value)->verify();
                },
            ],
        ]);

        return $validator;
    }
}

在这种情况下，验证器将验证电子邮件地址未被报告为垃圾邮件发送者。

有关如何创建和使用验证规则的信息，请参阅食谱。

如何配置缓存

此插件使用HTTP客户端发送请求并获取响应，然后逐个检查和处理。这可能会消耗大量资源并生成大量网络流量。因此，该插件使用缓存（错误响应除外）。

默认情况下，缓存处于活动状态。您可以使用cache选项启用或禁用它。示例：

$SpamDetector = new SpamDetector();
//Disables the cache
$SpamDetector->setConfig('cache', false);
//Re-enables the cache
$SpamDetector->setConfig('cache', true);

StopSpam将使用在其引导文件中定义的同名缓存引擎。

如果您想使用自己的缓存引擎或想使用不同于默认配置的配置，那么在加载插件之前必须配置StopSpam缓存引擎。示例：

Cache::setConfig('StopSpam, [
    'className' => 'File',
    'duration' => '+1 month',
    'path' => CACHE,
    'prefix' => 'stop_spam_',
]);

有关如何配置缓存引擎的信息，请参阅食谱。

请特别关注stopforumspam.org报告的内容。

此API不得用作通用软件防火墙。将每个传入连接与API进行比对将被视为对我们进行的拒绝服务攻击，并将导致任何违规IP地址立即被阻止。

因此，建议使用缓存，限制请求并使用会话来标记用户已验证。

版本控制

为了透明度和对发布周期的洞察，以及保持向后兼容性，cakephp-stop-spam将根据语义化版本控制指南进行维护。