First steps
First of all, the examples are not ready for use in real projects. They just indicate how to use the methods. I suggest you use a good IDE, so you get code-completion (For example: Zend Studio).
Second. I wrote this class in about 4hours, so if you find any bugs help me out and report them. Reporting can be done by sending an email to php-mollom-bugs[at]verkoyen[dot]eu. If you report a bug, make sure you give me enough information (include your code). If you have questions, try the Mollom-forum, don't send them by mail, I won't read them.
Third, Dries told me the output from Mollom isn't escaped. So think about it.
If you read the code in the file you will see I throw a lot of exceptions if something went wrong. So make sure you catch the exceptions. Catching exceptions can be done with a try-catch-structure. Below is some sample-code.
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set keys
Mollom::setPublicKey('<your-public-key>');
Mollom::setPrivateKey('<your-private-key>');
// populate serverlist (get them from your db, or file, or ...
Mollom::setServerList($servers);
// execute the method
try
{
if(Mollom::checkCaptcha($mollomSessionId, $answerFromVisitor)) echo 'the answer is correct, you may proceed!';
else echo 'incorrect!';
}
catch (Exception $e)
{
// your errorhandling goes here
}
?>
Available methods
- checkCaptcha
- checkContent
- getAudioCaptcha
- getImageCaptcha
- getServerList
- getStatistics
- sendFeedback
- setPrivateKey
- setPublicKey
- setServerList
- setUserAgent
- verifyKey
checkCaptcha
Validates the answer for a CAPTHCA
Parameters
- $sessionId
- A string that represents the Mollom-sessionid (returned by getImageCaptcha or getAudioCaptcha).
- $solution
- A string that represents the solution from the visitor.
Return
Returns a boolean. True if the given solution was correct, false if it wasn't.
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set keys
Mollom::setPublicKey('<your-public-key>');
Mollom::setPrivateKey('<your-private-key>');
// populate serverlist (get them from your db, or file, or ...
Mollom::setServerList($servers);
if(Mollom::checkCaptcha($mollomSessionId, $answerFromVisitor)) echo 'the answer is correct, you may proceed!';
else echo 'incorrect!';
?>
checkContent
Use this method to check if a post/comment/… is spam or not. The more data you provide the accurate the result will be. If the spam-status is unsure you can send the user an extra challenge, for example a CAPTCHA generated by getImageCaptcha.
Parameters
- $sessionId
- An optional string that represents the Mollom-sessionid (returned by getImageCaptcha or getAudioCaptcha).
- $postTitle
- An optional string that contains the title of the post/comment/….
- $postBody
- An optional string that contains the body of the post/comment/….
- $authorName
- An optional string that represents the authors name.
- $authorUrl
- An optional string that represents the authors url.
- $authorEmail
- An optional string that represents the authors email.
- $authorOpenId
- An optional string that represents the authors OpenID.
- $authorId
- An optional string that represents the id of the user on your website.
Return
Returns an array. In the array there will be 3 elements: spam (the spam-status, can be unknown, ham, spam or unsure), quality (an assessment of the content's quality, between 0 and 1) and session_id (mollom-sessionid).
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set keys
Mollom::setPublicKey('<your-public-key>');
Mollom::setPrivateKey('<your-private-key>');
// populate serverlist (get them from your db, or file, or ...
Mollom::setServerList($servers);
// get feedback
$feedback = Mollom::checkContent(null, null, '<a href="viagra.example.com">vi/-\gra</a>', '578dz');
// process feedback
if(in_array($feedback['spam'], array('unsure', 'unknow')))
{
// code for extra challenge
}
elseif ($feedback['spam'] == 'ham') echo 'your comment is OK. It will be stored.';
elseif ($feedback['spam'] == 'spam') echo 'your are spam! go away.';
?>
getAudioCaptcha
Get an audio-captcha.
Parameters
- $sessionId
- An optional string that represents the Mollom-sessionid (returned by a previous getImageCaptcha or getAudioCaptcha).
Return
Returns an array. In the array there will be 3 elements: session_id (Mollom-sessionid), url (url of the file) and html (html you can use on your website).
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set keys
Mollom::setPublicKey('<your-public-key>');
Mollom::setPrivateKey('<your-private-key>');
// populate serverlist (get them from your db, or file, or ...
Mollom::setServerList($servers);
// get captcha
$captcha = Mollom::getAudioCaptcha();
// output
echo $captcha['html'];
?>
getImageCaptcha
Get an image-captcha.
Parameters
- $sessionId
- An optional string that represents the Mollom-sessionid (returned by a previous getImageCaptcha or getAudioCaptcha).
Return
Returns an array. In the array there will be 3 elements: session_id (Mollom-sessionid), url (url of the file) and html (html you can use on your website).
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set keys
Mollom::setPublicKey('<your-public-key>');
Mollom::setPrivateKey('<your-private-key>');
// populate serverlist (get them from your db, or file, or ...
Mollom::setServerList($servers);
// get captcha
$captcha = Mollom::getImageCaptcha();
// output
echo $captcha['html'];
?>
getServerList
Get a list of servers. Store them in your DB or a file.
Return
Returns an array with servers.
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set keys
Mollom::setPublicKey('<your-public-key>');
Mollom::setPrivateKey('<your-private-key>');
// get the mollom servers
$servers = Mollom::getServerList();
?>
getStatistics
Get some stats. Usefull in backend or to show off on your blog.
Parameters
- $type
- A string that represents the type of statistics you want. Possible types are: total_days (Number of days Mollom has been used), total_accepted (Total of accepted posts), total_rejected (Total rejected spam), yesterday_accepted (Amount of posts accepted yesterday), yesterday_rejected (Number of posts rejected yesterday), today_accepted (Amount of posts accepted today), today_rejected (Number of posts rejected today).
Return
Returns a integer.
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set keys
Mollom::setPublicKey('<your-public-key>');
Mollom::setPrivateKey('<your-private-key>');
// populate serverlist (get them from your db, or file, or ...
Mollom::setServerList($servers);
// get statistics
$totalDaysMollomUsed = Mollom::getStatistics('total_days');
// output
echo $totalDaysMollomUsed;
?>
sendFeedback
Validates the answer for a CAPTHCA
Parameters
- $sessionId
- A string that represents the Mollom-sessionid (returned by checkContent).
- $feedback
- A string that contains the feedback, allowed feedback-strings are: spam (spam or unsolicited advertising), profanity (obscene, violent or profane content), low-quality (low quality content or writing), unwanted (unwanted, taunting or off-topic content).
Return
Returns a boolean.
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set keys
Mollom::setPublicKey('<your-public-key>');
Mollom::setPrivateKey('<your-private-key>');
// send feedback
Mollom::sendFeedback($mollomSessionId, 'spam');
?>
setPrivateKey
Set your private key. This function must be called.
Parameters
- $key
- A string that contains your private key.
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set key
Mollom::setPrivateKey('<your-private-key>');
?>
setPublicKey
Set your public key. This function must be called.
Parameters
- $key
- A string that contains your public key.
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set key
Mollom::setPublicKey('<your-public-key>');
?>
setServerList
Populate the serverlist. You should cache the server list. For example in a database or a file. The list will not change that much.
Parameters
- $servers
- A array that contains the servers.
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set keys
Mollom::setPublicKey('<your-public-key>');
Mollom::setPrivateKey('<your-private-key>');
// populate serverlist (get them from your db, or file, or ...
Mollom::setServerList($servers);
?>
setUserAgent
Change the user-agent. You don't have to do this, there is a default.
Parameters
- $newUserAgent
- A string that contains the new user-agent.
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set keys
Mollom::setPublicKey('<your-public-key>');
Mollom::setPrivateKey('<your-private-key>');
// populate serverlist (get them from your db, or file, or ...
Mollom::setServerList($servers);
// change user-agent
Mollom::setUserAgent('Application/Version Module/Version');
?>
verifyKey
Verifies your key.
Return
Returns a boolean. True if the given key is enabled and working, false if it is disabled or doesn't exists.
Example
<?php
// require Mollom-class
require_once 'path/to/mollom.php';
// set keys
Mollom::setPublicKey('<your-public-key>');
Mollom::setPrivateKey('<your-private-key>');
// populate serverlist (get them from your db, or file, or ...
Mollom::setServerList($servers);
if(Mollom::verifyKey()) echo 'correct key';
else echo 'incorrect key';
?>