module hCaptcha spam protection for ProcessWire forms

[MoritzLost]

This module allows you to integrate hCaptcha bot / spam protection into ProcessWire forms. hCaptcha is a great alternative to Google ReCaptcha, especially if you are in the EU and need to comply with privacy regulations.

The development of this module is sponsored by schwarzdesign.

The module is built as an Inputfield, allowing you to integrate it into any ProcessWire form you want. It's primarily intended for frontend forms and can be added to Form Builder forms for automatic spam protection. There's a step-by-step guide for adding the hCaptcha widget to Form Builder forms in the README, as well as instructions for API usage.

Features

• Inputfield that displays an hCaptcha widget in ProcessWire forms.
• The inputfield verifies the hCaptcha response upon submission, and adds a field error if it is invalid.
• All hCaptcha configuration options for the widget (theme, display size etc) can be changed through the inputfield configuration, as well as programmatically.
• hCaptcha script options can be changed through a hook.
• Error messages can be translated through ProcessWire's site translations.
• hCaptcha secret keys and site-keys can be set for each individual inputfield or globally in your config.php.
• Error codes and failures are logged to help you find configuration errors.

Please check the README for setup instructions.

Links

• Github Repository and documentation
• InputfieldHCaptcha in the module directory

Screenshots (configuration)

Screenshots (hCaptcha widget)

 

 

 

[teppo]

2 hours ago, MoritzLost said:

This module allows you to integrate hCaptcha bot / spam protection into ProcessWire forms. hCaptcha is a great alternative to Google ReCaptcha, especially if you are in the EU and need to comply with privacy regulations.

Literally heard about hCaptcha for the first time earlier today when someone recommended it as a ReCaptcha replacement. Great to have this available as an option! ?

[aComAdi]

Hi Moritz,

We would lek to start working with hCaptcha for our Processwire client sites using Form Builder. Ran into the following issue.

Hiding the field label causes 500 Internal Error. I've attached the the error as a screenshot. The environment is:

• PW 3.0.123
• Formbuilder 0.3.9
• PHP Version 7.3.16

Not a biggie, but might be an issue on some implementations.

 

 

[MoritzLost]

@aComAdi Thanks for letting me know! I'm using a constant there that is only available in ProcessWire 3.0.139 and above. I can certainly fix that!

In the meantime, if it's possible for you you can update ProcessWire to the new master version, which should fix the problem as well. But I'll update the module to work with your ProcessWire version as well, hopefully later today ?

[MoritzLost]

Release 1.0.1 is now live! It fixes the errors on ProcessWire versions below 3.0.139.

Background: The module uses Inputfield::skipLabelMarkup to remove the label markup if the inputfield is configured to not display a label. This constant was introduced in ProcessWire 3.0.139. On older versions, the module now falls back to Inputfield::skipLabelHeader, which renders the label but hides it with CSS (instead of skipping the label markup completely).

@aComAdi Let me know if the release isn't working for you, or if you have any more problems with the module!

[aComAdi]

The error has disappeared, but the actual label is still displaying. ?

https://www.garage-fischer.ch/kontakt/kontakt/

[MoritzLost]

6 minutes ago, aComAdi said:

The error has disappeared, but the actual label is still displaying. ?

Hm, that's curious. The way it's supposed to work is that the label gets the class InputfieldHeaderHidden, and the span inside the label is then hidden with CSS. In your form the class is generated correctly, but for some reason the corresponding CSS is missing. In my test installation, the CSS code that hides the label comes from /site/modules/FormBuilder/FormBuilder.css, which isn't included on your site. Maybe you're missing one of the core CSS files in your FormBuilder output?

If you can't or don't want to include this CSS file, you could just add the required rule manually to any of your stylesheets. This should do the trick:

.InputfieldForm .Inputfield:not(.InputfieldStateCollapsed) > .InputfieldHeaderHidden > span {
  display: none;
}

 

[aComAdi]

Sorry for late replay. It's solved now.

[MoritzLost]

InputfieldHCaptcha 1.0.2

I've just released a bugfix update to this module which should fix an issue with malformed API requests when using cURL. This should help if you had the following problems with the module:

• Captcha validation always fails with error codes missing-input-response and/or missing-input-secret (error codes are logged to the hcaptcha log file).
• General network / API request errors.

The new version 1.0.2 uses cURL only if it's supported on your system and the ProcessWire version is 3.0.167 or above (see this post for an explanation). Otherwise, it uses fopen with a fallback to sockets. If you're having trouble with the updated module, please let me know which ProcessWire version you're running and if your system supports cURL so I can try to replicate the problem.

Update: v1.0.2 contained a small error that prevented fallback to socket if fopen is unavailable (on systems that don't support cURL or below ProcessWire 3.0.167). Fix is live as version 1.0.3

Next steps

I'm planning to implement a couple of additional options for this module soon. In particular:

• An optional permission allowing users to bypass captcha validation.
• A global 'kill-switch' for the module – i.e. a option in the module config or a $config value that disables hCaptcha validation globally, passing all requests.

Let me know if those features would be useful to you or if you have other suggestions to improve this module!

[MoritzLost]

Quick tip: Displaying hCaptcha in the correct language

By default, hCaptcha displays its interface in the visitor's browser language, which means it may differ from the current language of your site. You might want to change that to always use your site's language, or the current language if you have a multi-language site. You can use the hook InputfieldHCaptcha::getScriptOptions to adjust the language of the hCaptcha interface dynamically. Here's a  snippet with a couple of options for setting the language:

// site/ready.php
wire()->addHookAfter('InputfieldHCaptcha::getScriptOptions', function (HookEvent $e) {
    $options = $e->return;

    // option 1: for single-language sites, you can just hardcode a specific language
    $options['hl'] = 'de';

    // option 2: for multi-language sites, you can use the translation api
    $options['hl'] = _x('de', 'hCaptcha Language');

    // option 3: you can also add a custom field to your language template to hold the language code
    $options['hl'] = wire('user')->language->language_code;

    $e->return = $options;
});

For option 2, make sure to add a translation for the language code in every language.

For option 3, first set $config->advanced = true in your config.php so you can edit the language template. You have to create the language_code field yourself and add it to the template, then set the language code in each of your languages.

For all options, make sure to use the correct language code as listed here.

[MoritzLost]

InputfieldHCaptcha 1.0.4

I just pushed an update that fixes a typo in the default error message for a missing captcha response. If you're using this module and have added translations for the module's messages, make sure to update them to match the new source string!

More information in the changelog

[DV-JF]

Hey @MoritzLost,

short question: Following scenario:

I'm using FormBuilder with the option "Submit to another URL (bypassing Form Builder processing)" (with "Form Submit Method" POST) to process the input of the form on a dedicated page with a separate template.

Is it possible to validate the hCaptcha field on this dedicated page to process only if hCaptcha field is valid.

I'm trying to avoid a scenario where visitors (or rather bots) visit the "processing" URL and causing high traffic.

Any thoughts are welcome... Many greets Jens alias DV-JF

[MoritzLost]

@DV-JF Hm, good question. The module builds on the base Inputfield class provided by ProcessWire, so it's built around being used inside a ProcessWire form context. I'm not actually sure how to execute the input validation on itself. That said, all you need to do is create an instance of the module and then execute the ___processInput method. This method expects a WireInputData object that you can get from $input->post(). The method will validate the hCaptcha response and add errors to the module instance, if any. So something like this *might* work:

$InputfieldHCaptcha = $modules->get('InputfieldHCaptcha');
$WireInputData = $input->post();
$InputfieldHcaptcha->processInput($WireInputData);
$errors = $InputfieldHCaptcha->getErrors();
$hasErrors = !empty($errors);

But I can't test this code right now and I haven't done something like this before, so I'm not sure if it's the right approach. If it doesn't, maybe ask in the FormBuilder support area. Ryan knows way more about this ^^

[Pete]

This module is great - thank you.

Quote

An optional permission allowing users to bypass captcha validation.

I'd love to see the addition you mentioned above though as there are some forms where I only want to display hCaptcha to guest users since logged-in users on the site I'm working on are already validated by this point. I guess the permission should just hide/not render the form and skip it during form validation but not sure how easy that is.

I guess the way to do that in the meantime would be via hooks, so using your example below from the docs, but only target visitors who aren't logged in and render it for just those visitors:

<?php // 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;
});

I'll give that a go and see how I go.

[MoritzLost]

@Pete Glad the module is working for you!

Yeah, the bypass permission will be a useful addition. I agree that this permission should hide the input field completely. Not sure if I can prevent the input field wrapper markup from showing up altogether, I'll have to give that a try.

One thing I'm concerned about is that superusers won't see the hCaptcha input at all, so some site admins might think the module is broken if they add the inputfield to a form and don't see it in the frontend (unless they test in a private browser window). Maybe instead of hiding the inputfield, it should display a static message? Something like The captcha is hidden because you're already a verified user. Or is that too confusing for users?

Anyway, I'll try to build this in a feature branch this week for testing purposes!

[MoritzLost]

@Pete I've added the permission check in a separate branch, would you mind testing it?
https://github.com/MoritzLost/InputfieldHCaptcha/tree/bypass-permission

For now the permission hides the widget completely, I think this makes the most sense. Server-side verification is skipped as well – for Form Builder entries, the generated field value should indicate this. Let me know if this works for you or if you're encountering any problems! Might have to re-install the module so that the new permission gets added, or add it manually.

[MoritzLost]

InputfieldHCaptcha 2.0.0

Version 2.0.0 of InputfieldHCaptcha is now available.

• Feature: Add a permission to bypass hCaptcha completely. See the documentation for details.
  • If you're upgrading from an earlier version of the module, you may need to add the permission manually. Go to Access -> Permissions -> Add new and add a permission with the name bypass-hcaptcha.
• Breaking change: After updating, superuser accounts won't see the hCaptcha widget anymore and be allowed to bypass it everywhere. This is a potential breaking change, but mostly relevant to know for development and debugging purposes – make sure to test your forms in a private browser window.

---------------------------

@Pete I've gone ahead and released the bypass permission feature in version 2.0.0. Let me know if anything is not working right for you!

[Pete]

Thank you - I had Covid last week so haven't had time to look at this yet but looking forward to testing it out this week.

[MarkE]

Hi @MoritzLost. I just installed this and added a field to my form in Formbuilder as per instructions with secret and site keys from hCaptcha, but nothing shows in the form. Any idea what might be wrong?

UPDATE

It seems to be working now. Maybe it just takes time for a new site to be recognised. 

Edited December 22, 2022 by MarkE

[MoritzLost]

@MarkEWere you viewing the form while logged in as superuser? Since version 2.0.0, the module comes with a permission to bypass hCaptcha. This permission also hides the widget from the frontend. The superuser skips all permission checks, so they never see the widget. Make sure to test the form in a private browser window where you're not logged in.

[MarkE]

On 12/22/2022 at 9:31 AM, MoritzLost said:

Were you viewing the form while logged in as superuser?

Yes. I realised after my last update that was probably the cause and that there is no delay in setting up. Maybe a small update to the module documentation? Anyway a really helpful module and very easy to install in Formbuilder. Thanks a lot!

[MoritzLost]

5 hours ago, MarkE said:

Yes. I realised after my last update that was probably the cause and that there is no delay in setting up. Maybe a small update to the module documentation? Anyway a really helpful module and very easy to install in Formbuilder. Thanks a lot!

It's right here 🙂

Quote

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.

Anyway, glad the module is working for you! Let me know if you run into any more issues.

[ngrmm]

On 12/22/2022 at 1:27 AM, MarkE said:

Hi @MoritzLost. I just installed this and added a field to my form in Formbuilder as per instructions with secret and site keys from hCaptcha, but nothing shows in the form. Any idea what might be wrong?

UPDATE

It seems to be working now. Maybe it just takes time for a new site to be recognised. 

@MoritzLost having the same problem. Nothing shows up.
Using PW 3.0.200 FB 5.3 and latest hCaptcha-Inputfield.
I added it to my form as per instructions with secret and site keys from hCaptcha.

I tried it in another Browser as a guest-user. Still nothing to see.
I'm using the custom markup embed option (D). So when I generate the markup via formbuilder there is no sign of the captcha field in the markup.

echo $forms->embed('form_name');

But also if I use the B option

echo $forms->render('form_name');

still nothing.

Any Idea what I'm doing wrong?

UPDATE:

It looks like it's not compatible with the option D of embedding forms. As long there a file with same name as the form here: /site/templates/FormBuilder/…
the captcha is not there. Is there a way to add it manually?

Edited March 30 by ngrmm
Update

[MoritzLost]

@ngrmm Not sure what's going wrong there, but some ideas:

• Are you sure you're not logged in, and your guest user doesn't have the permission to bypass the captcha?
• Maybe the form was cached while you viewed it as the admin, and the guest user is seeing the cached output without the captcha input?
• What happens if you submit the form (as the guest user) while the captcha is not visible - do you get an error or does the submission succeed?
• Depending on selected strength and hCaptcha subscription (if any), the script may not always show a visible captcha if it's confident you're a real user. Try reloading the page with the DevTools open - is the hCaptcha script being loaded? If so, maybe it's just using a hidden captcha. If not, the inputfield is probably not included at all, then it's probably an issue with your template.

Can you post your form builder template? Depending on how your template is built, you might need to include the hCaptcha inputfield manually.

[ngrmm]

@MoritzLost

Are you sure you're not logged in, and your guest user doesn't have the permission to bypass the captcha?
yes

Maybe the form was cached while you viewed it as the admin, and the guest user is seeing the cached output without the captcha input?
I guess that is not the case

What happens if you submit the form (as the guest user) while the captcha is not visible - do you get an error or does the submission succeed?
It gives me this Error:
[fieldname] - Captcha response is missing. Please fill out the captcha and try again.

Depending on selected strength and hCaptcha subscription (if any), the script may not always show a visible captcha if it's confident you're a real user. Try reloading the page with the DevTools open - is the hCaptcha script being loaded?
I was testing it always with devtools open with reset-cache-mode active

If so, maybe it's just using a hidden captcha. If not, the inputfield is probably not included at all, then it's probably an issue with your template.
Can you post your form builder template? Depending on how your template is built, you might need to include the hCaptcha inputfield manually.
Maybe you could try it yourself on a Test-PW-Installation. Just generate a FormBuilder form with simple text fields and a hcaptcha field and try out embed-option  D. Generate a copy markup of the form via FormBuilder. PW generates a copy here: /site/assets/cache/FormBuilder/
After copying it to /site/templates/FormBuilder/ the hcaptcha-field won't  show up