The ReCaptcha module contains a tag that seamlessly integrates with APF Forms. The configuration and validation of the field can be done as known from other form elements.

ReCaptcha is a CAPTCHA service offered by Google under The touring test provided there is deemed to be the best implementation form SPAM defense.

The following chapters describe the usage and configuration in detail.

1. ReCaptcha key

In order to use ReCaptcha please register an account under In case you do not have a Google account yet, please sign-up there.

ReCaptcha key request form

Please fill in the form field and submit your request clicking on the button. After processing your request, you are displayed the generated key. In case you intend to use the key for multiple domains, please follow the instructions within the request form.

ReCaptcha key

Please note or save the key because you will need it during configuration of the CAPTCHA field.

2. Usage

2.1. Basic configuration

Implementation of APF's ReCaptcha functionality is based on the external library recaptchalib that is available under

Zur Aktivierung der Funktionalität laden Sie sich die bitte von der angebenen Adresse herunter und legen diese in Ihrem Projekt ab. Anschließend binden Sie die Datei wie folgt z.B. in Ihrer Bootstrap-Datei ein, damit die Klassen ReCaptchaTag und ReCaptchaValidator auf die Funktionalität zurückgreifen können:

PHP code

2.2. Usage within forms

In order to easily use the ReCaptcha service the APF module includes a tag that is similar to other form tags. The signature is as follows:

APF template
<form:recaptcha name="" public-key="" private-key="" theme="" [custom-theme-id=""] [tabindex=""] />
Description of the attributes:

In order to use the field with a <html:form /> tag, please add the following phrase:

APF template
<form:addtaglib class="APF\modules\recaptcha\pres\taglib\ReCaptchaTag" prefix="form" name="recaptcha" />

Immediately after you can use the field as described in the subsequent code box:

APF template
<core:addtaglib class="APF\tools\form\taglib\HtmlFormTag" prefix="html" name="form" /> <html:form name="newsletter-signup"> <form:error> <p class="error"> The form is <strong>not</strong> filled correctly! </p> </form:error> <form:success> <p class="error"> The form is filled correctly. </p> </form:success> <p> <label for="email">Email address</label> <form:text name="email" id="email"/> <form:addvalidator class="APF\tools\form\validator\TextLengthValidator" control="email" button="send" /> <form:addvalidator class="APF\tools\form\validator\EMailValidator" control="email" button="send" /> </p> <p> <form:addtaglib class="APF\modules\recaptcha\pres\taglib\ReCaptchaTag" prefix="form" name="recaptcha" /> <form:recaptcha name="re-captcha" public-key="123456789012341-0000000000-ABCDE8764Rfc3" private-key="123456Rt3012341-1111111111-ABCDE8764Rfc-P" theme="white" /> <form:addvalidator class="APF\modules\recaptcha\pres\validator\ReCaptchaValidator" control="re-captcha" button="send" /> </p> <p> <form:button name="send" value="Send" /> </p> </html:form>
Please note that the public and private key within the above code box are sample keys that cannot be used within your application. Please sign up your own key pair as described in chapter 1.

To display the above form, you need a (Document-)Controller like this:

PHP code
class NewsletterController extends BaseDocumentController { public function transformContent() { $this->getForm('newsletter-signup')->transformOnPlace(); } }

3. Validation

As mentioned in chapter 2 the recaptcha module includes a validator that checks the user's input. Similar to the CAPTCHA tag (for forms) module it is necessary to define a validator for the ReCaptcha field.

In case no validator is attached to the ReCaotcha field within your form the CAPTCHA field is always valid and attackers may compromise your form freely.

Validation as well as the field generation is based on the reCAPTCHA PHP library. To guarantee ease of use this module includes an APF form validator that wraps this library. The validator can be used as follows:

APF template
<form:addvalidator class="APF\modules\recaptcha\pres\validator\ReCaptchaValidator" control="..." button="..." />

The control attribute refers to the desired ReCaptcha field (see chapter 2) and button defines the button that triggers the validation event. Details on form validators can be found on Forms.

4. Customizing

The Google ReCaptcha field is easy to adapt and the APF form element provides several attributes to support easy adaption.

4.1. Themes

The ReCaptcha element brings several basic themes as described under These are:

  • red (default)
  • white
  • blackglass
  • clean

You may define your favourite theme using the theme attribute of the <form:recaptcha /> tag.

In case you intend to use your own theme, please read the hints on carefully. Using custom themes, the theme attribute must be filled with custom.

4.2. Internationalisation

The ReCaptcha field supports several languages out-of-the-box. Generating the field the <form:recaptcha /> tag applies the currently selected language from the $this->language field. To control the language you may want to use the code described under (German).

In case you are not using dynamic language switches, please ensure that the language is set correctly within your bootstrap file:

PHP code
$fC = &Singleton::getInstance('Frontcontroller'); ... $fC->setLanguage('xyz'); ...

4.3. Custom translations

4.3.1. Configuration via attribute

Besides the translation mechanism described in chapter 4.2 you are able to provide your own texts for the different parts of the ReCaptcha field. For this reason, the following attributes ara available:

Attribute JavaScript option name Description
label-instructions-visual instructions_visual Label for the CAPTCHA image.
label-instructions-audio instructions_audio Label for the CAPTCHA audio.
label-play-again play_again Label for the play-again button for audio CAPTCHAs.
label-cant-hear-this cant_hear_this Label for choosing a new audio CAPTCHA.
label-visual-challenge visual_challenge Label for choosing a new image CAPTCHA.
label-audio-challenge audio_challenge Label for changing to an audio CAPTCHA.
label-refresh-btn refresh_btn Alternative text for the load-again button.
label-help-btn help_btn Label for the help button.
label-incorrect-try-again incorrect_try_again Error message for wrong CAPTCHA solving.

The attributes described in the above table may be used as follows:

APF template
<form:recaptcha name="my-captcha" ... [label-instructions-visual=""] [label-instructions-audio=""] [label-play-again=""] [label-cant-hear-this=""] [label-visual-challenge=""] [label-audio-challenge=""] [label-refresh-btn=""] [label-help-btn=""] [label-incorrect-try-again=""] />
Each of the attributes is optional (thus marked with brackets). In case an attribute is not specified, the default value for the current language is used.
4.3.2. Configuration via tag

As an alternative translation texts can also be specified via language files. For this reason, the <form:recaptcha /> tag ships with the <recaptcha:getstring /> implementation:

APF template
<form:recaptcha name="my-captcha"> <recaptcha:getstring namespace="" config="" entry="" /> </form:recaptcha>

The attributes of the <recaptcha:getstring /> tag are the same as for <html:getstring /> tags. In order to add custom translations using the <recaptcha:getstring /> tag a custom language file including the desired language and texts must be created. Having a tag definition like

APF template
<form:recaptcha name="my-captcha"> <recaptcha:getstring namespace="APF\sites\my-site\pres" config="recaptcha_labels.ini" entry="guestbook" /> </form:recaptcha>

the tag expects a configuration file named {ENVIRONMENT}_recaptcha_labels.ini and stored under config/sites/my-site/pres/{CONTEXT}/. In case you intend to provide custom translations of the ReCaptcha control in German and English the content of the file is as follows:

APF configuration
[de] guestbook.label-instructions-visual="" guestbook.label-instructions-visual="" guestbook.label-instructions-audio="" guestbook.label-play-again="" guestbook.label-cant-hear-this="" guestbook.label-visual-challenge="" guestbook.label-audio-challenge="" guestbook.label-refresh-btn="" guestbook.label-help-btn="" guestbook.label-incorrect-try-again="" [en] guestbook.label-instructions-visual="" guestbook.label-instructions-visual="" guestbook.label-instructions-audio="" guestbook.label-play-again="" guestbook.label-cant-hear-this="" guestbook.label-visual-challenge="" guestbook.label-audio-challenge="" guestbook.label-refresh-btn="" guestbook.label-help-btn="" guestbook.label-incorrect-try-again=""

The sections de and en contain the labels for the respective language and further languages may be added as desired. The sub-section of each language - guestbook in this case - describes the usage of the CAPTCHA. This enables you to define different labels for different use cases within one file.

The sub-section of each language is addressed by the entry attribute. Below, the label attributes are the same as the tag attributes (see table in chapter 4.3.1).

Each attribute to be used with the <recaptcha:getstring /> tag is considered optional. In case an attribute is missing the default value for the current version is used instead.

Details on configurations and on the handling with different contexts ({CONTEXT}) and environments ({ENVIRONMENT}) can be found under Configuration.

4.4. Tab index

The ReCaptcha element supports the definition of field orders using the tab key. In order to define the index, please provide the tabindex attribute of the <form:recaptcha /> tag with the intended number.

4.5. SSL usage

In order to use the SSL-based service of the ReCaptcha API please use the use-ssl attribute. In case it contains true the SSL-based API of Google's ReCaptcha service is used. In case the attribute is not present, the HTTP service is considered.


Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.
There are no comments belonging to this article.