Skip to content

TYPO3 Extension

The EU CAPTCHA TYPO3 extension integrates the EU CAPTCHA widget and server-side verification into your TYPO3 site. It protects frontend login forms (EXT:felogin), EXT:form submissions, and the TYPO3 backend login with no custom code required.

  • Version: 1.0.0
  • Requires: TYPO3 14.0+, PHP 8.2+
  • License: GPL-2.0-or-later
  • Download: eu_captcha.zip

Supported forms

Form Extension required
Frontend login EXT:felogin
EXT:form submissions EXT:form
Backend login —

We are happy to include support for more form types. Please contact support if you need additional destinations covered.

Installation

  1. Download eu_captcha.zip.
  2. In the TYPO3 backend, go to Admin Tools → Extension Manager → Upload Extension and upload the zip file, or extract the eu_captcha folder to typo3conf/ext/ manually.
  3. Activate the extension in the Extension Manager.

TypoScript setup

The extension TypoScript must be included in your site's frontend template so that verify.js is loaded and the EXT:felogin template override takes effect.

Modern approach (TYPO3 12+): Add to your site's TypoScript setup file (e.g. typo3conf/sites/yoursite/setup.typoscript):

@import 'EXT:eu_captcha/Configuration/TypoScript/setup.typoscript'

Classic approach: In the backend, go to Web → Template, select your root page, open the template record, go to the Includes tab, and add eu_captcha to Include static (from extensions).

Configuration

Go to System → EU-Captcha in the TYPO3 backend (admin access required).

Quick Setup

Click Quick Setup on the settings page. A modal opens loading the EU CAPTCHA dashboard in an embedded iframe. Complete the registration flow inside the modal — the extension receives your sitekey and secret automatically via postMessage and saves them without you copying anything.

Manual credentials

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

Field Description
Sitekey Your public sitekey (UUID format). Safe to display on the frontend.
Secret Your secret key (Base64 format). Stored in TYPO3 extension configuration — never sent to the browser.

Protected destinations

Enable the form types you want to protect. The widget is injected and server-side verification is enforced only for the destinations you enable.

Destination Setting key Description
Frontend login enableFelogin Protects the EXT:felogin login form. Requires the TypoScript setup to be included.
EXT:form enableForm Protects EXT:form submissions when the EuCaptcha finisher is added to a form definition.

Backend login is always protected when the sitekey and secret are saved — there is no separate toggle. The captcha widget appears automatically on the TYPO3 backend login page.

API options

Option Default Description
Check CDN / Proxy Headers On When enabled, the extension 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.

Save & Test

Use the Save & Test button to save your credentials and immediately run a live API call to verify that the sitekey and secret are correct.

How it works

  1. The extension adds https://cdn.eu-captcha.eu/verify.js (with async defer) to the page footer via TypoScript on all frontend pages.
  2. The EXT:felogin template override injects <div class="eu-captcha" data-sitekey="..."> into the login form. EXT:form inserts the widget via the EuCaptcha finisher.
  3. On form submission, a PSR-15 middleware reads eu-captcha-response from the POST body 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. On failure the visitor is redirected back to the form page with eu_captcha_error=1, and an error message is displayed near the widget.
  5. The backend login is protected by a separate middleware that runs before authentication and redirects failed attempts back to the login page.

Custom integration

WidgetViewHelper

Use the eucaptcha:widget ViewHelper to render the EU CAPTCHA widget in any Fluid template without adding a raw <div> manually.

{namespace eucaptcha=Myra\EuCaptcha\ViewHelpers}

<eucaptcha:widget />

The ViewHelper renders the widget <div> and an inline <script> tag for verify.js. If verify.js is already loaded by TypoScript (the normal case when the TypoScript setup is included), suppress the extra script tag:

<eucaptcha:widget includeScript="false" />

Optional arguments override the values from the extension settings:

Argument Type Description
sitekey string Overrides the configured sitekey.
theme string light or dark. Falls back to the configured theme.
height int Widget height in pixels (minimum 48).
width int Widget width in pixels.
includeScript bool Whether to render the verify.js <script> tag inline. Default: true.

EuCaptcha finisher (EXT:form)

To protect an EXT:form, add the EuCaptcha finisher as the first finisher in the form definition. Subsequent finishers (e.g. EmailToReceiver, database saves) are only executed when the captcha passes. On failure, all remaining finishers are cancelled and the form is re-displayed with an error message.

Via the Form Editor: Open your form in the Form Editor backend module, go to the Finishers section, and add EU-Captcha Verify as the first finisher.

Via YAML form definition:

finishers:
  - identifier: EuCaptcha
  - identifier: EmailToReceiver
    options:
      subject: 'New submission'
      recipientAddress: 'you@example.com'
      recipientName: 'You'
      senderAddress: '{email}'
      senderName: '{name}'

The EuCaptcha finisher requires no additional options. Make sure enableForm is enabled in the extension settings and that the TypoScript setup is included so verify.js is loaded on pages containing the form.

Third-party services

The extension communicates with the following external hosts:

Host Purpose
cdn.eu-captcha.eu Loads verify.js on frontend pages and the backend login page
api.eu-captcha.eu Server-side token verification on each form submission
app.eu-captcha.eu EU CAPTCHA dashboard loaded in the Quick Setup iframe

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. The extension ships with a ContentSecurityPolicies.php file that automatically extends the TYPO3 14 CSP for both frontend and backend scopes — no manual CSP configuration is needed. Refer to the EU CAPTCHA Privacy Policy for details on how this data is processed.

Troubleshooting

The widget does not appear on the felogin form

  • Confirm enableFelogin is ticked and that you clicked Save.
  • Verify the TypoScript setup is included (see TypoScript setup). Without it, verify.js is not loaded and the felogin template override is not applied.
  • Open browser DevTools → Network and verify verify.js loaded without errors.

The widget does not appear on the backend login page

  • Check that the sitekey and secret are both saved correctly. The backend widget is only rendered when the extension is configured.
  • If you use a custom Content Security Policy not managed by TYPO3's built-in CSP API, add cdn.eu-captcha.eu to script-src.

Form submissions are blocked even for real users

  • Verify the sitekey and secret are correct using Save & Test.
  • 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 extension blocks all submissions when your CDN is active

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

EXT:form: the captcha widget does not appear in the form

  • Confirm the EuCaptcha finisher is listed in your form definition and that the form is in the standard prototype.
  • Make sure the TypoScript setup is included so verify.js is loaded on the page containing the form.

What happens during an EU CAPTCHA outage?

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