InputfieldHCaptcha by MoritzLost

Adds hCaptcha spam protection to ProcessWire forms.

hCaptcha Inputfield for ProcessWire

This is an inputfield module for ProcessWire that displays an hCaptcha bot protection widget and verifies the response. It is primarily built for use with Form Builder, but can be used programmatically and inserted into any ProcessWire form, including the page edit forms.

The development of this module is sponsored by schwarzdesign.

Prerequisites


You need an hCaptcha account to create your API keys. You need two keys:

  1. Your account-wide Secret Key that is used server-side for API requests.
  2. A Site Key that is used in the hCaptcha widget to differentiate between sites.

You can configure those keys for each individual hCaptcha inputfield, but you can also set them globally in your config.php:

// replace with your actual keys
$config->hCaptchaSecretKey = '0x0000000000000000000000000000000000000000';
$config->hCaptchaSiteKey = '10000000-ffff-ffff-ffff-000000000001';

Setup for Form Builder


The most common use case for this module is as a bot / spam protection in frontend forms built with Form Builder.

  1. After you have installed the module, go to Modules -> Configure -> FormBuilder and add hCaptcha under Allowed Input Types.
  2. Now go to edit the Form Builder form you want to add an hCaptcha widget to (Setup -> Forms -> Edit -> [your form]). Add a new field of type hCaptcha.
  3. After adding the field, go to the Details tab to configure it. The field requires your secret key and a site key, unless you have added them to your config.php.
  4. The other options mostly reflect the hCaptcha Container Configuration, so you can change the look and feel and configure JavaScript callbacks. You can also hide the field label above the hCaptcha field.
  5. Now fill out the form in the frontend and try submitting it without filling out the captcha. You should see an error message asking you to fill out the captcha and try again. You can change or translate the error messages used by the module through ProcessWire's site translation system.
  6. If the verification is failing server-side even though you completed the captcha challenge, check the log file (Setup -> Logs -> hcaptcha). The module logs the error codes returned by the API when validation fails.

API usage


You can create and configure hCaptcha inputfields programmatically:

$hCaptcha = wire('modules')->get('InputfieldHCaptcha');

// the secret key & site key are required unless you have added them to your config.php
$hCaptcha->set('secretkey', '0x0000000000000000000000000000000000000000');
$hCaptcha->set('sitekey', '10000000-ffff-ffff-ffff-000000000001');

// the label is optional
$hCaptcha->set('label', __('Spam Protection'));
// hide the label (default = false)
$hCaptcha->set('hideLabel', 1);
// include the IP address in the API request to hCaptcha? (default = false)
$hCaptcha->set('includeIp', 1);

// change the display theme (default = light)
$hCaptcha->set('theme', 'dark'); // light | dark
// change the display size (default = normal)
$hCaptcha->set('size', 'compact'); // normal | compact | invisible
// set the tabindex (default = 0)
$hCaptcha->set('tabindex', 5); // -1, 0 or any positive integer
// hCaptcha callback (default = empty)
$hCaptcha->set('data-callback', 'yourCustomCallback'); // JavaScript function name
// hCaptcha expired callback (default = empty)
$hCaptcha->set('data-expired-callback', 'yourExpiredCallback'); // JavaScript function name
// hCaptcha error callback (default = empty)
$hCaptcha->set('data-error-callback', 'yourErrorCallback'); // JavaScript function name

Use hooks to add the hCaptcha inputfield to specific ProcessWire forms, like the page edit form:

// site/init.php
wire()->addHookAfter('ProcessPageEdit::buildForm', function (HookEvent $event) {
    $form = $event->return;
    $submitButton = $form->getChildByName('submit_save');
    if ($submitButton) {
        $hCaptcha = $event->wire('modules')->get('InputfieldHCaptcha');
        $hCaptcha->set('label', __('Spam Protection'));
        // ... configuration goes here
        $form->insertBefore($hCaptcha, $submitButton);
    }
    $event->return = $form;
});

Script options


The hCaptcha JavaScript library is included only once even if you have multiple hCaptcha inputfields on the same page. It has some configuration options as well, see hCaptcha Configuration. You can modify those options through a hook:

// site/init.php
wire()->addHookAfter('InputfieldHCaptcha::getScriptOptions', function (HookEvent $e) {
    $e->return = [
        // callback after the hCaptcha script has loaded (default = empty)
        'onload' => 'myCustomCallback',
        // render the widget automatically or manually? (default = onload)
        'render' => 'explicit', // onload | explicit
        // force a specific language for the hCaptcha widget (default = auto-detected browser language)
        'hl' => 'de', // @see https://docs.hcaptcha.com/languages
    ];
});

Install and use modules at your own risk. Always have a site and database backup before installing new modules.

Twitter updates

  • ProcessWire 3.0.182 core updates– More
    23 July 2021
  • ProcessWire 3.0.181 has fixes and improvements as usual, but the biggest addition is a nice pull request for multi-language module translations, plus major updates to our Helloworld and ProcessHello demonstration modules. This post covers it all— More
    2 July 2021
  • ProcessWire 3.0.180 core updates– More
    18 June 2021

Latest news

  • ProcessWire Weekly #376
    In the 376th issue of ProcessWire Weekly we'll cover the latest core updates, two new third party modules for ProcessWire, and more. Read on!
    Weekly.pw / 24 July 2021
  • ProcessWire 3.0.181 core updates + “Hello World”
    ProcessWire 3.0.181 has fixes and improvements as usual, but the biggest addition is a nice pull request from LostKobrakai, plus major updates to our Helloworld and ProcessHello demonstration modules. This post covers it all.
    Blog / 2 July 2021
  • Subscribe to weekly ProcessWire news

“ProcessWire is like a breath of fresh air. So powerful yet simple to build with and customise, and web editors love it too.” —Margaret Chatwin, Web developer