README

Official PHP SDK for the Akismet spam protection service by Automattic.

Note: This SDK is for non-WordPress PHP applications. WordPress sites should use the official Akismet plugin.

Requirements

• PHP 8.1 or higher
• A PSR-18 HTTP client (e.g., Guzzle, Symfony HttpClient)

Installation

composer require automattic/akismet-sdk

If you don't have a PSR-18 HTTP client installed, add one:

composer require guzzlehttp/guzzle

Quick Start

<?php

use Automattic\Akismet\Akismet;
use Automattic\Akismet\DTO\Content;
use Automattic\Akismet\Enum\ContentType;

// Initialize the client
$akismet = Akismet::create(
    apiKey: 'your-api-key',
    site: 'https://your-site.com'
);

// Check if content is spam
$content = new Content(
    userIp: $_SERVER['REMOTE_ADDR'],
    userAgent: $_SERVER['HTTP_USER_AGENT'],
    body: $formData['message'],
    authorName: $formData['name'],
    authorEmail: $formData['email'],
    type: ContentType::ContactForm
);

$result = $akismet->check($content);

if ($result->isSpam()) {
    // Handle spam
    if ($result->shouldDiscard()) {
        // Blatant spam - safe to discard silently
    }
} else {
    // Process legitimate submission
}

How It Works

flowchart LR
    A[Your App] --> B["Akismet::check()"]
    B --> C{verdict}
    C -->|ham| D[Publish Content]
    C -->|discard| E[Drop Silently]
    C -->|spam| F[Queue for Review]

Features

• Full support for Akismet API 1.1 and 1.2 endpoints
• PSR-18 HTTP client compatibility (works with Guzzle, Symfony, etc.)
• Immutable, type-safe DTOs
• Native PHP 8.1 enums for content types and verdicts
• Built-in test mode for development

API Methods

Integration Identification

If you're building a framework integration (Drupal, Laravel, Symfony, etc.), identify your integration via applicationUserAgent. This is prepended to the SDK's User-Agent header so Akismet can track compatibility and usage:

$akismet = Akismet::create(
    apiKey: 'your-api-key',
    site: 'https://your-site.com',
    applicationUserAgent: 'MyDrupalModule/1.0.0'
);

Framework Integration

Use ContentFactory to create Content objects from PSR-7 requests with automatic IP and user agent extraction:

use Automattic\Akismet\Factory\ContentFactory;
use Automattic\Akismet\Enum\ContentType;

$content = ContentFactory::fromRequest(
    request: $psr7Request,
    body: $formData['message'],
    authorName: $formData['name'],
    authorEmail: $formData['email'],
    type: ContentType::ContactForm,
);

Trusted Proxies

By default, ContentFactory::fromRequest() uses REMOTE_ADDR as the client IP. If your application runs behind a reverse proxy or load balancer, pass the proxy IPs to trust forwarded headers (X-Forwarded-For, X-Real-IP, CF-Connecting-IP, True-Client-IP):

// Trust specific proxy IPs
$content = ContentFactory::fromRequest(
    request: $psr7Request,
    body: $formData['message'],
    trustedProxies: ['10.0.0.1', '10.0.0.2'],
);

// Trust all proxies (use only in controlled environments)
$content = ContentFactory::fromRequest(
    request: $psr7Request,
    body: $formData['message'],
    trustedProxies: ['*'],
);

Submitting Feedback

Help improve Akismet's accuracy by reporting mistakes:

// Report a missed spam (was marked as ham but is actually spam)
$akismet->submitSpam($content);

// Report a false positive (was marked as spam but is actually ham)
$akismet->submitHam($content);

Error Handling

All SDK exceptions implement AkismetException, so you can catch everything with a single type:

use Automattic\Akismet\Exception\AkismetException;
use Automattic\Akismet\Exception\InvalidApiKeyException;
use Automattic\Akismet\Exception\RateLimitException;

try {
    $result = $akismet->check($content);
} catch (InvalidApiKeyException $e) {
    // API key is invalid or revoked
} catch (RateLimitException $e) {
    // Too many requests — retry after $e->getRetryAfter() seconds
} catch (AkismetException $e) {
    // Catch-all for network errors, server errors, validation errors, etc.
}

classDiagram
    class AkismetException {
        <<interface>>
    }
    InvalidApiKeyException ..|> AkismetException
    ValidationException ..|> AkismetException
    ClientErrorException ..|> AkismetException
    RateLimitException ..|> AkismetException
    NetworkException ..|> AkismetException
    ServerException ..|> AkismetException

API keys are automatically redacted from exception messages to prevent credential leakage in logs.

Testing

Use test mode during development to avoid affecting your accuracy metrics:

$akismet = Akismet::create(
    apiKey: 'your-api-key',
    site: 'https://your-site.com',
    isTest: true
);

In test mode:

• akismet-guaranteed-spam@example.com as author email returns spam
• akismet-guaranteed-spam as author name returns spam
• Normal content returns ham

Documentation

• Akismet Developer Documentation
• API Reference

License

GPL-2.0-or-later