Jump to content

hCaptcha spam protection for ProcessWire forms


MoritzLost
 Share

Recommended Posts

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.

schwarzdesign - Webdesign und Internet-Agentur aus Köln
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

Screenshots (configuration)

config-1.thumb.png.585279d95f7aca049fec5b3c20a51de3.pngconfig-2.thumb.png.4abb86e183dea2446e73c4dc6a06596e.png

Screenshots (hCaptcha widget)

widget-start.png.ea14e69f2ac333f24d87b638b8ffd665.png

 

 

widget-invalid.thumb.png.4991b1b4445af78a14827df9bfd6970b.png

 

  • Like 26
  • Thanks 2
Link to comment
Share on other sites

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! ?

  • Like 4
Link to comment
Share on other sites

  • 2 months later...

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.

 

 

Screenshot_2020-08-21 Error Undefined class constant 'skipLabelMarkup'.png

Link to comment
Share on other sites

@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 ?

Link to comment
Share on other sites

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!

  • Like 2
Link to comment
Share on other sites

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

 

Link to comment
Share on other sites

  • 2 weeks later...
  • 5 months later...

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!

  • Like 1
Link to comment
Share on other sites

  • 1 month later...

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.

Link to comment
Share on other sites

  • 4 months later...
  • 2 weeks later...

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

  • Like 1
Link to comment
Share on other sites

@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 ^^

Link to comment
Share on other sites

  • 10 months later...

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.

  • Like 1
Link to comment
Share on other sites

@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!

  • Like 1
Link to comment
Share on other sites

@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.

Link to comment
Share on other sites

  • 2 weeks later...

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!

  • Like 3
Link to comment
Share on other sites

  • 5 months later...

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 by MarkE
Link to comment
Share on other sites

@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.

  • Like 1
Link to comment
Share on other sites

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!

  • Like 1
Link to comment
Share on other sites

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.

  • Haha 1
Link to comment
Share on other sites

  • 3 months later...
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 by ngrmm
Update
Link to comment
Share on other sites

@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.

  • Like 1
Link to comment
Share on other sites

@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

 

  • Like 1
Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
 Share

×
×
  • Create New...