Integrationen

Laravel Integration

1. Repository eintragen

Füge das CaptchaCore-Repository in deine composer.json ein:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://captchacore.eu/packages"
        }
    ]
}

2. Paket installieren

composer require captchacore/laravel

3. .env konfigurieren

CAPTCHACORE_URL=https://captchacore.eu
CAPTCHACORE_SITE_KEY=cc_pub_dein_key
CAPTCHACORE_SECRET_KEY=cc_sec_dein_secret
CAPTCHACORE_WIDGET_MODE=interactive  # interactive | visible | invisible
CAPTCHACORE_WIDGET_THEME=auto        # auto | light | dark
CAPTCHACORE_WIDGET_COLOR=#4ade80
CAPTCHACORE_WIDGET_LABEL=Ich bin kein Bot
CAPTCHACORE_WIDGET_BRAND=CaptchaCore

Blade-Component

<form method="post" data-captchacore="interactive">
    @csrf
    <!-- Formularfelder -->
    <x-captchacore::widget />
    <button type="submit">Absenden</button>
</form>

Middleware

// Route schützen
Route::post('/register', RegisterController::class)
    ->middleware('captchacore:register');

// Oder als Validation Rule
'captchacore_token' => ['required', new CaptchaCoreToken('contact')]

// Tests: fake() mockt alle Verifikationen
CaptchaCore::fake();

Symfony Bundle

Für Symfony 6.4 LTS und 7.x. Vier Integrationswege: FormType, Validator-Constraint, Controller-Attribute und Security-Badge.

1. Installieren

composer require captchacore/captchacore-bundle

Symfony Flex registriert das Bundle und legt config/packages/captchacore.yaml automatisch an.

2. .env konfigurieren

CAPTCHACORE_URL=https://api.captchacore.eu
CAPTCHACORE_SITE_KEY=cc_pub_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
CAPTCHACORE_SECRET_KEY=cc_sec_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

FormType (empfohlen)

use CaptchaCore\SymfonyBundle\Form\Type\CaptchaCoreType;

$builder
    ->add('email', EmailType::class)
    ->add('message', TextareaType::class)
    ->add('captcha', CaptchaCoreType::class, [
        'form_type' => 'contact',
    ]);

Controller-Attribute

use CaptchaCore\SymfonyBundle\Security\Attribute\RequiresCaptcha;

#[Route('/contact', methods: ['POST'])]
#[RequiresCaptcha(formType: 'contact')]
public function submit(Request $request): Response { /* ... */ }

Validator-Constraint (DTOs)

use CaptchaCore\SymfonyBundle\Validator\CaptchaCoreToken;

final class ContactDto {
    public function __construct(
        #[Assert\NotBlank]
        public string $email,

        #[CaptchaCoreToken(formType: 'contact')]
        public string $captchaToken,
    ) {}
}

Programmatisch

use CaptchaCore\SymfonyBundle\Client\CaptchaCoreClient;

$result = $this->captcha->verify($token, 'login');

if ($result->blocked()) {
    throw new AccessDeniedHttpException();
}

// Properties: valid, riskScore, action, confidence, reasons, stepUp

Twig (standalone)

{{ captchacore_widget(mode: 'interactive') }}

Tests

CaptchaCoreClient::fake(VerificationResult::allow());
$this->client->request('POST', '/contact', [...]);
self::assertResponseIsSuccessful();

WordPress Plugin

1. Plugin installieren — in WordPress unter Plugins → Installieren nach „CaptchaCore" suchen (Eintrag im WordPress-Verzeichnis). Updates kommen dann von WordPress selbst. Alternativ das ZIP aus dem Kundenbereich hochladen.
2. Aktivieren unter Plugins
3. Einstellungen > CaptchaCore öffnen
4. Service-URL, Site Key und Secret Key eintragen
5. Widget-Modus, Theme und Farbe wählen
6. Gewünschte Formulare aktivieren (Login, Register, Kommentare, etc.)

WoltLab Suite

Das Paket wird über den offiziellen WoltLab Plugin-Store bezogen. Installation und alle künftigen Updates laufen darüber — im Kundenbereich gibt es dafür keinen eigenen Download.

1. Paket erwerben im Plugin-Store und im ACP unter Pakete → Paket installieren einspielen
2. Zugangsdaten hinterlegen unter Optionen → Sicherheit → Anti-Spam → CaptchaCore: Service-URL, Site Key und Secret Key
3. Erscheinungsbild wählen: Modus, Theme, Akzentfarbe und Sprache — „auto" übernimmt die Sprache des Forums.
4. CaptchaCore als Captcha auswählen unter Optionen → Sicherheit → Anti-Spam → Captcha — damit gilt es für Registrierung, Kontaktformular und alle weiteren Systemformulare

Eigene Integration bauen

Sie wollen CaptchaCore in ein System bringen, für das es noch kein Paket gibt, etwa Shopware, Joomla oder ein eigenes Framework? Der Aufwand liegt bei wenigen Stunden. Diese Reihenfolge hat sich bewährt.

Vorlagen zum Abschauen

Alle mitgelieferten Integrationen sind nach demselben Muster gebaut. Für ein Symfony-basiertes System wie Shopware 6 ist das Symfony-Bundle die nächstliegende Vorlage, für ein klassisches CMS das WordPress-Plugin.

Vor der Veröffentlichung prüfen

• Formular ohne JavaScript abgeschickt — greift Ihre Fail-Regel?
• Token zweimal verwendet — die zweite Prüfung muss scheitern, der Nonce ist einmalig.
• Token nach mehr als fünf Minuten abgeschickt — das Widget erneuert ihn selbst, prüfen Sie das im Langzeittest.
• Zwei geschützte Formulare auf einer Seite — beide müssen unabhängig funktionieren.
• Formular per AJAX nachgeladen — erscheint das Widget?
• Geheimer Schlüssel taucht nirgends im HTML oder in JavaScript auf.
• Antwort mit decision=step_up — der Nutzer darf nicht in einer Sackgasse landen.