PEAR is archived and read-only

This mirror preserves historical PEAR package releases and metadata so existing references remain available.

Home » Web Services » Services_Akismet2 » Manual

PHP implementation of the Akismet REST API

Introduction

About the Akismet API and the Services_Akismet2 package.

The Akismet API

The Akismet API is a web-service API used to filter spam from user-submitted comments. The Akismet API allows for both detecting and marking spam comments. When used correctly, the Akismet API can tremendously reduce the amount of work required to maintain user-submitted comments on a website. Often, the use of the Akismet API can reduce or eliminate the need for other spam-filtering solutions.

Services_Akismet2

Services_Akismet2 is an object-oriented implementation of the Akismet API. Services_Akismet2 supports all features of the Akismet API and provides and easy-to-use PHP 5 interface.

Services_Akismet2 is derived from the miPHP Akismet class written by Bret Kuhns for use in PHP 4. Services_Akismet2 requires PHP 5.2.1 or greater.

Setup

Service Providers

Though originally created for use with the Akismet service, the Akismet API is also used by other spam-filtering services. Services_Akismet2 works with any service that uses the Akismet API. To use Services_Akismet2 with other spam-filtering service providers, specify the API server in either the constructor, or by using the setConfig() method.

For example:

<?php

require_once 'Services/Akismet2.php';

// set service provider in constructor
$akismet = new Services_Akismet2('http://example.com', 'AABBCCDDEEFF', array(
    'apiServer' => 'antispam.example.com'
));

// set service provider using setConfig() method
$akismet = new Services_Akismet2('http://example.com', 'AABBCCDDEEFF');
$akismet->setConfig('apiServer', 'antispam.example.com');

// for a service provider that uses a non-standard port (8080)
$akismet = new Services_Akismet2('http://example.com', 'AABBCCDDEEFF');
$akismet->setConfig('apiServer', 'antispam.example.com')
        ->setConfig('apiPort', 8080);

?>

Popular spam-filtering service providers using the Akismet API include:

API Keys

All requests using the Akismet API must be verified using an API key. The API key is usually tied to a particular website and ensures the user is allowed to use the service (which is not free to provide). Most service providers offer API keys free of charge for personal or low-volume use, and offer licensing for commercial or high-volume applications.

API keys are specific to a particular service provider. If you switch spam-filtering service providers, you will need to acquire an API key for the particular service.

The format of the API key may vary between service providers. The API key itself is specified in the constructor. A Services_Akismet2_InvalidApiKeyException will be thrown when a request is made using an invalid API key.

Testing Your API Key

After you have acquired an API key, you may want to test it. A comment with the author set to viagra-test-123 should always be detected as spam, so it is a good way to make sure things are working properly.

<?php

require_once 'Services/Akismet2.php';
require_once 'Services/Akismet2/Comment.php';

$comment = new Services_Akismet2_Comment(array(
    'comment_author' => 'viagra-test-123',
    'user_ip'        => '127.0.0.1',
    'user_agent'     => 'just testing',
    'referrer'       => 'http://example.com'
));

$akismet = new Services_Akismet2('http://myblog.example.com', 'AABBCCDDEEFF');
if ($akismet->isSpam($comment)) {
    echo 'Everything is working properly.';
} else {
    echo 'Something\'s not right!';
}

?>

The Comment Class

Overview

The class Services_Akismet2_Comment represents a comment on a website. All Akismet API methods take a comment as the first parameter. The comment class contains content-related information such as the comment text, author name, author email and Web link; as well as server-related information such as the HTTP referer, timestamp and IP address. The accuracy provided by the Akismet API increases as more fields are included in the comment.

Required Fields

There are two required fields:

The blog URL, as referenced in the Akismet API documentation, is specified in the Services_Akismet2 constructor and does not need to be specified in the comment object.

Auto-Setting Server Fields

When checking if a comment is spam, it is possible to set the required fields, and several other server-related fields automatically. To do so, use the second parameter of the Services_Akismet2::isSpam() method. When using this parameter, usually only the content-related fields need to be specified manually.

Only auto-set server-related fields on actual comments submitted in real-time. If you check comments using an external system, you run the risk of submitting your own server information as spam. Instead, save the server information in the database and set it manually using the Services_Akismet2::setField() method.

Examples

There are two ways to specify fields in the comment object: setter methods, and in the constructor. As a shortcut, Services_Akismet2 methods that require a comment also accept an array of fields. For example:

<?php

require_once 'Services/Akismet2/Comment.php';

// set in constructor
$comment = new Services_Akismet2_Comment(array(
    'comment_author'       => 'Test User',
    'comment_author_email' => 'test@example.com',
    'comment_author_url'   => 'http://myblog.example.com',
    'comment_content'      => 'Buy V1agra!'
));

// using setter methods
$comment = new Services_Akismet2_Comment();
$comment->setAuthor('Test User')
        ->setAuthorEmail('test@example.com')
        ->setAuthorUrl('http://myblog.example.com')
        ->setContent('Buy V1agra!');

// using an array as a shortcut
$akismet->isSpam(array(
    'comment_author'       => 'Test User',
    'comment_author_email' => 'test@example.com',
    'comment_author_url'   => 'http://myblog.example.com',
    'comment_content'      => 'Buy V1agra!'
));

?>

API Methods

TODO

isSpam()

– Checks whether or not a comment is spam.

TODO

submitSpam()

– Submits a comment as an undetected spam to the Akismet server.

TODO

submitFalsePositive()

– Submits a comment as incorrectly detected spam to the Akismet server.

TODO

Examples

If you are using the Akismet API, it is recommended you build a system to enter data back into the API either by submitting missed spam, or by submitting false positives. While not strictly required, passing data back using the API will allow the service to learn from its mistakes, and will ensure the service stays relevant for your needs.

Handling User-Submitted Comments

<?php

require_once 'Services/Akismet2.php';
require_once 'Services/Akismet2/Comment.php';

$comment = new Services_Akismet2_Comment(array(
    'comment_author'       => 'Test Author',
    'comment_author_email' => 'test@example.com',
    'comment_author_url'   => 'http://example.com/',
    'comment_content'      => 'Hello, World!'
));

try {
    $apiKey  = 'AABBCCDDEEFF';
    $akismet = new Services_Akismet2('http://blog.example.com/', $apiKey);
    if ($akismet->isSpam($comment)) {
        // rather than simply ignoring the spam comment, it is recommended
        // to save the comment and mark it as spam in case the comment is a
        // false positive.
    } else {
        // save comment as normal comment
    }
} catch (Services_Akismet2_InvalidApiKeyException $keyException) {
    echo 'Invalid API key!';
} catch (Services_Akismet2_HttpException $httpException) {
    echo 'Error communicating with Akismet API server: ' .
        $httpException->getMessage();
} catch (Services_Akismet2_InvalidCommentException $commentException) {
    echo 'Specified comment is missing one or more required fields.' .
        $commentException->getMessage();
}

?>

Marking a Missed Comment as Spam

<?php

require_once 'Services/Akismet2.php';
require_once 'Services/Akismet2/Comment.php';

$comment = new Services_Akismet2_Comment(array(
    'comment_author'       => 'Test Author',
    'comment_author_email' => 'test@example.com',
    'comment_author_url'   => 'http://example.com/',
    'comment_content'      => 'Hello, World!'
));

try {
    $apiKey  = 'AABBCCDDEEFF';
    $akismet = new Services_Akismet2('http://blog.example.com/', $apiKey);
    $akismet->submitSpam($comment);
} catch (Services_Akismet2_InvalidApiKeyException $keyException) {
    echo 'Invalid API key!';
} catch (Services_Akismet2_HttpException $httpException) {
    echo 'Error communicating with Akismet API server: ' .
        $httpException->getMessage();
} catch (Services_Akismet2_InvalidCommentException $commentException) {
    echo 'Specified comment is missing one or more required fields.' .
        $commentException->getMessage();
}

?>

Marking a Comment as a False Positive

<?php

require_once 'Services/Akismet2.php';
require_once 'Services/Akismet2/Comment.php';

$comment = new Services_Akismet2_Comment(array(
    'comment_author'       => 'Test Author',
    'comment_author_email' => 'test@example.com',
    'comment_author_url'   => 'http://example.com/',
    'comment_content'      => 'Hello, World!'
));

try {
    $apiKey  = 'AABBCCDDEEFF';
    $akismet = new Services_Akismet2('http://blog.example.com/', $apiKey);
    $akismet->submitFalsePositive($comment);
} catch (Services_Akismet2_InvalidApiKeyException $keyException) {
    echo 'Invalid API key!';
} catch (Services_Akismet2_HttpException $httpException) {
    echo 'Error communicating with Akismet API server: ' .
        $httpException->getMessage();
} catch (Services_Akismet2_InvalidCommentException $commentException) {
    echo 'Specified comment is missing one or more required fields.' .
        $commentException->getMessage();
}

?>