README

Laravel HCaptcha

A package to easily include HCaptcha in Laravel.

This project is originally based on laravel-reCAPTCHA and forked from Scyllaly, who seemingly abandoned the project.

This fork is a near-drop-in replacement for Scyllaly's package, maintaining the same namespace for 4.x and 5.x versions.

Requirements

Need support for Laravel 7 or before? Check the 4.x branch.

Installation

Install the package with Composer:

composer require rvxlab/hcaptcha

Publish the config file:

php artisan vendor:publish --tag="hcaptcha-config"

Optionally publish the translations:

php artisan vendor:publish --tag="hcaptcha-lang"

Optionally publish the views:

php artisan vendor:publish --tag="hcaptcha-views"

Configuration

Add HCAPTCHA_SECRET and HCAPTCHA_SITEKEY in .env file :

HCAPTCHA_SECRET=secret-key
HCAPTCHA_SITEKEY=site-key

You can obtain them from your HCaptcha dashboard.

Usage

Prepare the script

First you need to initialize the script:

{!! HCaptcha::renderJs() !!}
// Or
<x-hcaptcha::script />

You can optionally set the locale and the custom callback function:

{!! HCaptcha::renderJs('nl', true, 'myCallbackFunction') !!}
// Or
<x-hcaptcha::script lang="nl" :has-callback="true" on-load-class="myCallbackFunction" />

You can also use the app locale if you have a multilingual application:

<x-hcaptcha::script use-app-locale />

Render the widget

This package provides support for the regular widget, as well as the invisible captcha.

Initialize the regular widget:

{!! HCaptcha::display() !!}
// Or
<x-hcaptcha::widget />

Any attributes can be passed as an array to the display method or as properties on the Blade component:

{!! HCaptcha::display([ 'class' => 'my-widget', 'data-test' => 'Test' ]) !!}
// Or
<x-hcaptcha::widget class="my-widget" data-test="Test" />

Invisible widget

If you rather want forms to have an invisible widget:

<form id="register-form" method="post" action="{{ route('register') }}">
    <input type="text" name="email" />
    
    <input type="password" name="password" />
    
    {!! HCaptcha::displaySubmit('register-form', 'Submit', [ 'class' => 'btn' ]) !!}
    // Or
    <x-hcaptcha::submit form-identifier="register-form" class="btn">
        Submit
    </x-hcaptcha::submit>
    @csrf
</form>

If you have a custom callback defined for your forms you can define a data-callback attribute:

{!! HCaptcha::displaySubmit('register-form', 'Submit', [ 'class' => 'btn', 'data-callback' => 'userDefinedCallback ]) !!}
// Or
<x-hcaptcha::submit form-identifier="register-form" class="btn" data-callback="userDefinedCallback">
    Submit
</x-hcaptcha::submit>

Validation

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

class RegisterRequest extends \Illuminate\Foundation\Http\FormRequest
{
    public function rules(): array
    {
        return [
            'email' => 'required|email|exists:users,email',
            'password' => 'required',
            'h-captcha-response' => 'required|HCaptcha',
        ];
    }
}

Testing

You can mock the HCaptcha validation by calling the shouldReceive method on the HCaptcha facade:

HCaptcha::shouldReceive('verifyResponse')->once()->andReturnTrue();

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

Or when testing a JSON call:

HCaptcha::shouldReceive('verifyResponse')->once()->andReturnTrue();

$response = $this->json('POST', '/register', [
    'h-captcha-response' => '1',
    'email' => 'john@example.com',
    'password' => '123456',
]);

Upgrading

Check the Upgrade Guide for notes on updating from 4.x to 5.x.

License

This package is licensed under MIT.

rvxlab / hcaptcha

Maintainers

Details