CaptchaFox Extension for TYPO3

You can protect the forms of your TYPO3 website using the official CaptchaFox Extension. It adds a “CaptchaFox” element to the TYPO3 form framework (EXT:form) and verifies the answer on the server before the form is accepted.

Requirements

TYPO3	Extension version	PHP
14.3 or newer	14.x	8.2 or newer
12.4 LTS and 13.4 LTS	12.x	8.1 or newer
10.4.11+ and 11.5.7+	10.x (security fixes only)	7.4 or newer

Installation

Install the extension with Composer or from the TYPO3 Extension Repository. Composer selects the version that matches your TYPO3 version:
```
composer require captchafox/captchafox-typo3
```
In the CaptchaFox Portal, copy the site key of your website (Sites) and the secret key of your organization (Organization Settings).
Enter both keys in Admin Tools > Settings > Extension Configuration > captchafox_official (TYPO3 14: System > Settings > Extension Configuration).
Add the element CaptchaFox to your forms in the form editor.
Everything is set. Your forms are now protected!

No static template needs to be included. Up to versions 10.0.2 and 12.0.1, the static template “CaptchaFox-Typo3” was required.

Configuration

Option	Default	Description
`site_key`	public test key	Site key from the CaptchaFox Portal (Sites)
`secret_key`	public test key	Secret key of your CaptchaFox organization
`lang`	empty (10.x: `de`)	Widget language code, e.g. `de`. Empty: the language of the current site language (10.x: the browser language)
`apiUnavailable`	`allow`	If CaptchaFox gives no usable answer (network error, timeout after 5 seconds, server error): `allow` lets the form through, `block` rejects it. Answers that CaptchaFox rejects are always rejected. Both cases are written to the TYPO3 log.
`robotMode`	off	Switches CaptchaFox off for all visitors, for automated tests only. Never enable it on a live site.
`enforceCaptcha`	off	Without it, CaptchaFox is neither shown nor checked while TYPO3 runs in the Development context.

⚠️

The default keys are the public test keys: the widget shows “For testing purposes only.” and nothing is protected until you enter your own keys.

Several Sites (Multi-Domain)

From versions 12.1.0 and 14.0.0 on (TYPO3 12 or newer), each site of an installation can use its own keys. Site settings override the extension configuration; each value that a site does not set falls back to it. Usually only the site key differs, because the secret key belongs to the CaptchaFox organization.

config/sites/<site>/settings.yaml:

captchafox:
  siteKey: 'sk_…'
  # Only if this site belongs to another CaptchaFox organization. Keep secrets out of version control:
  secretKey: '%env(CAPTCHAFOX_SECRET_KEY_EXAMPLE_COM)%'

From TYPO3 13 on, you can also edit both values in the backend: add the set “CaptchaFox” (captchafox/captchafox) to the site, then open Site Management > Settings (TYPO3 13) or Sites > Edit site settings (TYPO3 14). The editor shows the secret in plain text; the %env()% reference above avoids that.

Usage

Add the element CaptchaFox to a form in the form editor. The element always verifies the answer, even if its validator was removed from the form definition. Several forms with CaptchaFox on one page work independently.

Notes for Operators

Reverse proxies: The visitor’s IP address is sent to CaptchaFox. Behind a proxy or load balancer, configure $GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyIP'], otherwise the proxy’s address is sent.
Content Security Policy: If your site sends a Content Security Policy, allow the sources listed under Content Security Policy.
The widget script is loaded from https://cdn.captchafox.com/api.js; it cannot be bundled or self-hosted.

Keycloak ReachFive