mhinspeya/mhinspeya-captcha-hyva

Magento 2 CAPTCHA integration module for preventing spam and bots, compatible with Hyvä themes.

1.0.2 2026-07-22 14:14 UTC

Requires

• mhinspeya/backend-mod: ^1.0

Suggests

• mhinspeya/backend-mod: Support Configuration

OSL-3.0

• MHinspeya

• magento
• magento 2
• MHinspeya

Published on Packagist.org on 2026-07-22 14:15 UTC

README

Image-based CAPTCHA for Magento 2 with Hyvä Themes (Alpine.js). Visitors must select the upright image before submitting protected forms. Challenges are generated server-side, verified over AJAX, and enforced again on form POST.

Module name	MHinspeya_Captcha
Composer package	mhinspeya/mhinspeya-captcha-hyva
Version	1.0.1
License	OSL-3.0
Homepage	https://inspeya.com

Features

• Hyvä-native UI — Alpine.js widget; no RequireJS / Knockout
• Click-the-upright-image challenge (shuffled images, random hashes)
• Protected forms
  • Customer registration (customer/account/create)
  • Contact form (contact)
• Server-side enforcement on registration and contact POST (not only frontend)
• Challenge storage in Magento cache (token → correct hash, TTL 15 minutes)
• Admin toggle — enable/disable per store scope
• REST endpoint — anonymous GET /V1/mhinspeya/captcha
• Translations — de_DE, de_AT, de_CH

Requirements

• Magento Open Source / Adobe Commerce 2.4.x (developed against 2.4.8, PHP 8.x)
• Hyvä Theme (Alpine.js on the storefront)
• Composer dependency: mhinspeya/backend-mod ^1.0 (admin/config support)
• Magento modules: Magento_Customer (declared in sequence); contact protection also uses Magento_Contact

How it works

1. Page loads → Alpine captcha widget calls GET captcha/captcha/generate
2. Server returns { token, images[{ hash, base64, randomName }] }
3. Correct hash is stored in cache under the token (not sent to the browser as “correct”)
4. User clicks an image → POST captcha/captcha/verify { token, hash }
5. On success, hidden fields captcha_token + captcha_hash are set
6. Form submit → CreatePost / Contact Post re-validates token+hash via CaptchaStorage

Frontend routes (frontName: captcha)

Path	Purpose
captcha/captcha/generate	Create challenge (JSON)
captcha/captcha/verify	Validate selected hash (JSON)
captcha/captcha/validate	Legacy/alternate base64 session validation (JSON)

Web API

Method	URL	Service
GET	/rest/V1/mhinspeya/captcha	MHinspeya\Captcha\Api\CaptchaInterface::getCaptcha

Returns image src URLs (dynamic Magento static URLs) and isIncorrect flags for API consumers.

Installation

Composer (recommended)

composer require mhinspeya/mhinspeya-captcha-hyva
php bin/magento module:enable MHinspeya_Captcha
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

In production mode, also deploy static content:

php bin/magento setup:static-content:deploy

Manual (app/code)

1. Copy the module to app/code/MHinspeya/Captcha
2. Ensure mhinspeya/backend-mod is installed
3. Run:

php bin/magento module:enable MHinspeya_Captcha
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

Configuration

Admin path: Stores → Configuration → Hyvä Captcha Settings → Captcha Configuration → General Settings

Setting	Path	Description
Enable Captcha	mhinspeya_captcha/general/enabled	Yes/No — show widget and require verification when enabled

ACL resource for the config section: MHinspeya_Captcha::config.

After changing config, flush cache:

php bin/magento cache:flush

Where the CAPTCHA appears

Page	Layout	Template
Customer create account	customer_account_create.xml	newcaptcha.phtml
Contact us	contact_index_index.xml	newcaptcha.phtml

The widget is injected into form.additional.info and renders only when Enable Captcha is Yes.

Hidden fields posted with the form:

• captcha_token
• captcha_hash

Module structure (high level)

Api/                  Web API service contract
Block/                Storefront block (enabled / timeout helpers)
Controller/
  Account/            Preference: customer registration POST + captcha gate
  Captcha/            generate / verify / validate endpoints
  Index/              Preference: contact form POST + captcha gate
Helper/               Scope config (enabled, timeout paths)
Model/
  Captcha.php         REST getCaptcha() implementation
  CaptchaStorage.php  Cache storage for challenges
  Session/            Session helper for legacy validate flow
view/frontend/        Layouts, Alpine template, captcha images
etc/                  DI preferences, routes, webapi, system.xml, ACL
i18n/                 German locale CSVs

Important preferences (etc/frontend/di.xml)

• Magento\Customer\Controller\Account\CreatePost → MHinspeya\Captcha\Controller\Account\CreatePost
• Magento\Contact\Controller\Index\Post → MHinspeya\Captcha\Controller\Index\Post

Challenge cache

Item	Value
Key pattern	mhinspeya_captcha_{token}
Tag	MHINSPEYA_CAPTCHA
TTL	900 seconds (15 minutes)
Stored data	{ "correctHash": "..." }

Verification uses timing-safe hash_equals().

Compatibility notes

• Designed for Hyvä (Alpine alpine:init + Alpine.data('captcha')). Luma/Blank are not the primary target.
• Registration and contact controllers are preferences (full class overrides). Test after Magento upgrades that change those core constructors.
• Image assets live under view/frontend/web/images/ (JPEG challenge set for generate; PNG set for REST getCaptcha).

Troubleshooting

Issue	What to check
CAPTCHA not visible	Config Enable Captcha = Yes; Hyvä theme active; cache flushed; block in layout
Always fails verification	captcha_token / captcha_hash posted; cache backend working; TTL not expired
Generate returns “Image files are missing”	Deploy/static content; files under view/frontend/web/images/captcha1.jpg … captcha6.jpg
DI compile errors after upgrade	Core CreatePost / Contact Post constructor changes — update module preferences
Admin config missing	mhinspeya/backend-mod installed; ACL MHinspeya_Captcha::config

Uninstall

php bin/magento module:disable MHinspeya_Captcha
# Composer:
composer remove mhinspeya/mhinspeya-captcha-hyva
# Or remove app/code/MHinspeya/Captcha
php bin/magento setup:upgrade
php bin/magento cache:flush

Support

• Vendor: MHinspeya
• Website: https://inspeya.com