friendlycaptcha_official
studiomitte/friendlycaptcha-typo3
main
en
Studio Mitte GmbH
This document is published under the Creative Commons BY 4.0 license.
Fri, 06 Feb 2026 09:36:19 +0000
<abstract>
Table of Contents:
Tip
Checkout the information and demo at https://friendlycaptcha.com/ before trying this extension.
This extension integrates the service of Friendly Captcha into your site by using the official API. This version only supports Friendly Captcha V2. For V1 support, please install an earlier version of the plugin.
Currently it supports the following form solutions:
typo3/cms-form )in2code/powermail )Additionally the extension can be used in your own extensions.
This chapter should help people understand how the extension works. Remove it if it is not relevant.
Official demo of Friendly Captcha
This extension can be installed as most of all other extensions of TYPO3 too.
Note
To be able to use the extension, it is required to configure it after the installation.
This is described in the Configuration section!
Use composer to install this extension by using
composer require studiomitte/friendlycaptchaUse the TYPO3 Extension Manager to install this extension.
Search for friendlycaptcha_ and install the extension.
Please follow the links below to learn more about the configuration of Friendly Captcha.
It is required to have an account at https://friendlycaptcha.com/ before being able to use this extension!
After creating the account, you need to setup a so called Application
Creation of an application
Note
This version on the Plugin supports only FriendlyCaptcha V2. The V2 version has to be enabled in your Application
and afterwards you need to create new a new API Key. Please copy the generated key as you need it later!
Creation of an API Key
The integration is configured in the Sites module.
Switch to the module Site Management/Sites and select the site which you want to configure.
A new tab Friendly Captcha is available which includes all configuration options.
Integration in the Site module
Note
After finishing the configuration, you are ready to use Friendly Captcha on your site.
This is described in the Using Friendly Captcha section!
By default, the global endpoint https:// is used.
If you prefer to use the EU endpoint, enter https:// in Verify URL field and ensure that the Use EU Puzzle Endpoint option is checked.
If you are using automated tests you might want to skip the captcha.
This can be achieved by setting the folloowing ENV variable FRIENDLYCAPTCHA_ to a string with minimum length of 30.
Now provide the same string with with the request header X-.
After a successful setup, you are ready to use the Friendly Captcha in TYPO3.
Follow one of the links below how to integrate it.
If the extension form is used, the Friendly Captcha integration is automatically available
in the section Advanced Elements.
Field "Friendly Captcha"
The automatically used template can be found at EXT:.
Friendly Captcha can be used in EXT:powermail by following these steps:
TypoScript and Page TsConfig need to be extended.
Either import the TypoScript manually in your site package or add the following line to your TypoScript template:
@import 'EXT:friendlycaptcha_official/Configuration/TypoScript/Powermail/setup.typoscript'or select the TypoScript in your TypoScript record
Add TypoScript
Either import the TsConfig manually in your site package or add the following line to your TsConfig files :
@import 'EXT:friendlycaptcha_official/Configuration/PageTsConfig/powermail.typoscript'or select the TypoScript in your TypoScript record
Add Page TsConfig
It is now possible to select Friendly Captcha as a field type in a powermail field record
Add Friendly Captcha to your form
The result should look like this:
Result
To integrate Friendly Captcha in your own extensions, 2 steps are required:
The puzzle needs to be integrated into the form. This can be done like this in your templates
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
xmlns:friendlycaptcha="http://typo3.org/ns/StudioMitte/FriendlyCaptcha/ViewHelpers"
data-namespace-typo3-fluid="true">
<f:variable name="captchaConfiguration" value="{friendlycaptcha:configuration()}" />
<f:if condition="{captchaConfiguration.enabled}">
<f:then>
<f:asset.script defer="1" async="1" identifier="friendlycaptcha" src="{captchaConfiguration.jsPath}" />
<div class="frc-captcha" data-sitekey="{captchaConfiguration.siteKey}" {f:if(condition: '{captchaConfiguration.useEuPuzzleEndpoint}', then: 'data-api-endpoint="eu"')}></div>
</f:then>
<f:else>
<p>{f:translate(key:'LLL:EXT:friendlycaptcha_official/Resources/Private/Language/locallang.xlf:configuration_missing')}</p>
</f:else>
</f:if>
</html>The verification of the puzzle is done after the form has been submitted. Either use the validator \Studio or use a custom implementation with a code like this
$friendlyCaptchaService = GeneralUtility::makeInstance(Api::class);
// either pass the solution as 1st argument to verify() or let it be fetched from the request within the method
if (!$friendlyCaptchaService->verify()) {
$this->addError(
$this->translateErrorMessage('message.invalid', 'friendlycaptcha_official'),
1689236324
);
}If you’re currently using an earlier version of the plugin with Friendly Captcha V1 and want to switch to Friendly Captcha V2:
Puzzle Endpoint - check it if you want to use the EU Endpoint
Verify URL - https:// or https:// if you prefer to use EU endpoint
JavaScript Path - EXT:
JavaScript Path. _v2.1.0_update:
If you’re currently using an earlier v2 version of the plugin and want to switch to Friendly Captcha v2.1.0:
Change EXT: to EXT:
Version 2.1.0 of the plugin uses the latest 0.1.26 version of the Friendly Captcha widget library, which includes improvements to accessibility.