README

介绍

为任何PHP应用程序提供了一种简单直观的方式来使用Akismet反垃圾邮件服务。

安装与需求

需要PHP ~8.0 || ~8.1 || ~8.2

该库不包含HTTP客户端，因此如果您项目中尚未安装PSR-18 HTTP客户端，则需要安装一个以使用它。有很多HTTP客户端可供选择，例如流行的库Guzzle或HttpPlug。

该库还要求您安装一个PSR-17 (HTTP Factories)库，您可以在Packagist上找到其实现，我个人更喜欢laminas/laminas-diactoros。

composer require laminas/laminas-diactoros
composer require php-http/curl-client
composer require gsteel/akismet

基本用法

构建客户端

一旦安装了必要的HTTP相关库，它们应该可以通过提供的发现库被发现。向构造函数提供一个API密钥和您将操作的基本网站地址，您将获得一个现成的客户端。

<?php

use GSteel\Akismet\Client;
use Http\Discovery\Psr17FactoryDiscovery;
use Http\Discovery\Psr18ClientDiscovery;

$client = new Client(
    'myApiKey',
    'https://my-website.example.com',
    Psr18ClientDiscovery::find(),
    Psr17FactoryDiscovery::findRequestFactory(),
    Psr17FactoryDiscovery::findStreamFactory()
);

// Check the validity of your API key

$result = $client->verifyKey();
assert($result === true);

评论参数和检查内容

该库的主要关注点是检查评论和表单提交等请求，以确定内容是“垃圾邮件”还是“非垃圾邮件”。

Akismet API提供了一些参数以提高检查的准确性，这些参数已封装到不可变值对象\Gsteel\Akismet\CommentParameters中。

如果您熟悉参数名称，可以向此对象的构造函数传递一个数组，否则您可以通过调用各种方法来构建一个包含您希望提供所有信息的对象。

<?php

use GSteel\Akismet\AkismetClient;
use GSteel\Akismet\CommentParameters;
use GSteel\Akismet\CommentType;

assert($client instanceof AkismetClient);

$parameters = (new CommentParameters())
    ->withComment('Some comment Content', CommentType::contactForm())
    ->withRequestParams($_SERVER['REMOTE_ADDR']);
    
$result = $client->check($parameters);

assert($result->isSpam());

有大量的其他参数和方法可用于向API提供尽可能多的上下文，还有一个名为构造函数的有用构造函数，适用于使用PSR-7消息的环境。

<?php

use GSteel\Akismet\CommentParameters;
use Psr\Http\Message\ServerRequestInterface;

assert($request instanceof ServerRequestInterface);

$parameters = CommentParameters::fromRequest($request);

提交误判或误分类

可以通过向submitHam()方法发送与check()中使用的相同有效载荷来提交被错误分类为垃圾邮件的内容。相反，您可以使用submitSpam()提交被错误分类为非垃圾邮件的实际垃圾邮件。

<?php

use GSteel\Akismet\AkismetClient;
use GSteel\Akismet\Result;

assert($client instanceof AkismetClient);

$parameters = CommentParameters::fromRequest($request);
$result = $client->check($parameters);

// Result is incorrectly classified as spam:
$client->submitHam($result->parameters());

// Result is incorrectly classified as ham:
$client->submitSpam($result->parameters());

您可以将客户端check()方法的Result序列化和反序列化为JSON字符串。

<?php

use GSteel\Akismet\Result;

assert($result instanceof Result);

$jsonString = json_encode($result);

$hydratedResult = Result::fromJsonString($jsonString);

结合您自己的特定请求识别方法，您可以创建一个机制来存储结果，并根据用户反馈将其提交为垃圾邮件或非垃圾邮件。

错误处理

所有错误都实现了 \GSteel\Akismet\GenericException 接口，因此可以使用单个类型捕获库抛出的任何错误。具体的异常包括：

• ApiError - 表示由于无效密钥等原因，API请求失败
• HttpError - 表示无法通过HTTP与Akismet进行通信
• InvalidRequestParameters - 必要的值缺失或向CommentParameters提供了无效的值

PSR-11 容器

\GSteel\Akismet\Container\ClientDiscoveryFactory 包含了一个工厂，该工厂可以被集成到您选择的依赖注入（DI）容器中，利用HTTP发现来注入HTTP客户端和工厂等。

它假设容器会通过请求config来返回一个数组或实现ArrayAccess的对象。它进一步假设这个配置结构包含以下信息：

<?php
$config = [
    'akismet' => [
        'key' => 'Your API Key',
        'website' => 'https://you.example.com',
    ],
];

许可证

本软件发布于MIT许可证之下 - 有关详细信息，请参阅LICENSE文件。