Skip to content

Joomla! Plugin

The EU CAPTCHA Joomla! plugin integrates the EU CAPTCHA widget and server-side verification into your Joomla! site with no custom code required. It hooks into Joomla's standard captcha API, so any form that supports a captcha field is automatically protected once the plugin is configured.

  • Version: 1.0.0
  • Requires: Joomla! 4.x / 5.x / 6.x, PHP 8.1+
  • License: GPL-2.0-or-later
  • Download: pkg_eucaptcha.zip

Supported forms

Any Joomla! form that uses the built-in captcha field is supported, including:

  • User Registration
  • User Password Reset
  • Contact Component (com_contact)
  • Any third-party component that renders a standard Joomla! captcha field

We are happy to include support for additional integrations. Please contact support if you need a specific component supported.

Installation

  1. Download pkg_eucaptcha.zip.
  2. In the Joomla! administrator back-end, go to Extensions → Install.
  3. On the Upload Package File tab, upload pkg_eucaptcha.zip. Joomla! installs and enables both plugins automatically.

Configuration

After installation an admin notice appears at the top of every back-end page until the plugin is fully configured. Click Go to Settings in the notice, or navigate to Extensions → Plugins and open the EU Captcha plugin.

Quick Setup

Click Quick Setup at the top of the plugin settings page. A dialog opens loading the EU CAPTCHA registration portal in an embedded iframe. Complete the registration flow inside the dialog — your sitekey and secret are received automatically via postMessage and filled into the form without you copying anything.

Manual credentials

If you already have a sitekey and secret from the dashboard, enter them directly in the plugin settings.

Field Description
Public Sitekey Your public sitekey (UUID format). Safe to display on the frontend.
Secret Your secret key (Base64 format). Stored in the Joomla! database — never sent to the browser.

Save the plugin settings. Once both fields are filled in, the admin notice disappears automatically.

API options

Option Default Description
Check CDN / Proxy Headers On When enabled, the plugin reads the visitor's real IP from HTTP_CLIENT_IP, HTTP_X_FORWARDED_FOR, or HTTP_X_REAL_IP before falling back to REMOTE_ADDR. Enable this if your site sits behind a CDN or load balancer.
Failsafe Off When disabled (default), a network error reaching the verification API causes the form submission to be blocked. When enabled, transport-level errors (timeouts, DNS failures) are treated as a passed verification so submissions go through. Invalid tokens are still rejected regardless of this setting.

Widget styling

Option Default Description
Theme Light Controls the widget colour scheme. Choose Light or Dark.
Height (px) — Optional fixed height in pixels (minimum 48). Leave empty to use the widget default.
Width (px) — Optional fixed width in pixels (minimum 1). Leave empty to use the widget default.

Activating the captcha on your site

Go to System → Global Configuration, open the Site tab, and set Default Captcha to EU Captcha. Save the configuration.

Any component that renders a captcha field will now display the EU CAPTCHA widget. For the built-in contact form, enable the captcha field under Components → Contact → Options → Form tab.

How it works

  1. The plugin registers the EU CAPTCHA provider with Joomla!'s captcha registry via the onCaptchaSetup event.
  2. When a form with a captcha field is rendered, the plugin enqueues https://cdn.eu-captcha.eu/verify.js (with async defer) via the WebAssetManager and outputs <div class="eu-captcha" data-sitekey="..."> inside the form.
  3. On form submission, Joomla! calls the plugin's checkAnswer() method, which reads the token from eu-captcha-response and sends a server-side request to https://api.eu-captcha.eu/v1/verify with the token, visitor IP, and User-Agent.
  4. Submissions are accepted or rejected based on the API response.

Third-party services

Host Purpose
cdn.eu-captcha.eu Loads verify.js on pages with protected forms
api.eu-captcha.eu Server-side token verification on each form submission
app.eu-captcha.eu EU CAPTCHA dashboard loaded in the Quick Setup dialog

EU CAPTCHA sets no cookies and collects no personal data in the browser, making it GDPR-compliant without a cookie banner. Data sent to api.eu-captcha.eu on each verification: sitekey, secret, captcha response token, visitor IP address, visitor User-Agent string. Refer to the EU CAPTCHA Privacy Policy for details on how this data is processed.

Troubleshooting

The widget does not appear on a form

  • Confirm Default Captcha is set to EU Captcha in Global Configuration.
  • Confirm the specific component has its captcha field enabled (e.g. Contact → Options → Form tab).
  • Check that the sitekey is saved correctly (UUID format).
  • Open browser DevTools → Network and verify verify.js loaded without errors.
  • If a Content Security Policy is active, add cdn.eu-captcha.eu to script-src and connect-src.

Form submissions are blocked even for real users

  • Verify the sitekey and secret are correct. An incorrect secret causes the API to return train: true, which the plugin treats as a failure.
  • Check that the sitekey was created for this domain. Each sitekey is tied to the domain specified at creation — create a new sitekey if needed.

Submissions always pass even for empty tokens

  • Confirm the secret is correct. A wrong secret puts the API into bypass mode (train: true) where all submissions appear successful.

The plugin blocks all submissions when your CDN is active

  • Enable Check CDN / Proxy Headers in the plugin settings so the plugin forwards the real visitor IP rather than the CDN's address.

What happens during an EU CAPTCHA outage?

By default the plugin blocks submissions when the API is unreachable (fail closed). Enable Failsafe in the plugin settings to accept submissions during outages (fail open). See the Failsafe option above.