tmi/anti-spam

Framework-light, presentation-free anti-spam primitives for Symfony forms.

Layer 1 — honeypot stack (free, no CAPTCHA, no third party). Three cheap, JS-and-bot-resistant signals:

• Honeypot — a hidden website field a human never fills.
• Timestamp — _loaded_at (unix seconds, set by JS on page load). Submissions faster than 3 s or older than 6 h are rejected.
• JS token — _js_token, set by JS on first user interaction to the form's expected constant. A missing/mismatched token means JS never ran (bot).

Layer 2 — Cloudflare Turnstile (optional, stronger). A decoupled siteverify wrapper with an injected hostname allow-list — catches what the honeypot can't and vice versa. Use both for defence-in-depth.

Carries no entities, templates, translations or routes — pure logic + one form-type extension + one Stimulus controller. Detachable by design.

Install

composer require tmi/anti-spam

Register the bundle (Symfony Flex does this automatically):

// config/bundles.php
return [
    // ...
    Tmi\AntiSpam\TmiAntiSpamBundle::class => ['all' => true],
];

Usage

1. Add the honeypot fields to a form

public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'data_class' => MyRequest::class,
        'honeypot'   => true, // injects website / _loaded_at / _js_token (mapped:false)
    ]);
}

2. Wire the JS (Stimulus)

<form data-controller="antispam"
      data-antispam-timestamp-field-value="{{ field_name('_loaded_at') }}"
      data-antispam-token-field-value="{{ field_name('_js_token') }}"
      data-antispam-token-value="{{ constant('App\\Form\\MyType::JS_TOKEN') }}">

Copy assets/controllers/antispam_controller.js into your app's assets/controllers/ (or register the package's UX assets).

3. Check on submit

use Tmi\AntiSpam\HoneypotFields;
use Tmi\AntiSpam\Service\SpamGuard;

$reason = $spamGuard->detect(
    (string) $form->get(HoneypotFields::WEBSITE)->getData(),
    (string) $form->get(HoneypotFields::LOADED_AT)->getData(),
    (string) $form->get(HoneypotFields::JS_TOKEN)->getData(),
    MyType::JS_TOKEN,
);

if (null !== $reason) {
    // silently drop — no flash, no persistence
}

Pair it with a Symfony rate_limiter on the submit endpoint for layered defence.

4. (Optional) Cloudflare Turnstile

TurnstileVerifier is app-decoupled — it takes the allowed hostnames as a constructor argument rather than reading any app host registry, so subclass it (or wire it) to supply your own list. The HTTP client should be a scoped client pointed at https://challenges.cloudflare.com; the secret stays server-side.

use Tmi\AntiSpam\Service\TurnstileVerifier;

final class AppTurnstileVerifier extends TurnstileVerifier
{
    public function __construct(HttpClientInterface $turnstileClient, string $secret, LoggerInterface $logger)
    {
        parent::__construct($turnstileClient, $secret, $logger, ['example.com', 'www.example.com']);
    }
}

// in the controller, BEFORE the honeypot check:
$reason = $verifier->verify(
    $request->request->getString('cf-turnstile-response'),
    $request->getClientIp() ?? '',
    'newsletter', // the action your widget declared
);
// null = ok; otherwise 'missing-token'|'invalid-token'|'timeout-or-duplicate'|'hostname-mismatch'|'action-mismatch'|'network-error'

Hostnames are normalized (lowercase + trailing .local strip for dev parity) before comparison. The widget JS + sitekey stay in your app.

License

MIT.