ReCaptcha

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 http://www.google.com/recaptcha. 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 https://www.google.com/recaptcha/admin/create. In case you do not have a Google account yet, please sign-up there.

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 https://github.com/google/recaptcha.

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 https://developers.google.com/recaptcha/docs/display#config.

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 https://developers.google.com/recaptcha/docs/display#config. 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.

Comments

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.

ReCaptcha

Comments

QUICKNAVI