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:
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:
<form:recaptcha
name=""
public-key=""
private-key=""
[theme="dark|light"]
[lang=""]
[size=""]
[tabindex=""]
[valmarkerclass=""]
/>-
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-_])
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:
<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>To display the above form, you need a (Document-)Controller like this:
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.
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:
<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:
$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
QUICKNAVI
JetBrains supports the development of the APF with PHPStorm licenses and we feel confidential that PHPStorm strongly influences the APF's quality. Use PHPStorm!
