Download the PHP package happenv-com/filament-turnstile without Composer

Filament Turnstile

Cloudflare Turnstile panel plugin for Filament v4 and v5. Register it once on a panel and login is protected automatically — optionally registration and password-reset request too. No form schema edits for the common case.

Based on muazzambuilds/filament-turnstile by Muazzam Builds.

Key features

• Login, registration and password reset — one panel plugin protects Filament's auth pages; each page is switched on or off on its own. See Panel plugin.
• Multi-factor authentication aware — Turnstile runs on the password step only, never again on the app code or passkey challenge.
• Custom auth pages — one trait per page (Login, Register, RequestPasswordReset) adds Turnstile to your own subclasses, plus a Turnstile form field for any other Filament form. See Custom auth pages.
• Testing helpers — Livewire test mixins (assertTurnstileBlocks(), assertTurnstileAllows(), passTurnstile(), …) for Pest and PHPUnit, with Cloudflare's test keys answered locally, so tests never reach Cloudflare. See Testing your application.
• Laravel 11, 12 and 13, Filament 4 and 5 — see Requirements.
• Translations — validation messages in 64 languages, every locale Filament ships. See Supported languages.
• Safe without keys — with no keys configured the widget is hidden and verification is skipped, so local apps still boot.

Requirements

CI runs the test suite on PHP 8.3 – 8.5 with Laravel 12 and 13 and Filament 4 and 5. PHP 8.2 and Laravel 11 are allowed by composer.json but cannot be tested in CI (the test tooling needs PHP 8.3, and Composer refuses every Laravel 11 release because of security advisories).

Installation

Install the package via Composer:

Add your keys to .env:

Create a widget and get keys at dash.cloudflare.com → Turnstile.

Register the plugin in your panel provider — see Panel plugin below.

The widget's wrapper uses a few Tailwind classes. If your panel uses a custom theme, add the package's views to its CSS file so Tailwind generates them:

Configuration

Publish the config file (optional):

Optionally, publish the views:

Usage

Panel plugin (recommended)

Call ->plugin(...) after ->login() / ->registration() / ->passwordReset() so the plugin can swap the auth page classes:

Defaults: login is protected; registration and password-reset request are not.

Each page is toggled independently, so any combination works — e.g. registration and password reset only:

Login protection works with Filament multi-factor authentication (app codes, passkeys): Turnstile appears only on the password step, and the multi-factor challenge step has no widget and no second verification.

Widget options

Manual form field

For custom auth pages or any Filament form:

Disable auto-swap and extend or compose yourself:

Custom auth pages

Keep extending Filament's page and add the matching trait from Happenv\FilamentTurnstile\Concerns — it carries everything the packaged page does:

What each trait adds:

• Every trait gives the page a default form with the widget and resets the widget on any validation error.
• InteractsWithTurnstileLogin also resets the widget after a wrong password and skips it on the multi-factor challenge step (app codes, passkeys). The token was already verified on the password step, and Cloudflare accepts a token only once.
• InteractsWithTurnstileRegistration also keeps the token out of the data passed to user creation.
• InteractsWithTurnstilePasswordReset also resets the widget after each request, so another one can be sent.

InteractsWithTurnstile is the shared base — use it directly only for forms other than these auth pages.

Register the page yourself and turn off the plugin's swap for it, otherwise the plugin replaces it with the packaged page:

Use the login trait (not the generic InteractsWithTurnstile) on login pages: it keeps Turnstile off the multi-factor challenge step.

Testing your application

Local and CI keys

Cloudflare test keys (any hostname, including localhost):

With a test site key the widget produces the dummy token XXXX.DUMMY.TOKEN.XXXX. The package answers the test secret keys itself, the same way Cloudflare does — verification never leaves the app, so it works offline and with Http::preventStrayRequests(). Production secret keys reject the dummy token.

If keys are missing, the widget is hidden and server validation is skipped so local apps without Turnstile still boot.

Livewire test helpers

The package adds Turnstile helpers to Livewire's test object (Livewire::test(...), or livewire(...) from pest-plugin-livewire), the same way Filament adds fillForm() — they work in Pest and PHPUnit alike. Each helper switches the app to the Cloudflare test keys above and fills the dummy token, so no request reaches Cloudflare.

Test the page your panel registers — the packaged one, or your own page using a trait:

assertTurnstileBlocks() and assertTurnstileAllows() first assert the widget is active, so they fail on a page Turnstile does not protect instead of passing silently. Every helper takes the schema name as its last argument (default form); the two call helpers take the method's arguments before it:

Use passTurnstile() to get past Turnstile in tests about something else — the full login with a multi-factor challenge, for example:

The helpers change the filament-turnstile.* keys in the config for the rest of that test.

Browser tests

The helpers above extend Livewire's test object; Pest's browser pages cannot be extended the same way. In a browser test, switch to the test keys yourself — Pest serves the app from the test process, so the config applies to the page. The real widget then solves itself; wait for its token before submitting:

The widget loads from challenges.cloudflare.com, so browser tests need network access.

Translations

Validation messages ship in every locale Filament ships — see Supported languages. The app locale picks the language.

To change a message or add a language, publish the files:

The widget itself follows the browser language; set ->language() or TURNSTILE_LANGUAGE to fix it.

Supported languages

Development

The browser tests drive the real widget from challenges.cloudflare.com with Cloudflare's test keys, so they need network access.

Upgrading

Breaking changes and how to migrate are described in UPGRADING for every major version.

Changelog

See GitHub releases for what has changed recently.

Contributing

See CONTRIBUTING for details.

Security vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Happenv sp. z o.o.
• webard
• Muazzam Builds — author of the original muazzambuilds/filament-turnstile
• All contributors

License

The MIT License (MIT). See License File for more information.