/ 
Mojolicious-Plugin-BlogSpam-0.08
River stage zero No dependents
/ Mojolicious::Plugin::BlogSpam

NAME

Mojolicious::Plugin::BlogSpam - Check your Comments using BlogSpam

SYNOPSIS

# In Mojolicious
$app->plugin('BlogSpam');

# In Mojolicious::Lite
plugin 'BlogSpam';

# In Controller
my $blogspam = $c->blogspam(
  comment => 'I just want to test the system!'
);

# Check for spam
if ($blogspam->test_comment) {
  print "Your comment is no spam!\n";
};

# Even non-blocking
$blogspam->test_comment(sub {
  print "Your comment is no spam!\n" if shift;
});

# Train the system
$blogspam->classify_comment('ok');

DESCRIPTION

Mojolicious::Plugin::BlogSpam is a plugin for Mojolicious to test comments or posts for spam against a BlogSpam instance (see Blog::Spam::API for the codebase). It supports blocking as well as non-blocking requests.

METHODS

Mojolicious::Plugin::BlogSpam inherits all methods from Mojolicious::Plugin and implements the following new ones.

register

# Mojolicious
$app->plugin(Blogspam => {
  url  => 'blogspam.sojolicio.us',
  port => '8888',
  site => 'http://grimms-abenteuer.de/',
  log  => '/spam.log',
  log_level => 'debug',
  exclude   => 'badip',
  mandatory => [qw/name subject/]
});

# Mojolicious::Lite
plugin 'BlogSpam' => {
  site => 'http://grimms-abenteuer.de/'
};

# Or in your config file
{
  BlogSpam => {
    url => 'blogspam.sojolicio.us',
    site => 'http://grimms-abenteuer.de/',
    port => '8888'
  }
}

Called when registering the plugin. Accepts the following optional parameters:

url

URL of your BlogSpam instance. Defaults to http://test.blogspam.net/.

port

Port of your BlogSpam instance. Defaults to 8888.

site

The name of your site to monitor.

log

A path to a log file.

log_level

The level of logging, based on Mojo::Log. Spam is logged as info, errors are logged as error.

In addition to these parameters, additional optional parameters are allowed as defined in the BlogSpam API. See "test_comment" method below.

HELPERS

blogspam

# In controller:
my $bs = $c->blogspam(
  comment => 'This is a comment to test the system',
  name => 'Akron'
);

Returns a new blogspam object, based on the given attributes.

OBJECT ATTRIBUTES

These attributes are primarily based on the BlogSpam API.

agent

$bs->agent('Mozilla/5.0 (X11; Linux x86_64; rv:12.0) ...');
my $agent = $bs->agent;

The user-agent sending the comment. Defaults to the user-agent of the request.

comment

$bs->comment('This is just a test comment');
my $comment_text = $bs->comment;

The comment text.

email

$bs->email('spammer@sojolicio.us');
my $email = $bs->email;

The email address of the commenter.

hash

my $hash = $bs->hash;

Returns a hash representation of the comment.

ip

$bs->ip('192.168.0.1');
my $ip = $bs->ip;

The ip address of the commenter. Defaults to the ip address of the request. Supports X-Forwarded-For proxy information.

$bs->link('http://grimms-abenteuer.de/');
my $link = $bs->link;

Homepage link given by the commenter.

name

$bs->name('Akron');
my $name = $bs->name;

Name given by the commenter.

subject

$bs->subject('Fun');
my $subject = $bs->subject;

Subject given by the commenter.

OBJECT METHODS

These methods are based on the BlogSpam API.

test_comment

# Blocking
if ($bs->test_comment(
       mandatory => 'name',
       blacklist => ['192.168.0.1']
    )) {
  print 'Probably ham!';
} else {
  print 'Spam!';
};

# Non-blocking
$bs->test_comment(
  mandatory => 'name',
  blacklist => ['192.168.0.1'],
  sub {
    my $result = shift;
    print ($result ? 'Probably ham!' : 'Spam!');
  }
);

Test the comment of the blogspam object for spam or ham. It's necessary to have a defined comment text and an IP address. The method returns nothing in case the comment is detected as spam, 1 if the comment is detected as ham and -1 if something went horribly, horribly wrong. Accepts additional option parameters as defined in the BlogSpam API.

blacklist

Blacklist an IP or an array reference of IPs. This can be either a literal IP address ("192.168.0.1") or a CIDR range ("192.168.0.1/8").

exclude

Exclude a plugin or an array reference of plugins from testing. See "get_plugins" for installed plugins of the BlogSpam instance.

fail

Boolean flag that will, if set, return every comment as spam.

mandatory

Define an attribute (or an array reference of attributes) of the blogspam object, that should be treated as mandatory (e.g. "name" or "subject").

The maximum number of links allowed in the comment. This defaults to 10.

max-size

The maximum size of the comment text allowed, given as a byte expression (e.g. "2k").

min-size

The minimum size of the comment text needed, given as a byte expression (e.g. "2k").

min-words

The minimum number of words of the comment text needed. Defaults to 4.

whitelist

Whitelist an IP or an array reference of IPs. This can be either a literal IP address ("192.168.0.1") or a CIDR range ("192.168.0.1/8").

For a non-blocking request, append a callback function. The parameters of the callback are identical to the method's return values in blocking requests.

classify_comment

$bs->classify_comment('ok');
$bs->classify_comment(ok => sub {
  print 'Done!';
});

Train the BlogSpam instance based on your comment definition as ok or spam. This may help to improve the spam detection. Expects a defined comment attribute and a single parameter, either ok or spam.

For a non-blocking request, append a callback function. The parameters of the callback are identical to the method's return values in blocking requests.

get_plugins

my @plugins = $bs->get_plugins;
$bs->get_plugins(sub {
  print join ', ', @_;
});

Requests a list of plugins installed at the BlogSpam instance.

For a non-blocking request, append a callback function. The parameters of the callback are identical to the method's return values in blocking requests.

get_stats

my $stats = $bs->get_stats;
my $stats = $bs->get_stats('http://sojolicio.us/');
$bs->get_stats(sub {
  my $stats = shift;
});

Requests a hash reference of statistics for your site regarding the number of comments detected as ok or spam. If no site attribute is given (whether as a parameter or when registering the plugin), this will return nothing.

For a non-blocking request, append a callback function. The parameters of the callback are identical to the method's return values in blocking requests.

DEPENDENCIES

Mojolicious.

SEE ALSO

Blog::Spam::API, http://blogspam.net/.

AVAILABILITY

https://github.com/Akron/Mojolicious-Plugin-BlogSpam

COPYRIGHT AND LICENSE

Copyright (C) 2012-2014, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

The API definition as well as the BlogSpam API code were written and defined by Steve Kemp.

Be aware that information of your users may be send to a third party. This should be noted in your privacy policy if you use a foreign BlogSpam instance.