/laracaptcha

A Laravel package to seamlessly use hCapthca or reCaptcha v2 or v3 on your forms or RESTful APIs

Primary LanguagePHPMIT LicenseMIT

LaraCaptcha

Latest Version on Packagist Total Downloads GitHub Actions

A Laravel package to seamlessly integrate Google reCAPTCHA v3, v2 or hCAPTCHA into your application forms or Restful API.

Image 1 hCaptcha Image 2 reCaptcha

Supported Captcha Services

Service Version Type Supported
Google reCAPTCHA v3 - ✅ Yes
Google reCAPTCHA v2 Checkbox ✅ Yes
Google reCAPTCHA v2 Invisible ✅ Yes
hCAPTCHA - Checkbox ✅ Yes
hCAPTCHA - Invisible ✅ Yes

Installation

Note: This package requires PHP 7.4 or higher.

You can install the package via composer:

composer require martian/laracaptcha

Register Service Provider

Add the following to the providers array in config/app.php:

Martian\LaraCaptcha\Providers\LaraCaptchaServiceProvider::class,

Publish Configuration File

Publish the configuration file using the following command:

php artisan vendor:publish --provider="Martian\LaraCaptcha\Providers\LaraCaptchaServiceProvider"

Configuration

The configuration file is located at config/laracaptcha.php. The following options are available:

reCAPTCHA v2 Configuration

  • In order to use reCAPTCHA you need to register your site for an API key pair. To use reCaptcha v2 Checkbox, select Challenge (v2) > I'm not a robot Checkbox. To use the invisible reCAPTCHA, select Challenge (v2) > Invisible reCAPTCHA badge. The API key pair consists of a site key and secret key. Set the default option to recaptcha in config/laracaptcha.php:

    'default' => 'recaptcha',

  • Change the version option to v2 to use reCAPTCHA v2:

    'drivers' => [
    'recaptcha' => [
        ...
        'version' => 'v2',
        ...
    ],
],

  • Add RECAPTCHA_SITE_KEY and RECAPTCHA_SECRET_KEY to your .env file:

    RECAPTCHA_SITE_KEY=your-site-key
RECAPTCHA_SECRET_KEY=your-secret-key

reCAPTCHA v3 Configuration

  • In order to use reCAPTCHA you need to register your site for an API key pair. To use reCaptcha v3, select reCAPTCHA v3. The API key pair consists of a site key and secret key. Set the default option to recaptcha in config/laracaptcha.php:

    'default' => 'recaptcha',

  • Change the version option to v3 to use reCAPTCHA v3:

    'drivers' => [
    'recaptcha' => [
        ...
        'version' => 'v3',
        ...
    ],
],

  • Add RECAPTCHA_SITE_KEY, RECAPTCHA_SECRET_KEY and RECAPTCHA_SITE_URL to your .env file:

    RECAPTCHA_SITE_KEY=your-site-key
RECAPTCHA_SECRET_KEY=your-secret-key
RECAPTCHA_SITE_URL=${APP_URL}

hCAPTCHA Configuration

  • In order to use hCAPTCHA you need to register your site for an API key pair. The API key pair consists of a site key and secret key. Set the default option to hcaptcha in config/laracaptcha.php:

    'default' => 'hcaptcha',

  • Add HCAPTCHA_SITE_KEY and HCAPTCHA_SECRET_KEY to your .env file:

    HCAPTCHA_SITE_KEY=10000000-ffff-ffff-ffff-000000000001
HCAPTCHA_SECRET_KEY=0x0000000000000000000000000000000000000000

These are the test keys we use by default. You should not use them in production!

Usage

To display captcha in your form, follow the steps below according to the captcha configuration you are using.

reCAPTCHA v2 Checkbox & Invisible

Initializing JavaScript

Add the following to the <head> section of your page:

{!! LaraCaptcha::script() !!}

With other options in Google reCaptcha v2 Checkbox dox

{!! LaraCaptcha::script('yourCallbackFunction', 'explicit', 'en') !!}

Note: The first parameter is the callback function name, the second is the rendering mode (explicit or onload), and the third is the language code from doc

Displaying Captcha Widget - Checkbox

Add the following to your form:

{!! LaraCaptcha::display() !!}

With other options in Google reCaptcha v2 Checkbox dox

{!! LaraCaptcha::display(['data-theme' => 'dark']) !!}

Note: The parameter is an array of attributes for the widget

Displaying Captcha Widget - Invisible

Add the following to your form:

{!! LaraCaptcha::displayInvisibleButton('formIdentifier', 'Submit Button',['data-size' => 'invisible']) !!}

Note: The first parameter is the form identifier, the second is the button label (Submit Button), and the third is an array of attributes for the widget, see doc. Add the formIdentifier value as the id in the form element

Validating Captcha

Add the following to your validation rules:

'g-recaptcha-response' => 'recaptcha',

You can also use the rule in the Validator facade:

$validator = Validator::make($request->all(), [
    'g-recaptcha-response' => 'recaptcha',
]);

Add Custom Validation Message

Add the following to your validation messages:

'g-recaptcha-response.recaptcha' => 'Captcha verification failed.',

Or you can change the default message in config/laracaptcha.php:

'error_message' => 'Captcha verification failed.',

reCAPTCHA v3

Initializing JavaScript

Add the following to the <head> section of your page:

{!! LaraCaptcha::script() !!}

With other options in Google reCaptcha v3 dox

{!! LaraCaptcha::script('yourCallbackFunction', 'explicit', 'en') !!}

Displaying Captcha Widget

Add the following to your form:

{!! LaraCaptcha::display() !!}

With other options in Google reCaptcha v3 dox

{!! LaraCaptcha::display(['action' => 'homepage', 'custom_validation' => 'yourCustomFunction', 'recaptcha_input_identifier' => 'yourReCaptchaInputId']) !!}

Note: The parameter is an array of attributes for the widget, see doc for actions type

hCAPTCHA v2 Checkbox & Invisible

Initializing JavaScript

Add the following to the <head> section of your page:

{!! LaraCaptcha::script() !!}

With other options in hCAPTCHA dox

{!! LaraCaptcha::script('yourCallbackFunction', 'onload' 'en', 'on') !!}

Note: The first parameter is the callback function name, the second is the rendering mode (onload or explicit), the third is the language code from doc, and the fourth is the recaptchacompat option

Displaying Captcha Widget - Checkbox

Add the following to your form:

{!! LaraCaptcha::display() !!}

With other options in hCAPTCHA dox

{!! LaraCaptcha::display(['data-theme' => 'dark']) !!}

Note: The parameter is an array of attributes for the widget

Displaying Captcha Widget - Invisible

Add the following to your form, see documentation for invisible hcaptcha:

{!! LaraCaptcha::displayInvisibleButton('formIdentifier', 'Submit Button',['data-size' => 'invisible']) !!}

Note: The first parameter is the form identifier, the second is the button label (Submit Button), and the third is an array of attributes for the widget, see doc

Validating Captcha

Add the following to your validation rules:

'h-captcha-response' => 'hcaptcha',

You can also use the rule in the Validator facade:

$validator = Validator::make($request->all(), [
    'h-captcha-response' => 'hcaptcha',
]);

Add Custom Validation Message

Add the following to your validation messages:

'h-captcha-response.hcaptcha' => 'Captcha verification failed.',

Or you can change the default message in config/laracaptcha.php:

'error_message' => 'Captcha verification failed.',

For other configuration go through the config/laracaptcha.php file.

Testing

./vendor/bin/phpunit

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email hendurhance.dev@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.