Zend Framework: Zend_Service_Akismet Component Proposal

Proposed Component Name	Zend_Service_Akismet
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Service_Akismet
Proposers	Matthew Weier O'Phinney
Revision	1.0 - 10 January 2007: First draft. (wiki revision: 8)

$akismet = new Zend_Service_Akismet('http://example.com/blog/', $apiKey);
$akismet->commentCheck(array(
    'user_ip'              => '111.222.222.222',
    'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1)',
    'referrer'             => 'http://www.example.com/blog/',
    'comment_type'         => 'comment',
    'comment_author'       => "viagra-test-123",
    'comment_author_email' => 'spammer@nooneknows.com',
    'comment_content'      => 'a little v i a g r a goes a l o n g way'
`
));

UC-03

$akismet = new Zend_Service_Akismet('http://example.com/blog/', $apiKey);
$akismet->submitSpam(array(
    'user_ip'              => '111.222.222.222',
    'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1)',
    'referrer'             => 'http://www.example.com/blog/',
    'comment_type'         => 'comment',
    'comment_author'       => "viagra-test-123",
    'comment_author_email' => 'spammer@nooneknows.com',
    'comment_content'      => 'a little v i a g r a goes a l o n g way'
`
));

UC-04

$akismet = new Zend_Service_Akismet('http://example.com/blog/', $apiKey);
$akismet->submitHam(array(
    'user_ip'              => '111.222.222.222',
    'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1)',
    'referrer'             => 'http://www.example.com/blog/',
    'comment_type'         => 'comment',
    'comment_author'       => "Mr. Goodbar",
    'comment_author_email' => 'goodbar@example.com',
    'comment_content'      => 'Why are my comments always trapped as spam?'
`
));

UC-05

// Use behind a proxy
// Setup an HTTP client with a proxy adapter, with the necessary proxy options
$httpClient = new Zend_Http_Client(null, array(
    'adapter'    => 'Zend_Http_Client_Adapter_Proxy',
    'proxy_host' => 'proxy.example.com',
    'proxy_port' => 8080,
    'proxy_user' => 'me',
    'proxy_pass' => 'bananarama'
));

// Pass it into the akismet client
Zend_Service_Akismet::setHttpClient($httpClient);

// Everything else is as normal
$akismet = new Zend_Service_Akismet('http://example.com/blog/', $apiKey);
$akismet->submitHam(array(
    'user_ip'              => '111.222.222.222',
    'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1)',
    'referrer'             => 'http://www.example.com/blog/',
    'comment_type'         => 'comment',
    'comment_author'       => "Mr. Goodbar",
    'comment_author_email' => 'goodbar@example.com',
    'comment_content'      => 'Why are my comments always trapped as spam?'
`
));

9. Class Skeletons

<?php
/** Zend_Service_Abstract */
require_once 'Zend/Service/Abstract.php';

/** Zend_Service_Exception */
require_once 'Zend/Service/Exception.php';

/**
 * Akismet REST service implementation
 * 
 * @uses Zend_Service_Abstract
 * @package Zend_Service
 * @version $Id: Akismet.php 4015 2007-01-09 15:56:30Z matthew $
 * @license New BSD {@link http://framework.zend.com/license/new-bsd}
 */
class Zend_Service_Akismet extends Zend_Service_Abstract
{
    /**
     * Akismet API key
     * @var string
     */
    protected $_apiKey;

    /**
     * Blog URL
     * @var string
     */
    protected $_blogUrl;

    /**
     * Charset used for encoding
     * @var string
     */
    protected $_charset = 'UTF-8';

    /**
     * Zend_Http_Client_Adapter class to use
     * @var string
     */
    protected $_httpClientAdapterClass = 'Zend_Http_Client_Adapter_Socket';

    /**
     * TCP/IP port to use in requests
     * @var int
     */
    protected $_port = 80;

    /**
     * User Agent string to send in requests
     * @var string
     */
    protected $_userAgent = 'Zend Framework/0.7.0 | Akismet/1.11';

    /**
     * Constructor
     * 
     * @param string $apiKey 
     * @return void
     */
    public function __construct($blog, $apiKey)
    {
        $this->setBlogUrl($blog)
            ->setApiKey($apiKey);
    }

    /**
     * Retrieve blog URL
     * 
     * @return string
     */
    public function getBlogUrl()
    {
        return $this->_blogUrl;
    }

    /**
     * Set blog URL
     * 
     * @param string $blogUrl
     * @return Zend_Service_Akismet
     */
    public function setBlogUrl($blogUrl)
    {
        require_once 'Zend/Uri.php';
        if (!Zend_Uri::check($blogUrl)) {
            throw new Zend_Service_Exception('Invalid url provided for blog');
        }

        $this->_blogUrl = $blogUrl;
        return $this;
    }

    /**
     * Retrieve API key
     * 
     * @return string
     */
    public function getApiKey()
    {
        return $this->_apiKey;
    }

    /**
     * Set API key
     * 
     * @param string $apiKey 
     * @return Zend_Service_Akismet
     */
    public function setApiKey($apiKey)
    {
        $this->_apiKey = $apiKey;
        return $this;
    }

    /**
     * Retrieve charset
     * 
     * @return string
     */
    public function getCharset()
    {
        return $this->_charset;
    }

    /**
     * Set charset
     * 
     * @param string $charset
     * @return Zend_Service_Akismet
     */
    public function setCharset($charset)
    {
        $this->_charset = $charset;
        return $this;
    }

    /**
     * Retrieve TCP/IP port
     * 
     * @return int
     */
    public function getPort()
    {
        return $this->_port;
    }

    /**
     * Set TCP/IP port
     * 
     * @param int $port 
     * @return Zend_Service_Akismet
     * @throws Zend_Service_Exception
     */
    public function setPort($port)
    {
        if (!is_int($port)) {
            throw new Zend_Service_Exception('Invalid port');
        }

        $this->_port = $port;
        return $this;
    }

    /**
     * Retrieve User Agent string
     * 
     * @return string
     */
    public function getUserAgent()
    {
        return $this->_userAgent;
    }

    /**
     * Set User Agent 
     * 
     * @param string $userAgent 
     * @return Zend_Service_Akismet
     * @throws Zend_Service_Exception
     */
    public function setUserAgent($userAgent)
    {
        if (!is_string($userAgent)
            || !preg_match(":^[Zend_Font - Karol Babioch^\n/]*/[Zend_Font - Karol Babioch^ ]* \| Akismet/[0-9\.]*$:i", $userAgent))
        {
            throw new Zend_Service_Exception('Invalid User Agent string; must be of format "Application name/version | Akismet/version"');
        }

        $this->_userAgent = $userAgent;
        return $this;
    }

    /**
     * Retrieve HTTP client adapter class
     * 
     * @return string
     */
    public function getHttpClientAdapterClass()
    {
        return $this->_httpClientAdapterClass;
    }

    /**
     * Set HTTP client adapter class
     * 
     * @return Zend_Service_Aksimet
     */
    public function setHttpClientAdapterClass($class)
    {
        $this->_httpClientAdapterClass = $class;

        return $this;
    }

    /**
     * Post a request
     * 
     * @param string $host 
     * @param string $path 
     * @param array  $params 
     * @return mixed
     */
    protected function _post($host, $path, array $params)
    {
        $client = self::getHttpClient();
        $client->setUri('http://' . $host . $path);
        $client->setConfig(array(
            'maxredirects' => 0,
            'timeout'      => 3,
            'useragent'    => $this->getUserAgent(),
            'adapter'      => $this->getHttpClientAdapterClass(),
            'httpversion'  => '1.0'
        ));

        $client->setHeaders(array(
            'Host'         => $host,
            'Content-Type' => 'application/x-www-form-urlencoded; charset=' . $this->getCharset()
        ));
        $client->setParameterPost($params);

        $client->setMethod(Zend_Http_Client::POST);
        return $client->request();
    }

    /**
     * Verify an API key
     * 
     * @param string $key Optional; API key to verify
     * @param string $blog Optional; blog URL against which to verify key
     * @return boolean
     */
    public function verifyKey($key = null, $blog = null)
    {
        if (null === $key) {
            $key = $this->getApiKey();
        }

        if (null === $blog) {
            $blog = $this->getBlogUrl();
        }

        $response = $this->_post('rest.akismet.com', '/1.1/verify-key', array(
            'key'  => $key,
            'blog' => $blog
        ));

        if ('valid' == $response->getBody()) {
            return true;
        }

        return false;
    }

    /**
     * Perform an API call
     * 
     * @param string $path
     * @param array $params 
     * @return Zend_Http_Response
     */
    protected function _makeApiCall($path, $params)
    {
        if (empty($params['user_ip']) || empty($params['user_agent'])) {
            throw new Zend_Service_Exception('Missing required Akismet fields');
        }

        if (!isset($params['blog'])) {
            $params['blog'] = $this->getBlogUrl();
        }

        return $this->_post($this->getApiKey() . '.rest.akismet.com', '/1.1/comment-check', $params);
    }

    /**
     * Check a comment for spam
     *
     * Checks a comment to see if it is spam. $params should be an associative 
     * array with one or more of the following keys (unless noted, all keys are 
     * optional):
     * - blog: URL of the blog. If not provided, uses value returned by {@link getBlogUrl()}
     * - user_ip (required): IP address of comment submitter
     * - user_agent (required): User Agent used by comment submitter
     * - referrer: contents of HTTP_REFERER header
     * - permalink: location of the entry to which the comment was submitted
     * - comment_type: typically, one of 'blank', 'comment', 'trackback', or 'pingback', but may be any value
     * - comment_author: name submitted with the content
     * - comment_author_email: email submitted with the content
     * - comment_author_url: URL submitted with the content
     * - comment_content: actual content
     *
     * Additionally, Akismet suggests returning the key/value pairs in the 
     * $_SERVER array, and these may be included in the $params.
     * 
     * @param array $params 
     * @return boolean
     */
    public function commentCheck($params)
    {
        $response = $this->_makeApiCall('/1.1/comment-check', $params);

        if ('true' == $response->getBody()) {
            return true;
        }

        return false;
    }

    /**
     * Submit spam
     *
     * Takes the same arguments as { @link commentCheck()}.
     * 
     * @param array $params 
     * @return void
     */
    public function submitSpam($params)
    {
        $this->_makeApiCall('/1.1/submit-spam', $params);
    }

    /**
     * Submit ham
     *
     * Takes the same arguments as { @link commentCheck()}.
     * 
     * @param array $params 
     * @return void
     */
    public function submitHam($params)
    {
        $this->_makeApiCall('/1.1/submit-ham', $params);
    }
}

Page Operations

Browse Space

Zend_Service_Akismet Proposal - Matthew Weier O'Phinney

Labels

Zend Framework: Zend_Service_Akismet Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

4. Dependencies on Other Framework Components

5. Theory of Operation

6. Milestones / Tasks

7. Class Index

8. Use Cases

9. Class Skeletons