hcaptcha: hCaptcha datatype
This page is for site owners who want to keep spam out of forms with hCaptcha instead of Google's reCAPTCHA. hcaptcha
adds an hCaptcha datatype, the counterpart of recaptcha. Add the attribute to a content class, and
the form asks the visitor to solve the challenge before it is accepted: in content edit, user registration and
information collection. The hCaptcha project's switching guide is at docs.hcaptcha.com/switch.
The extension is based on an original solution by an earlier contributor and was released as 1.0 on 11 August 2024. No Composer package is needed for hCaptcha (unlike recaptcha).
Set it up
- Activate the extension (
ActiveExtensions[]=hcaptcha). - Sign up at the hCaptcha dashboard and create a site to get your keys.
- Put them in
settings/override/hcaptcha.ini.append.php:
[Keys]
PublicKey=<your site key>
PrivateKey=<your secret key>
[Display]
Theme=white
OverrideLang=
[PublishSettings]
NewObjectsOnly=false- Clear the caches, then add an hCaptcha attribute to the class.
The settings mean the same as in recaptcha: per-host keys as arrays, Theme,
OverrideLang and NewObjectsOnly.
Settings
| File | Block | Key | Default | Meaning |
|---|---|---|---|---|
hcaptcha.ini | Keys | PublicKey, PublicKey[<host>] | placeholder text Enter your Public Key here | The site key; one per host when you run several sites |
hcaptcha.ini | Keys | PrivateKey, PrivateKey[<host>] | placeholder text Enter your Private Key here | The secret key, used on the server only |
hcaptcha.ini | Display | Theme | white | Widget theme |
hcaptcha.ini | Display | OverrideLang | empty | Language code of the widget (en, de, fr, ...); empty works it out from the object language |
hcaptcha.ini | PublishSettings | NewObjectsOnly | false | Check only new objects, not re-edits |
The comments of the shipped INI file still speak of Google's service (it was copied from recaptcha). The code talks
to hCaptcha: the widget script is loaded from js.hcaptcha.com, and the answer is verified on the server at
https://hcaptcha.com/siteverify by classes/hcaptchalib.php. Check:
grep -n hcaptcha.com extension/hcaptcha/classes/hcaptchalib.phpLimit: the form overrides are recaptcha's
design/standard/override/templates/full/feedback_form.tpl and request_form.tpl are the same files as in
recaptcha. They read ezini( 'Keys', 'PublicKey', 'recaptcha.ini' ) and load
Google's recaptcha/api.js, not hCaptcha's. If both extensions are active and you use these form classes, the forms
use the reCAPTCHA settings; the hCaptcha datatype has its own template. Check:
grep -n 'ezini\|google' extension/hcaptcha/design/standard/override/templates/full/feedback_form.tplTo use hCaptcha on those forms, remove the overrides from your design, or override them in your own extension.
What changed
| Version | Date | Change |
|---|---|---|
| 6 August 2024 | The repository began as a copy of recaptcha, so its first commits are recaptcha's. One of them added google/recaptcha to composer.json; the mass update that followed removed that dependency again. composer.json now requires only PHP 7.2 or later and the legacy installer. | |
| 1.0 | 11 August 2024 | The internals were reworked for the hCaptcha API, tested with Exponential 6; funding metadata. |
| 1.1 | 30 September 2026 | The about page names the extension "hCaptcha extension for Exponential"; the description names Exponential. |
| 1.2 | 2 October 2026 | extension.xml, which the extension lacked, was added, and the website in ezinfo.php, so the about page and the upgrade checks show version, license and website. |
Related pages
- recaptcha
- Extension metadata specification
- Chronicle and release notes
- Change ledger
- Behaviour changes of the extensions
- Months: 2024-08, 2026-10 (all extensions)
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.