Cloudflare Turnstile Bundle Laravel Package

Product Decisions This Supports

• Bot-mitigation vendor choice (Turnstile vs reCAPTCHA vs hCaptcha): The bundle collapses the "how hard is it to wire in?" variable to near zero on Symfony, so the decision can be made on the criteria that actually matter — privacy posture, accessibility, conversion impact, and cost — instead of on engineering effort. Turnstile is free and privacy-forward, which makes it the default candidate for a roadmap item that would otherwise stall on "we'll get to it."
• Build vs. buy for CAPTCHA integration: The entire surface area is one Twig/JS widget plus a server-side POST to siteverify. That is a genuinely small build. This package is the artifact that lets you price the buy option honestly: if it saves 1–2 engineer-days per form surface and you have several surfaces, integrate; if you have one form, write it yourself.
• Which surfaces get protected, and in what order: Signup, login, password reset, checkout guest flow, contact/support, and public API endpoints have very different friction tolerances. Having a drop-in integration makes it cheap to A/B one surface at a time rather than shipping a platform-wide CAPTCHA policy in one risky release.
• Stack-fit decision — and this is the load-bearing one: despite the framing as a Laravel/PHP package, this is a Symfony bundle (DI extension, bundle config, Twig integration). For a Laravel roadmap it informs the decision only as a reference implementation or in a mixed Symfony service. A Laravel team should treat this as evidence that "the integration is trivial" and then choose a Laravel-native path.
• Runtime/platform currency: 0.5.0 hard-requires PHP 8.2+ (7.4 support removed, readonly classes/properties used). That converts "check version constraints" from a footnote into a gating condition: any service still on 8.0/8.1 cannot consume this release at all, and a service on 8.2+ takes an upgrade-cadence dependency. It should show up in the platform-upgrade roadmap, not just the package decision.
• Compliance and privacy roadmap: a cookieless, privacy-oriented challenge reduces the consent-management and DPA surface versus reCAPTCHA. If legal review is a gate on roadmap items, picking Turnstile early removes a recurring blocker.
• Maintenance ownership: with 35 stars and 0 dependents, adopting this is effectively a decision to own it. That is a real resourcing decision (a fork, a pinned version, a wrapper interface), and it belongs in the plan, not in the postmortem. 0.5.0 does not change this — new translations and unit tests are quality signals, not an adoption base.
• Localization and accessibility commitments: 0.5.0 ships German, Italian, and Spanish translations, which materially narrows the gap between this bundle and the "international funnel" requirement that previously had to be hand-rolled. The remaining accessibility question (assistive-tech behavior, WCAG conformance of the challenge itself) is a provider property, not something this package fixes.

When to Consider This Package

Adopt when:

• You are on Symfony and on PHP 8.2 or newer. 0.5.0 dropped PHP 7.4 support and adopted readonly classes and constructor property promotion, so 8.2 is a hard floor, not a preference. Confirm the supported Symfony version matrix in composer.json against your runtime before anything else.
• You use Twig and/or Symfony Forms — the bundle's value is exactly this glue, and 0.5.0 adds unit tests for TurnstileType, so the form-type path is now the better-covered one.
• You want config-driven site key / secret key handling rather than hard-coded values, and server-side verification wired into your existing flow.
• You want German, Italian, or Spanish UI copy without maintaining translation files yourself — this release closes a real gap for EU/ES-funnel products and removes one previously-plausible reason to build in-house.
• Your config passes a real boolean to the enable option. The switch from scalarNode to booleanNode is a small but real backward-compatibility break: string-typed values (enable: "true") that previously validated will now be rejected. If you use %env(bool:…)%, you're fine; if you hand-typed a string, that's your upgrade work item.
• You are comfortable being an early adopter. MIT licensing plus a small code surface means forking is cheap — budget for it explicitly, and note that 0.5.0 marked Configuration, the compiler pass, and the DI extension as final, so a fork is a copy, not a subclass. Plan accordingly.
• You want a fast spike to generate real conversion and abuse-rate data before committing to a provider.

Look elsewhere when:

• Your stack is Laravel. This is not a Laravel package. Use a Laravel-native Turnstile package, or drop in the Cloudflare script tag plus a validation rule and a Http::post to siteverify — roughly the same effort, no third-party maintenance tail.
• You are on PHP below 8.2. 0.5.0 is unavailable to you; you would be pinning 0.4.x, which means adopting an out-of-support branch on an auth path. Not worth it for a ~100-line integration.
• You need enterprise support, an SLA, or a security review with a vendor to talk to. Zero dependents and a single maintainer is the whole risk profile, and this release did not change it.
• You need the fuller Turnstile feature set — action and cData tokens, custom widget theming/language overrides, explicit handling of the documented error codes, testing keys in CI. New translations are display strings, not full i18n configurability; confirm the rest before you commit.
• Your policy forbids unreviewed third-party bundles in auth paths. In that case, vendor the ~100 lines into your own codebase — the license permits it and you keep the upgrade path.
• You are mid-migration off Symfony. A jump from scalarNode to booleanNode plus a runtime floor bump in a single minor release is a reasonable signal to check release cadence against your own upgrade calendar.

Practical gate before adoption: read the source end-to-end, confirm the server-side verification is actually performed server-side with the secret (not in Twig), confirm the token is single-use and validated on every protected request, and confirm behavior when Cloudflare is unreachable — fail-open vs fail-closed is a product decision, not an implementation detail, and you should be the one making it. The new TurnstileType tests are a starting point for confidence, not a substitute for that review.

How to Pitch It (Stakeholders)

For executives: Cloudflare Turnstile is a free, privacy-friendly bot challenge — it cuts spam signups, credential-stuffing attempts, and fake support tickets without the image puzzles that hurt conversion, and it avoids the third-party-cookie and consent overhead of reCAPTCHA. Integration cost is measured in days, not sprints. The newest release (0.5.0) added German, Italian, and Spanish UI copy and unit tests, which is good housekeeping for an international funnel, but it also raised the PHP floor to 8.2 — so it only applies to services already on our current runtime. The package itself remains a very small open-source project (35 stars, no downstream users, one maintainer), so we should treat it as a fast prototype, not a foundation: run a short spike, measure abuse and conversion impact, and keep the option to swap providers or maintain our own copy. Because it's MIT-licensed and the integration is only a few dozen lines, the worst case is inexpensive — we fork it or replace it in a day.

For engineering: it's a Symfony bundle — DI configuration for site/secret keys, a Twig helper for the widget, and server-side verification against siteverify. 0.5.0 requires PHP 8.2+ (readonly classes/properties, constructor promotion) and tightens the enable option from scalarNode to booleanNode, so a string-typed value that used to pass validation will now fail — check your config before bumping. Configuration, PixelOpenCloudflareTurnstileCompilerPass, and PixelOpenCloudflareTurnstileExtension are now final, so plan any fork as a copy rather than a subclass. Adopt behind our own thin interface (CaptchaVerifier) so the provider and the package are both swappable, pin the version, and add tests for the failure modes the bundle doesn't cover: expired token, reused token, Cloudflare timeout, and missing secret. Given zero dependents, assume we own upgrades.

The ask: a one-to-two day spike on a single low-risk form, on a service already on PHP 8.2+, with a written go/no-go on conversion delta, abuse reduction, and maintenance burden — and a stated fallback (Laravel/Symfony-native integration or in-house verification) agreed before we start.