Manual

Services_ReCaptcha is a PHP5 interface to the two services offered by recaptcha: reCAPTCHA and reCAPTCHA Mailhide.

Introduction

Introduction – introduction to the Services_ReCaptcha package

Introduction

Services_ReCaptcha is a PHP5 interface to the two services offered by reCAPTCHA: reCAPTCHA and reCAPTCHA Mailhide.

reCAPTCHA is a freely available CAPTCHA implementation. It distinguishes humans from computers. To use reCAPTCHA, you will need a public/private API key pair, available here: http://recaptcha.net/api/getkey.

reCAPTCHA Mailhide helps you protect your inbox by asking people to solve a reCAPTCHA before they can view your email address. The reCAPTCHA can only be solved by humans, so this stops spammers from gaining access to your email address through automated programs. reCAPTCHA Mailhide also requires a public and a private API key, that can be generated here: http://mailhide.recaptcha.net/apikey.

Installation

To install the package with pear just do:

$ pear install Services_ReCaptcha

And to uninstall it:

$ pear uninstall Services_ReCaptcha

reCAPTCHA

reCAPTCHA – getting started with the reCAPTCHA functionality of Services_ReCaptcha

Instanciating the Services_ReCaptcha class

To instanciate the Services_ReCaptcha class just do:

<?php

require_once 'Services/ReCaptcha.php';

$recaptcha = new Services_ReCaptcha('your_public_key', 'your_private_key');

?>

You can also pass an array of option as third parameter, or pass options later with the Services_ReCaptcha_Base::setOption() or Services_ReCaptcha_Base::setOptions()

Available options are:

Services_ReCaptcha options
Name	Description	Type	Default value
secure	Whether to force the ssl url or not	boolean	false
xhtml	Whether the html should be xhtml compliant or not	boolean	true
theme	The theme to use for the CAPTCHA	string	red
lang	The language to use for the CAPTCHA (must be one of the reCATCHA supported languages codes)	string	en
custom_translations	An array of cutom translations to use	array	null
custom_theme_widget	The id of the HTML element corresponding to the theme widget	string	null
tabindex	The HTML tabindex attribute for the reCAPTCHA textarea	string	null

For more information about these options please consult relevant reCAPTCHA API docs.

A simple recaptcha example

<?php

/**
 * Include the Services_ReCaptcha class
 */
require_once 'Services/ReCaptcha.php';

// you must get your API keys here:
// http://recaptcha.net/api/getkey
$publicKey  = 'your_public_key';
$privateKey = 'your_private_key';

// we instanciate our Services_ReCaptcha instance with the public key and the 
// private key
$recaptcha = new Services_ReCaptcha($publicKey, $privateKey);

// if the form was submitted and the catpcha challenge response is ok, we 
// display a message and exit
if (isset($_POST['submit']) && $recaptcha->validate()) {
    echo "Challenge response ok !";
    exit(0);
}

// we display the html form
?>
<html>
<head>
    <title>recaptcha test</title>
</head>
<body>
    <form method="post" action="">
<?php echo $recaptcha; ?>
        <hr/>
        <input type="submit" name="submit" value="Ok"/>
    </form>
</body>
</html>

A more advanced recaptcha example

<?php

/**
 * Include the Services_ReCaptcha class
 */
require_once 'Services/ReCaptcha.php';

// you must get your API keys here:
// http://recaptcha.net/api/getkey
$publicKey  = 'your_public_key';
$privateKey = 'your_private_key';

// we instanciate our Services_ReCaptcha instance with the public key and the 
// private key
$recaptcha = new Services_ReCaptcha($publicKey, $privateKey);

// we are going to customize our Services_ReCaptcha instance
$recaptcha->setOption('secure', true);   // we force the secure url
$recaptcha->setOption('theme', 'white'); // use the white theme
$recaptcha->setOption('lang', 'fr');     // set language to french

// alternatively we could have done:
// $recaptcha = new Services_ReCaptcha($publicKey, $privateKey, array(
//     'secure' => true,
//     'theme'  => 'white',
//     'lang'   => 'fr'
// ));
// or:
// $recaptcha->setOptions(array('theme' => 'white', 'lang' => 'fr'));

// we use a proxy, so we need to configure it
$recaptcha->getRequest()->setConfig(
    array('proxy_host' => 'localhost', 'proxy_port' => 8118)
);

// if the form was submitted
if (isset($_POST['submit'])) {
    if ($recaptcha->validate()) {
        // the catpcha challenge response is ok, we display a message and exit
        echo "Challenge response ok !";
        exit(0);
    } else {
        // if the captcha validation failed, instead of letting the captcha 
        // display the error, we want to echo the error and exit
        echo $recaptcha->getError();
        exit(1);
    }
}

// we display the html form
?>
<html>
<head>
    <title>recaptcha test</title>
</head>
<body>
    <form method="post" action="">
<?php echo $recaptcha; ?>
        <hr/>
        <input type="submit" name="submit" value="Ok"/>
    </form>
</body>
</html>

reCAPTCHA Mailhide

reCAPTCHA Mailhide – getting started with the Mailhide functionality of Services_ReCaptcha

Instanciating the Services_ReCaptcha_MailHide class

To instanciate the Services_ReCaptcha_MailHide class just do:

<?php

require_once 'Services/ReCaptcha/MailHide.php';

$recaptcha = new Services_ReCaptcha_MailHide('your_public_key', 'your_private_key', 'email_to_hide@example.com');

?>

You can also pass an array of option as third parameter, or pass options later with the Services_ReCaptcha_Base::setOption() or Services_ReCaptcha_Base::setOptions()

Available options are:

Services_ReCaptcha_MailHide options
Name	Description	Type	Default value
mask_text	The chars that will be displayed in the email address to hide it	string	... (three dots)
link_text	An alternate string for the text of the link	string	null
link_title	Text to display as the title (tooltip) of the link	string	Reveal this e-mail address
popup_width	The popup width in pixels	integer	500
popup_height	The popup height in pixels	integer	300

Recaptcha Mailhide example

<?php

/**
 * Include the Services_ReCaptcha_MailHide class
 */
require_once 'Services/ReCaptcha/MailHide.php';

// you must generate your API keys here:
// http://mailhide.recaptcha.net/apikey
$publicKey  = 'your_public_key';
$privateKey = 'your_private_key';

// we instanciate our Services_ReCaptcha_MailHide instance with the public key
// and the private key
$mailhide1 = new Services_ReCaptcha_MailHide(
    $publicKey,
    $privateKey,
    'johndoe@example.com'
);

$mailhide2 = new Services_ReCaptcha_MailHide(
    $publicKey,
    $privateKey,
    'johndoe@example.com',
    array('link_text' => 'John Doe')
);

$mailhide3 = new Services_ReCaptcha_MailHide(
    $publicKey,
    $privateKey,
    'johndoe@example.com'
);
$mailhide3->setOptions(
    array(
        'link_text'    => 'Click here to display my email',
        'link_title'   => 'Some help message',
        'link_title'   => 'Some help message',
        'popup_width'  => 800,
        'popup_height' => 600,
    )
);

?>
<html>
<head>
    <title>recaptcha test</title>
</head>
<body>
    <h2>Hidden emails can be displayed like this:</h2>
    <p><?php echo $mailhide1 ?></p>
    <h2>Like this:</h2>
    <p><?php echo $mailhide2 ?></p>
    <h2>And even like this:</h2>
    <p><?php echo $mailhide3 ?></p>
</body>
</html>