README

Build status:

This is PHP library that handle Google's reCAPTCHA API, you can easy implement it into your site or app and be able to set custom configurations and options to display the widget as you want.

Library Features

• Display a reCAPTCHA V1 widget onto your form.
• Validate a given input value for an image Captcha and returns the result.
• Support to different Standard Theme, Custom Theming and Template customization.
• Internationalization support and custom language strings translation.
• Custom Global configuration if you need to run reCAPTCHA in many forms.
• Individually configuration for each widget.
• Timeout configuration for request server API.
• Error handling.
• Uses socket connection for API calls fallback to CURL whether the function fsockopen is not available.
• Fully customization and optimization to display reCAPTCHA
• Ease implementation

Quick Installation via composer

You can find this library at Composer/Packagist.

$ composer require "recaptcha-lib/recaptcha:0.1.*"

Optional Manual Install

If you don't use composer you'll have to download the latest release of this library and unpack it within your project folder.

Once you've done it, you'll need only those files within the ReCaptcha folder you can get rid of others files and samples in there, if you want to.

The reCAPTCHA Libray comes with an Autoloader that you can include in the top of your page. By using the autoloader there is no need of including files manually, see an example below:

require_once 'ReCaptcha/CaptchaAutoloader.php';

$captcha = new \ReCaptcha\Captcha();
echo $captcha->displayHTML();

Displaying reCAPTCHA

Display default options and theme.

use ReCaptcha\Captcha;

$captcha = new Captcha();
$captcha->setPublicKey('YourPublicKey');
echo $captcha->displayHTML();

Display a Standard Theme, your API Keys and options from a config file.

use ReCaptcha\Captcha;

$my_config = '/optional/path/to/captcha_config.php';
$captcha = new Captcha();
$captcha->setConfig($my_config);
echo $captcha->displayHTML();

To display a different theme and language straightforward.

echo $captcha->displayHTML('theme_name', array('lang'=>'es'));

Samples

ReCaptcha-lib provides many ways to display and configure a reCAPTCHA widget. A theme can be set by a given name e.g: Captcha::displayHTML('clean'). You can find all Standard Theme names in https://developers.google.com/recaptcha/docs/customization.

displayHTML();	displayHTML('white');	displayHTML('clean');	displayHTML('custom');

NOTE: When using a custom theme, as you can see above, the template is displayed in pure HTML so you need to provide a CSS to display a custom theme properly to your users. The widget elements are wrapped within a div container default ID recaptcha_widget but you can change this ID using the option custom_theme_widget

array('custom_theme_widget' => 'my_widget_id_name');

You can find more examples how to implement reCAPTCHA in examples folder.

Verifying reCAPTCHA User's Answer

The Library has a method Captcha::isValid() to check the user's answer when performing a form post. It's easy to implement.

Basic Verify

$captcha = new Captcha();
$captcha->setPrivateKey('YourPrivateKey');

if ( !$captcha->isValid() ) {

   echo $captcha->getError();
   // stop action

} else {

   echo 'Captcha Valid!!!';
   // do something else
}

The method Captcha::isValid() takes an action only when its encountered a REQUEST_METHOD POST, so you can set in the same page that method Captcha::displayHTML()

$captcha = new Captcha();

$captcha->setPublicKey('YourPublicKey');
$captcha->setPrivateKey('YourPrivateKey');

// only perform when the form is submitted
if ( !$captcha->isValid() ) {
   echo $captcha->getError();
}

echo $captcha->displayHTML();
// something else ...

Options

Custom options can be set by passing an array of values to Captcha::displayHTML()

array('lang'=>'it', 'tabindex'=>2);

Custom theming and language of the widget

$captcha->displayHTML(
	'custom',
	array(
		'lang'=>'it',
		'custom_theme_widget'=>'my_container_id'
	)
);

Configuration

Changing Widget Language

Set a language in object constructor as a first parameter.

$captcha = new Captcha('pt');

Run reCAPTCHA Over SSL

When using SSL site, to avoid getting browser certificate warnings when you display reCAPTCHA set a second parameter to TRUE in object constructor.

$captcha = new Captcha(NULL, TRUE);

NULL set the language to default system built-in translation. TRUE enable call API using https://

Timeout

The Library has a timeout when performing a request server API to verify the user's answer. The default timeout value is 10. If you want to change.

$captcha->timeout = 100;

Global Config

If you want instead of passing arrays all the time into your widget you might set a Global configuration by creating an external file with all options and configurations to be read globally.

Sample File: captcha_config.php.

// your KEYs
$CAPTCHA_CONFIG['publicKey']  = '6Ldoa_YourPublicKey';
$CAPTCHA_CONFIG['privateKey'] = '6Ldoa_YourPrivateKey';

// reCAPTCHA options
$CAPTCHA_CONFIG['recaptchaOptions'] = array(
                     'theme'    => 'custom',
                     'lang'     => 'it',
                     'tabindex' => 0
                     );

// Enable/Disable when you use reCAPTCHA on SSL site
$CAPTCHA_CONFIG['ssl'] = false;

// Set Server API timeout
$CAPTCHA_CONFIG['timeout'] = 10;

Then pass its path to the method: Captcha::setConfig($path).

// Set Global config captcha_config.php
$my_config = '/path/to/my/captcha_config.php';
$captcha = new Captcha();
$captcha->setConfig($my_config);

Internationalization

This library has two different approaches to display reCAPTCHA widget in a different language to the user's screen.

Built-in Language

It's a default Google's reCAPTCHA API language translation, so the widget strings are shown according the user's browser language preference, whether user's language is not in the system built-in the English will be used instead.

Custom language

If you are using Custom Theme Template you must set a customized translation as well, despite using any Standard Theme that you need to display your reCAPTCHA widget in a different language which is not available in system built-in you can use your own translation strings.

This library offers you a simple way to customize translation strings, within a folder I18n there's a few languages already translated in there. If you want to use one of them just pass the language code as first parameter to the object constructor. See examples in section options and configuration above.

Even if your language is not in there, you have two options to get your widget translated.

Create a Language File

You might translate the widget strings by writing a file recaptcha.lang.[lang_code].php take a look one of them within I18n folder as a reference*, place it somewhere in your dir, then tell to the library where it is by passing its path as a second parameter to the method Captcha::setTranslation(lang_code, path).

$myCustomLang = '/optional/path/to/file/lang'; // no need trailing slash.
$captcha->setTranslation('fr', $myCustomLang);

This will point to a file: /optional/path/to/file/lang/recaptcha.lang.fr.php

NOTE: your custom Lang file must be named as recaptcha.lang.[lang_code].php where lang_code is your language abbreviation e.g. 'French' is fr.

Optional

Instead of create an external Lang file you may also translate your widget strings by passing an array to the custom_translations option:

$my_options = array(
   'custom_theme_widget'=>'recaptcha_widget',
   'tabindex' => 0,
   'lang' => 'de',
   'custom_translations' => array(
      'instructions_visual' => 'Geben Sie den angezeigten Text ein',
      'instructions_audio'  => 'Geben Sie das Gehörte ein:',
      'play_again'          => 'Wort erneut abspielen   ',
      'cant_hear_this'      => 'Wort als MP3 herunterladen',
      'visual_challenge'    => 'Captcha abrufen',
      'audio_challenge'     => 'Audio-Captcha abrufen',
      'refresh_btn'         => 'Neues Captcha abrufen',
      'help_btn'            => 'Hilfe',
      'incorrect_try_again' => 'Falsch, bitte versuchen Sie es erneut.'
    )
);

Collaborate If you want to translate a language file and collaborate, fork this project do it and send us a pull request.

Theme Customization

There are a few Standard Theme ready to go with, as written in Samples, but to go any further, it's possible to style as you want by adding an option theme=>custom as array to config file, by parameter option or straightforward Captcha::displayHTML('custom'). To do so set one of these options and create a CSS to prettify it, you can checkout demo or see more in reCAPTCHA Custom Theming Docs.

Documentation

This library has a better documentation generated by PHPDoc you can take a look at Documentation Page.

Bugs

Have you found a bug? Please open a new issue.

Author

Adriano Rosa @adrianorosa

Notes

In order to start using this library you must generate your reCAPTCHA's API Key from Google's reCAPTCHA site.

License

This software is licensed under the MIT License. Please read LICENSE for information on the software availability and distribution.