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.

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 recaptcha that is available under

To use the functionality please download the library and unpack it within your project. As an alternative, you may want to install the library via composer.

In order to use the library, please add the installation path to your auto loader configuration:

PHP code
RootClassLoader::addLoader( new StandardClassLoader( 'ReCaptcha', __DIR__ . '/vendor/ReCaptcha' ) );

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="dark|light"] [lang=""] [size=""] [tabindex=""] [valmarkerclass=""] />
Description of the attributes:
  • name: Name of the ReCaptcha control. Used to refer the control within a validator definition. (Allowed characters: [A-Za-z0-9_-])
  • public-key: Public key to use the ReCaptcha service with. (Allowed characters: [A-Za-z0-9-])
  • private-key: Private key to use the ReCaptcha service with. (Allowed characters: [A-Za-z0-9-])
  • theme: Name of the theme. Default: light. (Allowed characters: dark|light)
  • lang: Selected language to display. In case this option is not set the current document language will be used. Further notes can be found in chapter 4.2.
  • size: Size of the control. Default: normal. (Allowed characters: compact|normal)
  • tabindex: Defines the position of the field for tab key usage. (Allowed characters: [0-9])
  • valmarkerclass: CSS class used to mark the control in case of invalid input. Default: apf-form-error (Allowed characters: [A-Za-z0-9-_])
Details on the configuration can be taken from

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

The field can be used as described in the subsequent code box:

APF template
<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"/> </p> <p> <form:recaptcha name="re-captcha" public-key="123456789012341-0000000000-ABCDE8764Rfc3" private-key="123456Rt3012341-1111111111-ABCDE8764Rfc-P" /> </p> <p> <form:button name="send" value="Send" /> <form:addvalidator class="APF\tools\form\validator\TextLengthValidator" control="email" button="send" /> <form:addvalidator class="APF\tools\form\validator\EMailValidator" control="email" button="send" /> <form:addvalidator class="APF\modules\recaptcha\pres\validator\ReCaptchaValidator" control="re-captcha" button="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:

  • light (default)
  • dark

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

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 in Wiki (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::class); ... $fC->setLanguage('xyz'); ...

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.


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.

In order to provide a state-of-the-art web experience and to continuously improve our services we are using cookies. By using this web page you agree to the use of cookies. For more information, please refer to our Privacy policy.