Skip to main content

reCAPTCHA Plugin

Introduction​

The reCAPTCHA Plugin allows you to add Google's reCAPTCHA service to your forms, making sure any user that submits the form is a legitimate user.

Installation​

Type composer require jump/oc-recaptcha-plugin into your project root terminal.

Repository​

Github

Configuration​

Depending on what version of reCAPTCHA you wish to use, there's a few different env variables you can set:

Version​

.env
JUMP_RECAPTCHA_DRIVER=V3

This sets the version of reCAPTCHA you will be using. By default, this will be version 3 (V3), but version 2 (V2) can also be implemented.

Keys​

.env
JUMP_RECAPTCHA_PUBLIC_KEY=PUBLIC-KEY-ASSIGNED-BY-GOOGLE
JUMP_RECAPTCHA_PRIVATE_KEY=PRIVATE-KEY-ASSIGNED-BY-GOOGLE

These are the keys you get from Google when setting up reCAPTCHA for your project.

A screengrab of the keys area with the Google reCAPTCHA settings area

caution

Make sure you get the correct keys for the version of reCAPTCHA you intend to use.

Score Threshold​

.env
JUMP_RECAPTCHA_THRESHOLD=0.5

When using version 3, Google assesses a user’s validity by assigning them a score ranging from 0.0 to 1.0 (with 0.0 being high risk/unlikely to be legitimate and 1.0 being low risk/likely to be legitimate).

This value sets the score that the user will have to beat in order to submit the form. A higher number makes the form more picky about whether it approves the user or not.

By default, this is set to 0.5, and it’s very unlikely it would need to be anything else.

Usage​

Setting it up in Google​

A screengrab of creating a new property in Google reCAPTCHA Admin Console

Firstly, log in to your Google account, and go to the reCAPTCHA Admin Console. You can then click the + to register a new site.

Add a label, select which version you wish to use, and then list the domains you want to protect with your new reCAPTCHA property (if you select version 2, you will also need to select what version of the reCAPTCHA you wish to use).

Then you just click Submit and you are good to go!

Adding it to Your Form​

To add reCAPTCHA to your form, you would simply add the following just before the submit button:

contact-form.htm
{{ recaptcha() }}

<p data-validate-for="g-recaptcha-response"></p>

Then, to enable the validation on form submission, and the following to the rules() method in your form's Action class:

/plugins/app/site/actions/SendEnquiry.php
<?php

namespace App\Site\Actions;

use Mail;
use Jump\Query\FormAction;
use Jump\Query\ParamBag;

class SendEnquiry extends FormAction
{
    protected function rules()
    {
        return [
            'g-recaptcha-response' => 'recaptcha',
        ];
    }
    
    ...
}

You would then add the following data-request-complete attribute to your form tag to reset the reCAPTCHA after a failed validation:

contact-form.htm
    <form
        class="c-Form__form"
        data-request="{{ actions.submit }}"
        data-request-validate
        data-request-flash
        method="post"
        data-request-complete="resetRecaptcha()"
    >
    ...