Important: domain name change. We are moving from web-utils.eu to securecaptcha.net. If you use our service, change host name in your code.

Secure CAPTCHA - installation in PHP environment

This page contains information about integrating the Secure CAPTCHA service in the PHP environment.

Overview

We assume, that you have already obtained your siteID and privateKey. If not, check instructions at the installation page.

To integrate Secure CAPTCHA with your site, you will have to complete following steps:
1. Download a script
2. Integrate it with your form

1. Download a script

You need a handwrittenCaptcha.php script. Download it, save it and copy to your PHP project location, so that it can be found with the require statement. To test if it is installed properly run this code in your web environment.

    require 'handwrittenCaptcha.php';

If you can run this code and there are no errors, it means, that script has been installed successfully.

2. Integrate with your form

Script handwrittenCaptcha provides CaptchaService class with constructor: CaptchaService($siteID, $privateKey, $proxyServer=null, $proxyPort=null). You can obtain siteID and privateKey after creating the site definition at our admin panel. If your server is behind the proxy, you may need to use proxyHost and proxyPort parameters.

CaptchaService class provides following methods.

getCaptcha(&$ret) - requests for a new CAPTCHA and returns True on success and False on error. Return parameter $ret is set to array with hash, mac, timestamp and fragment values on success or to error code on failure. HtmlFragment is a HTML/XHTML fragment you should print directly into your page. Hash, mac and timestamp are used to validate the answer and you should keep them somewhere (ie. in user's session object) and restore them when user submits the form. You should not reveal them to the user.
validateOffline($hash, $mac, $timestamp, $answer) validates user's answer using offline algorithm (hmac). It returns True if answer is valid or False otherwise. $hsh, $mac and $timestamp parameters are values returned by getCaptcha method; $answer is an answer provided by the user. If you are not sure, that you use the same values that has been generated in getCaptcha method, use online validation.
validateOnline($hash, $timestamp, $answer, &$error) validates user's answer using online algorithm (http request). It returns True if answer is valid and no errors occurred or False otherwise. Return parameter$error is set to error code on validation error or to null otherwise. $hsh and $timestamp are values returned by getCaptcha method; $answer is an answer provided by the user.

You can see an example below.

#!/usr/local/bin/php
<?PHP
    session_start();
?>
<html><body>
<?PHP
    // we import the script
    require 'handwrittenCaptcha.php';
    // replace it with your siteID
    $siteID = 'put your siteID here!';
    // replace it with your privateKey 
    $privateKey = 'put your privateKey here!';

    // initialization
    $captchaService = new CaptchaService($siteID, $privateKey);

    // if the answer was submitted
    if (isset($_REQUEST['formSubmitted'])) {
	$answer = $_REQUEST['answer'];
        // restore data
        $value = $_SESSION['captchaData'];
        $hash = $value['hash'];
        $mac = $value['mac'];
        $timestamp = $value['timestamp'];

        unset($_SESSION['captchaData']);

        // validate offline
        $okOffline = $captchaService->validateOffline($hash, $mac, $timestamp, $answer);
        if ($okOffline) print 'Offline validation: OK. ';

        // validate online
        $okOnline = $captchaService->validateOnline($hash, $timestamp, $answer, $error);
        if ($okOnline) print 'Online validation: OK. ';
        if ($error != null) print 'Online validation error: ' . error;
    }
?>
<form action="" method="post">
<?PHP
    // create new captcha
    if ($captchaService->getCaptcha($value)) {
        $hash = $value['hash'];
        $mac = $value['mac'];
        $timestamp = $value['timestamp'];
        $fragment = $value['fragment'];
        // store captcha values for later use	
        $_SESSION['captchaData'] = array('hash' => $hash, 'mac' => $mac, 'timestamp' => $timestamp);
        // print captcha html/xhtml fragment
        echo $fragment;
    } else {
        echo 'An error occurred: ' . $value;
    }
?>
  Rewrite text from the image above (only small Latin letters):
  <input type="text" name="answer" value="" />
  <input type="submit" name="formSubmitted" value="Submit" />
</form>
</body>
</html>

How this example works:

at line 15: CaptchaService is initialized,
at line 41: new CAPTCHA is created,
at line 47: CAPTCHA values are saved for later use,
at line 49: CAPTCHA fragment is printed,
at line 21: CAPTCHA values are restored,
at lines 29 and 33: CAPTCHA answer is validated.