laravel-recaptchav3

To ensure Recaptcha V3 has enough context about user interactions, load the Javascript by adding the following to your header or footer template:

{!! RecaptchaV3::initJs() !!}

Install the package via Composer and configure your Google Recaptcha credentials in your .env file.

composer require josiasmontag/laravel-recaptchav3

Add your Google Recaptcha V3 credentials to your .env file. You can also optionally set a specific locale using RECAPTCHAV3_LOCALE.

RECAPTCHAV3_SITEKEY=sitekey
RECAPTCHAV3_SECRET=secret
# Optional: Set a specific locale (e.g., 'ar')
RECAPTCHAV3_LOCALE=ar

To customize the package settings, publish the configuration file to your application's config directory using the config tag:

php artisan vendor:publish --tag=config

This will copy the package's internal configuration to config/recaptchav3.php.

If you wish to hide the default Google ReCAPTCHA badge, add the following rule to your CSS:

.grecaptcha-badge { visibility: hidden !important; }

You can mock the RecaptchaV3 facade in your tests to simulate successful or failed verification.

RecaptchaV3::shouldReceive('verify')
    ->once()
    ->andReturn(1.0);

Use the recaptchav3 validation rule. The rule accepts two parameters: the action name and the minimum required score (which defaults to 0.5).

$validate = Validator::make(Input::all(), [
	'g-recaptcha-response' => 'required|recaptchav3:register,0.5'
]);

Use RecaptchaV3::field($action, $name='g-recaptcha-response') to create an invisible input field that automatically populates with a Recaptcha token on page load.

<form method="post" action="/register">
    {!! RecaptchaV3::field('register') !!}
    <input type="submit" value="Register"></input>
</form>

If you need to perform custom logic based on the score, use the verify($token, $action) method on the RecaptchaV3 facade. It returns the score as a float.

use Lunaweb\RecaptchaV3\Facades\RecaptchaV3;

// Returns the score (float)
$score = RecaptchaV3::verify($request->get('g-recaptcha-response'), 'register');

if($score > 0.7) {
    // proceed
} elseif($score > 0.3) {
    // require additional verification
} else {
    return abort(400, 'You are most likely a bot');
}

To change the error message for Recaptcha validation, add a key for recaptchav3 inside the custom array of your application's validation language file.

'custom' => [
    'g-recaptcha-response' => [
        'recaptchav3' => 'Captcha error message',
    ],
],

The field($action, $name = 'g-recaptcha-response') method generates the HTML required to capture the Recaptcha token on the client side.

It produces:

1. A hidden <input> element with a unique ID.
2. A <script> block that uses grecaptcha.execute to fetch a token for the specified $action and injects it into the input field.

This should be placed within your form.

// In your Blade template inside a form
<form method="POST" action="/submit">
    {!! $recaptchaV3->field('submit_form') !!}
    <!-- other form fields -->
    <button type="submit">Submit</button>
</form>

Use the verify($token, $action = null) method to validate a token received from the client side.

• If the token is invalid or the verification fails, it returns false.
• If the token is valid, it returns the score (float) provided by Google.
• If an $action is provided, the method will also verify that the action name in the token matches the provided $action. If they do not match, it returns false.

// Returns the score (e.g., 0.9) if valid, or false if invalid
$score = $recaptchaV3->verify($token, 'login');

if ($score !== false) {
    // Proceed with logic
}