Download the PHP package recranet/craft-secure-forms without Composer

Secure Forms

Contact forms for Craft CMS 5 with spam protection, stored submissions and proper error reporting. Replaces craftcms/contact-form, hybridinteractive/craft-contact-form-extensions and recranet/craft-contact-form-recaptcha in one plugin.

Design principles

• Spam is not an error. Real spam is stored with its score and reason, silently accepted (configurable), and never logged as an error.
• Misconfiguration is a real error. Missing/invalid captcha keys, a domain missing from the allowlist, an unreachable verification API or an SMTP failure are shown to the visitor, logged under the secure-forms category, and forwarded to Sentry when the SDK is installed. They never silently classify submissions as spam.
• Nothing is ever lost. Submissions are persisted before any email is attempted; send failures are recorded on the submission (failed status) instead of dropping the message.

Features

• Submission storage as elements with a fixed schema — dynamic form fields are stored as JSON and expanded back into columns on CSV export
• Persisted spam classification: isSpam, spamScore (reCAPTCHA v3 score), spamReason
• Spam protection: honeypot + Google reCAPTCHA v2/v3/Enterprise or Cloudflare Turnstile (experimental)
• Tokens bound to the form and the site: v3/Enterprise tokens are checked against the per-form action and the hostname they were minted on, so a token farmed elsewhere cannot be replayed
• Minimum fill time: submissions that arrive faster than a human could type are rejected before any captcha call is made
• Blocklist for human-driven spam: match a sender address, @domain, local-part prefix or IP prefix — the one thing a captcha score cannot catch
• Notification + optional confirmation emails, rendered from site templates
• Email / SMTP test utility in the control panel (works with allowAdminChanges disabled) that surfaces full SMTP transport errors
• Control panel section with per-form sources, statuses (sent / spam / failed) and search

Not supported

Deliberate non-goals, kept out to keep the attack surface and codebase small:

• File attachments — file inputs are ignored; nothing user-uploaded is ever stored or emailed. Forms that need uploads should use a dedicated form builder.
• Developer events — no beforeSend/afterSend hooks. This is an in-house plugin: extend it by changing the code, not by hooking it.
• Per-field validation — only fromName, fromEmail and message presence are validated server-side; dynamic message[...] fields are stored as-is. Use HTML validation attributes in the form template.

Installation

Usage

The individual fields are still available if you need to place them separately:

Why the action name matters

A reCAPTCHA v3 token is only as specific as the action it was minted with. When every form uses the same action, a token harvested from the cheapest form on the site — or from any other domain on the key's allowlist — verifies perfectly well against your most valuable form. Passing a distinct action per form (contact, apply, newsletter) binds each token to the form it came from: the action travels in a hashed hidden field, so the server compares Google's reported action against what the form actually rendered, and a bot cannot rewrite either side.

The plugin also compares the hostname Google reports against the hostname the form was posted to, which closes the same hole across domains sharing a site key.

Google only accepts letters, digits, / and _ in action names; anything else is logged as an error and falls back to submit.

Upgrading existing forms

Both checks are additive — a form that doesn't render the new fields keeps working exactly as before:

Once every form emits the timestamp, set requireTimestamp to true so a POST that never loaded a form is treated as spam.

Error handling in the template:

Configuration

All settings are read from the environment with sensible defaults, so one config file works across dev/staging/production. Create config/secure-forms.php:

When recaptchaHideBadge is enabled, Google requires the reCAPTCHA attribution to be visible in the form, e.g.:

Environment variables

Captcha keys live in .env:

Local dev: the boilerplate leaves the captcha keys empty so no captcha runs and the honeypot plus timing check still apply. If you do use Google's test keys locally, add testkey.google.com to SECURE_FORMS_CAPTCHA_ALLOWED_HOSTNAMES — that is the hostname Google reports for them.

All other settings can optionally be overridden per environment:

Google reCAPTCHA deprecation notes

Google deprecated classic reCAPTCHA and migrated all keys to Google Cloud projects (automated migration completed Q1 2026; keys without a Cloud project have API access locked). What this means for this plugin:

• Key management — keys live in a Google Cloud project, created either in the Cloud console or programmatically via the reCAPTCHA Enterprise API (projects.keys.create with webSettings.integrationType SCORE (v3) or CHECKBOX (v2) and the allowedDomains list). The key ID is what goes into RECAPTCHA_SITE_KEY.
• Server-side verification — this plugin verifies tokens via the legacy siteverify endpoint, which Google keeps supported for migrated and Enterprise-created keys. Use the legacy secret key as RECAPTCHA_SECRET_KEY, available in the Cloud console under Integration → Use legacy key or via the retrieveLegacySecretKey API method.
• Domain allowlist — keep the key's allowedDomains in sync with the site's domains. A domain missing from the allowlist stops the widget from producing tokens, which this plugin reports as a visible error (never as silent spam).
• Free quota — without a billing account (Essentials tier) reCAPTCHA includes 10,000 free assessments per month, aggregated across the whole Google Cloud organization: all sites and keys share the pool. Beyond it, siteverify fails open (returns success: true with a fixed 0.9 score instead of verifying), silently degrading spam protection. This plugin only generates assessments on actual form submits (not page views), so the quota maps 1:1 to submission attempts. See reCAPTCHA billing and tier comparison.
• Shared quota warning (agencies) — with many client sites' keys in one Cloud project, one busy or bot-targeted site can exhaust the shared pool and silently disable spam filtering on every other site in the organization. Link a billing account or use the recaptcha-enterprise provider to avoid this.
• Billing — linking a billing account (Standard tier) keeps the same 10,000 free assessments but replaces the fail-open cliff with paid verification: a flat $8 covers up to 100,000 assessments/month, then $1 per 1,000.
• Enterprise API — Google's long-term replacement for siteverify is the createAssessment API, supported by this plugin as the recaptcha-enterprise provider (requires RECAPTCHA_PROJECT_ID + RECAPTCHA_API_KEY). It returns the real risk score and fails closed on quota (HTTP 429, surfaced as a visible error) instead of silently passing.
• Cloudflare Turnstile — free, no assessment quota and no Google dependency; available as the turnstile provider (experimental) if moving away from reCAPTCHA entirely.

Migrating from contact-form-extensions

Stored submissions can be copied from craft-contact-form-extensions into Secure Forms. Run this before uninstalling the old plugin (its uninstall drops the source table):

Safe to re-run: already-migrated submissions are skipped. Recommended production order: install Secure Forms → run the migration → uninstall the old plugins.

Failure handling & manual delivery

Every submission is stored before any email is attempted, so nothing is ever lost. What happens per failure mode:

Why an action/hostname mismatch is stored rather than rejected: when it fires for a real attack it fires occasionally, but when it fires because of a misconfiguration (a proxy rewriting the host, a stale cached page minting the old action, a site key shared across domains) it fires on every submission. Storing it means that shows up in the Submissions index instead of silently swallowing every message the site receives.

Nav badge: the Secure Forms item in the control panel sidebar shows a badge with the number of submissions whose notification email never went out — visible from every CP page, no email dependency (an email alert would be useless when SMTP is the thing that's down).

Manual delivery: the submission detail view has a send button that covers both cases — Retry sending for failed submissions, and Not spam — send for reviewed spam (delivering it marks it as not spam; the score and reason are kept for the record). Re-scoring is impossible by design: captcha tokens are single-use and expire within minutes, so a stored submission can never be re-verified — a human decision replaces the score.

Email templates

Site templates receive submission (the element) and message (the decoded dynamic fields):