hCaptcha package for Laravel

A package specifically designed to include hCaptcha directly into Laravel.

Installation

To install, use Composer:

composer require teampanfu/laravel-hcaptcha

Manual setup

As of Laravel 5.5, packages are discovered automatically via package discovery. So if you are using a newer version, you can skip these steps.

Add the following to your config/app.php:

'providers' => [
    ...

    /*
     * Package Service Providers...
     */
    Panfu\Laravel\HCaptcha\HCaptchaServiceProvider::class,

    ...
],

'aliases' => [
    ...
    'HCaptcha' => Panfu\Laravel\HCaptcha\Facades\HCaptcha::class,
    ...
],

Then publish the configuration file:

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

Configuration

Add your website in the hCaptcha dashboard to get a site key and secret key.

When you have done that, add the keys to your .env file:

HCAPTCHA_SITEKEY=10000000-ffff-ffff-ffff-000000000001
HCAPTCHA_SECRET=0x0000000000000000000000000000000000000000

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

Usage

Display

To display the widget:

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

You can also set custom attributes on the widget:

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

Or extend the class:

{!! HCaptcha::display([
    'class' => $errors->has('email') ? 'is-invalid' : '',
]) !!}

Script

To load the hCaptcha javascript resource:

{!! HCaptcha::script() !!}

You can also set the query parameters:

{!! HCaptcha::script($locale, $render, $onload, $recaptchacompat) !!}

Validation

To validate the hCaptcha response, use the hcaptcha rule:

$request->validate([
    'h-captcha-response' => ['hcaptcha'],
]);

You can leave out the required rule, because it is already checked internally.

Custom validation message

Add the following values to your validation.php in the language folder:

'custom' => [
    'h-captcha-response' => [
        'hcaptcha' => 'Please verify that you are human.',
    ]
],

Invisible Captcha

You can also use an invisible captcha where the user will only be presented with a hCaptcha challenge if that user meets challenge criteria.

The easiest way is to bind a button to hCaptcha:

{!! HCaptcha::displayButton() !!}

This will generate a button with an h-captcha class and the site key. But you still need a callback for the button:

<script>
    function onSubmit(token) {
        document.getElementById('my-form').submit();
    }
</script>

By default, onSubmit is specified as callback, but you can easily change this (along with the text of the button):

{!! HCaptcha::displayButton('Submit', ['data-callback' => 'myCustomCallback']) !!}

You can also set other custom attributes, including class.

Use without Laravel

The package is designed so that it can be used without Laravel. Here is an example of how it works:

<?php

require_once 'vendor/autoload.php';

use Panfu\Laravel\HCaptcha\HCaptcha;

$sitekey = '10000000-ffff-ffff-ffff-000000000001';
$secret = '0x0000000000000000000000000000000000000000';
$hCaptcha = new HCaptcha($sitekey, $secret);

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

?>

<form method="POST">
    <?= $hCaptcha->display() ?>
    <button type="submit">Submit</button>
</form>

<?= $hCaptcha->script() ?>

Testing

$ ./vendor/bin/phpunit

Contribute

If you find a bug or have a suggestion for a feature, feel free to create a new issue or open a pull request.

We are happy about every contribution!

License

This package is open-source software licensed under the MIT License.