Manual

Implementation of CAPTCHAs (Completely Automated Public Turing tests to tell Computers and Humans Apart).

Introduction

This package provides the functionality to create CAPTCHAs (Completely Automated Public Turing tests to tell Computers and Humans Apart). Features include:

Creating graphical CAPTCHAs using GD2
Pluggable driver architecture using factory pattern
Generic information about the CAPTCHA

The package creates CAPTCHAs; due to the stateless nature of the HTTP protocol, the logic to secure a webpage using the package must be specifically implemented. See the usage example for detailled information.

Currently, the graphical CAPTCHA driver depends on Image_Text which in turn requires TTF support to be compiled into PHP.

Example

The following example implements the standard use of a CAPTCHA: Submitted form data is only evaluated when a CAPTCHA has been solved correctly.

Creating a CAPTCHA

The following code creates a CAPTCHA, provides the relevant information for the package, anhd retrieves the CAPTCHA as a PNG image.

<?php
require_once 'Text/CAPTCHA.php';

// Set CAPTCHA options (font must exist!)
$imageOptions = array(
    'font_size'        => 24,
    'font_path'        => './',
    'font_file'        => 'COUR.TTF',
    'text_color'       => '#DDFF99',
    'lines_color'      => '#CCEEDD',
    'background_color' => '#555555'
);

// Set CAPTCHA options
$options = array(
    'width' => 200,
    'height' => 80,
    'output' => 'png',
    'imageOptions' => $imageOptions
);
           
// Generate a new Text_CAPTCHA object, Image driver
$c = Text_CAPTCHA::factory('Image');
$retval = $c->init($options);
if (PEAR::isError($retval)) {
    printf('Error initializing CAPTCHA: %s!',
        $retval->getMessage());
    exit;
}

// Get CAPTCHA secret passphrase
$_SESSION['phrase'] = $c->getPhrase();

// Get CAPTCHA image (as PNG)
$png = $c->getCAPTCHAAsPNG();
if (PEAR::isError($png)) {
    echo 'Error generating CAPTCHA!';
    echo $png->getMessage();
    exit;
}
file_put_contents(md5(session_id()) . '.png', $png);
?>

Securing a form with a CAPTCHA

The following code implements the functionality to check whether a CAPTCHA was solved correctly or not. for this, the CAPTCHA's phrase is stored in a session variable to retain this information between requests. It is important to unset the session after solving the CAPTCHA to avoid the reuse of the session ID.

<?php
session_start();
$ok = false;
$msg = 'Please enter the text in the image in the field below!';
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    if (isset($_POST['phrase']) && is_string($_POST['phrase']) && isset($_SESSION['phrase']) &&
        strlen($_POST['phrase']) > 0 && strlen($_SESSION['phrase']) > 0 &&
        $_POST['phrase'] == $_SESSION['phrase']) {
        $msg = 'OK!';
        $ok = true;
        unset($_SESSION['phrase']);
    } else {
        $msg = 'Please try again!';
    }
    unlink(md5(session_id()) . '.png');
}
print "<p>$msg</p>";

if (!$ok) {
    // create the CAPTCHA as seen above
    // and send it to the client
}
?>

See the file CAPTCHA_test.php in the package distribution for a full, working example (GD and TTF support required).

Information about the CAPTCHA and inner workings

Text_CAPTCHA provides information about the CAPTCHA and makes its inner workings accessible using several functions defined in the base class; the specific implementation of them is up to the driver.

init() is used to initialize the CAPTCHA and provide further information, like Image_Text parameters.
_createCAPTCHA() generates the CAPTCHA, but is called internally by init(). getPhrase() returns the CAPTCHA's phrase.
_createPhrase() creates a phrase for the CAPTCHA, but is used internally.
getCAPTCHA() returns the CAPTCHA, the format used depends on the driver implementation.