drAkismetPlugin
===============

This plugin is a library on top of the _Akismet API_. It is a spam detection tool leveraged by a web service. Read their [online documentation](http://akismet.com/development/api/) for more information on the available calls.

Installation and configuration
------------------------------

1. Download the plugin and copy it to your project's plugins directory
2. Enable the plugin in your ``ProjectConfiguration`` class (``/config/ProjectConfiguration.class.php``)
3. Create a configuration file ``akismet.yml``
4. Enter your API key(s): [signup](https://akismet.com/signup/)

Usage
-----

### API calls

The 1.1 API supports four methods:

*   [verify-key](http://akismet.com/development/api/#verify-key): drAkismetVerifyKey
*   [comment-check](http://akismet.com/development/api/#comment-check): drAkismetCheckComment
*   [submit-spam](http://akismet.com/development/api/#submit-spam): drAkismetSubmitSpam
*   [submit-ham](http://akismet.com/development/api/#submit-ham): drAkismetSubmitHam  
      
Use a ``drAkismetApi`` instance to call theses methods:

    [php]
    $api = new drAkismetApi();
    $verifyKey = $api->verifyKey() // or: new drAkismetApiVerifyKey();
                     ->setBlogUri('http://www.symfony-project.org/blog/');
    $api->call($verifyKey); // returns a drAkismetApiReponse
    
    // or alternatively you can directly do:
    $api->verifyKey()->setBlogUri('http://www.symfony-project.org/blog/')
                     ->isValid($api); // returns TRUE / FALSE

Or use the ``drAkismetApiComment`` helper class - which can be extended by your own comment class:

    [php]
    $api = new drAkismetApi();
    $checkComment = new drAkismetCheckComment();
    $comment = new drAkismetApiComment();
    $comment->setAuthor('viagra-test-123')
            ->setAuthorEmail('foo@bar.net')
            ->setCommentContent('test');
    $checkComment->setBlogUri('http://www.symfony-project.org/blog/')
                 ->isSpam($api, $comment);
                 
### Response

Calls to an API method return an instance of ``drAkismetApiReponse``. The four provided methods return a subclass of said response class:

* ``verifyKeyResponse`` has a method ``isValid`` (returned by _verify-key_)
* ``checkCommentResponse`` has a method ``isSpam`` (returned by _comment-check_)
    
### Validator

Use ``drAkismetValidatorSpam`` to validate comments directly from your forms. Of course, like any ``sfValidator``, you can also use it outside your forms:

    [php]
    new drAkismetValidatorSpam(array(
            'blog'                 => 'http://www.symfony-project.org/blog/',
            'user_ip'              => $_SERVER['REMOTE_ADDR'],
            'comment_author'       => 'viagra-test-123',
            'comment_author_email' => 'foo@bar.net',
            'comment_content'      => 'test'
    ));
    
### And more ...

It is possible to create your own connection class (socket connection by default) or to override the
request parameters (e.g. for testing purposes):

    [php]
    class myConnection implements drAkismetConnectionInterface
    {
      /* ... */
    }
    $api = new drAkismetApi();
    $api->setConnection(new myConnection());
    
    $api->setHost('akismet-test.yourhost.com');
    $api->setPort(8080);
    
The default connection class ``drAkismetApiSocketConnection`` sends two events that you can use to monitor server requests and responses:
    
    [php]
    $api = new drAkismetApi();
    // drAkismetApiSocketConnection::EVENT_PRE_REQUEST
    $api->getConnection()->getEventDispatcher()
                         ->connect('akismet.pre_request', array('listenToPreRequest'));
    // drAkismetApiSocketConnection::EVENT_RAW_RESPONSE
    $api->getConnection()->getEventDispatcher()
                         ->connect('akismet.raw_response', array('listenToRawResponse'));
    
Configuration
-------------

### User agent

The defaults in the config directory of this plugin should suffice, but your are free to alter them.

### API keys

For each host you can configure different API keys. You can also override the hostname that will be used when communicating with the Akismet service:

    akismet:
      api_keys:
         www.yourhost.com: 123abc456def # the API key for said host
         mydev.local:
           host: www.yourhost.com # the hostname to use (instead of mydev.local)
           key:  123abc456def

### Deny calls

You can limit the available API methods by using the ``allow_calls`` key:

    akismet:
      allow_calls: [check-comment] # one or more of: verify-key, check-comment, submit-spam, submit-ham