InputfieldHCaptcha by MoritzLost

Adds hCaptcha spam protection to ProcessWire forms.

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.


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';

The module comes with a permission (bypass-hcaptcha) that allows users to bypass hCaptcha verification completely. The widget will be hidden for users with that permission and the server-side verification will not take place.

Warning: As the superuser, you will never see the hCaptcha widget, because the superuser passes all permission checks. Make sure to test the widget in a different browser or a private browser window.


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.

Note for Embed Option D: If you're using Option D: Custom Markup Embed, you have to adjust the generated template. See this comment for details.


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;
});

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.

Latest news

  • ProcessWire Weekly #490
    In the 490th issue of ProcessWire Weekly we'll check out what's new in the latest core version ProcessWire 3.0.229, introduce a brand-new third party module, and more. Read on!
    Weekly.pw / 30 September 2023
  • ProcessWire 3.0.226 new main/master version
    After 8 months in development we are excited to bring you ProcessWire 3.0.226 main/master. This version has a ton of great new features, improvements and optimizations, plus more than 100 issue fixes. This post takes an in-depth look at highlights from this great new version.
    Blog / 25 August 2023
  • Subscribe to weekly ProcessWire news

“We were really happy to build our new portfolio website on ProcessWire! We wanted something that gave us plenty of control on the back-end, without any bloat on the front end - just a nice, easy to access API for all our content that left us free to design and build however we liked.” —Castus, web design agency in Sheffield, UK