bataboom/h-captcha

hCAPTCHA For Laravel.

dev-master 2025-03-27 14:14 UTC

Requires

• php: >=5.5.5
• filament/forms: ^2.16|^3.0-stable|^3.2.51
• guzzlehttp/guzzle: ^6.2|^7.0
• illuminate/support: ^5.0|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^12.0

Requires (Dev)

• phpunit/phpunit: ~4.8|^9.5.10|^10.5

MIT

• bataboom

• captcha
• laravel
• laravel4
• laravel5
• laravel6
• hcaptcha
• h-captcha
• laravel10

README

Inspirations: anhskohbo/no-captcha package. abanoubnassem/filament-grecaptcha-field package.

Installation

composer require bataboom/h-captcha:dev-master

Laravel 5 and above

Setup

NOTE This package supports the auto-discovery feature of Laravel 5.5 and above, So skip these Setup instructions if you're using Laravel 5.5 and above.

In app/config/app.php add the following :

1- The ServiceProvider to the providers array :

BataBoom\Captcha\HCaptchaServiceProvider::class,

2- The class alias to the aliases array :

'HCaptcha' => BataBoom\Captcha\Facades\HCaptcha::class,

3- Publish the config file

php artisan vendor:publish --provider="BataBoom\Captcha\HCaptchaServiceProvider"

Configuration

Add HCaptcha_SECRET and HCaptcha_SITEKEY in .env file :

HCAPTCHA_SECRET=secret-key
HCAPTCHA_SITEKEY=site-key

(You can obtain them from here)

Usage

Init js source

With default options :

 {!! HCaptcha::renderJs() !!}

With language support or onloadCallback option :

 {!! HCaptcha::renderJs('fr', true, 'recaptchaCallback') !!}

Display reCAPTCHA

Default widget :

{!! HCaptcha::display() !!}

With custom attributes (theme, size, callback ...) :

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

{!! HCaptcha::display(['data-theme' => 'dark', 'data-callback' => 'onSubmit', 'data-theme' => 'dark']) !!}

Invisible reCAPTCHA using a submit button:

{!! HCaptcha::displaySubmit('my-form-id', 'submit now!', ['data-theme' => 'dark']) !!}

Notice that the id of the form is required in this method to let the autogenerated callback submit the form on a successful captcha verification.

Validation

Add 'h-captcha-response' => 'required|captcha' to rules array :

$validate = Validator::make(Input::all(), [
    'h-captcha-response' => 'required|captcha'
]);

Custom Validation Message

Add the following values to the custom array in the validation language file :

'custom' => [
    'h-captcha-response' => [
        'required' => 'Please verify that you are not a robot.',
        'captcha' => 'Captcha error! try again later or contact site admin.',
    ],
],

Then check for captcha errors in the Form :

@if ($errors->has('h-captcha-response'))
    <span class="help-block">
        <strong>{{ $errors->first('h-captcha-response') }}</strong>
    </span>
@endif

Testing

When using the Laravel Testing functionality, you will need to mock out the response for the captcha form element.

So for any form tests involving the captcha, you can do this by mocking the facade behavior:

// prevent validation error on captcha
HCaptcha::shouldReceive('verifyResponse')
    ->once()
    ->andReturn(true);

// provide hidden input for your 'required' validation
HCaptcha::shouldReceive('display')
    ->zeroOrMoreTimes()
    ->andReturn('<input type="hidden" name="h-captcha-response" value="1" />');

You can then test the remainder of your form as normal.

When using HTTP tests you can add the h-captcha-response to the request body for the 'required' validation:

// prevent validation error on captcha
HCaptcha::shouldReceive('verifyResponse')
    ->once()
    ->andReturn(true);

// POST request, with request body including h-captcha-response
$response = $this->json('POST', '/register', [
    'h-captcha-response' => '1',
    'name' => 'John',
    'email' => '[e-mail]',
    'password' => '123456',
    'password_confirmation' => '123456',
]);

Without Laravel

Checkout example below:

<?php

require_once "vendor/autoload.php";

$secret  = 'CAPTCHA-SECRET';
$sitekey = 'CAPTCHA-SITEKEY';
$captcha = new \BataBoom\Captcha\HCaptcha($secret, $sitekey);

if (! empty($_POST)) {
    var_dump($captcha->verifyResponse($_POST['h-captcha-response']));
    exit();
}

?>

<form action="?" method="POST">
    <?php echo $captcha->display(); ?>
    <button type="submit">Submit</button>
</form>

<?php echo $captcha->renderJs(); ?>

hCaptcha Filament Installation -- hCaptcha field for the Filament Forms(V2-V3), works in Admin-Panel and Frontend-Forms.

You can install the package via composer:

composer require bataboom/h-captcha

You may publish the configuration by running:

php artisan vendor:publish --provider="BataBoom\HCaptcha\HCaptchaServiceProvider"

Configuration

Add HCAPTCHA_SECRET and HCAPTCHA_SITEKEY in .env file :

HCAPTCHA_SECRET=secret-key
HCAPTCHA_SITEKEY=site-key

(You can obtain them from here)

Usage

Publish an Example using:

php artisan vendor:publish --tag=hcaptcha-filament-login

Or define it yourself

use BataBoom\Captcha\Forms\Components\HCapthaFilamentField;

// admin panel
    public static function form(Form $form): Form
    {
        return $form->schema([
                    ...
                    HCapthaFilamentField::make('captcha')
                ]);
     }

//forntend-forms 
    public $captcha = ''; // must be initialized 
    protected function getFormSchema(): array
    {
        return [
            ....
             HCapthaFilamentField::make('captcha')
        ];
    }

Contribute

https://github.com/BataBoom/h-captcha/pulls https://github.com/anhskohbo/no-captcha/pulls https://github.com/AbanoubNassem/filament-grecaptcha-field/pulls