coderflex / filament-turnstile
Filament Plugin to help you implement Cloudflare Turnstile
Installs: 11 040
Dependents: 0
Suggesters: 0
Security: 0
Stars: 16
Watchers: 0
Forks: 7
Open Issues: 1
Requires
- php: ^8.1
- coderflex/laravel-turnstile: ^1.0|^2.0
- illuminate/contracts: ^10.0|^11.0
- spatie/laravel-package-tools: ^1.14.0
Requires (Dev)
- filament/filament: ^3.0
- larastan/larastan: ^2.0.1
- laravel/pint: ^1.0
- nunomaduro/collision: ^7.9|^8.1
- orchestra/testbench: ^8.0|^9.0
- pestphp/pest: ^2.0
- pestphp/pest-plugin-arch: ^2.0
- pestphp/pest-plugin-laravel: ^2.0
- pestphp/pest-plugin-livewire: ^2.0
- phpstan/extension-installer: ^1.1
- phpstan/phpstan-deprecation-rules: ^1.0
- phpstan/phpstan-phpunit: ^1.0
README
Filament Turnstile is an essential plugin designed to seamlessly integrate Cloudflare's turnstile into your applications.
This plugin uses Laravel Turnstile under the hood. For detailed information, explore the Laravel Turnstile README.
Installation
Install the package via Composer:
composer require coderflex/filament-turnstile
For users still on Filament V2, install the package using:
composer require coderflex/filament-turnstil "^1.0"
Turnstile Keys
To utilize Cloudflare Turnstile, obtain your SiteKey
and SecretKey
from your Cloudflare Dashboard.
Refer to the documentation for detailed instructions.
After generating the keys, include them in your .env
file using the following format:
TURNSTILE_SITE_KEY=1x00000000000000000000AA TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
For testing purposes, you can use Dummy site keys and secret keys provided by Cloudflare.
Usage
Utilizing this plugin is incredibly straightforward. In your form, incorporate the following code:
use Coderflex\FilamentTurnstile\Forms\Components\Turnstile; Turnstile::make('captcha') ->theme('auto') // accepts light, dark, auto ->language('en-US') // see below ->size('normal'), // accepts normal, compact
For a list of supported languages, refer to the supported languages section.
The Turnstile
field offers various options; you can learn more about them in the Cloudflare configuration section.
Turnstile Events
The Turnstile package provides events that you can leverage to manage the behavior of the captcha in various scenarios.
Reset Event
The reset-captcha
event allows you to programmatically reset the captcha challenge. This can be useful when you want to:
- Clear the challenge after a successful form submission: This ensures a fresh captcha for the next user.
- Reset the challenge upon validation errors: Prevents users from being stuck with a previously solved captcha after encountering errors during form submission.
Dispatching the Reset Event:
There are two primary ways to dispatch the reset-captcha
event:
1. Using onValidationError
Method:
Filament provides the onValidationError
method within your form's Livewire component. This method is automatically triggered whenever form validation fails. Here's how to utilize it:
protected function onValidationError(ValidationException $exception): void { $this->dispatch('reset-captcha'); // Perform additional actions as necessary (e.g., display error messages) }
In this example, the reset-captcha
event is dispatched upon validation errors, ensuring the captcha is reset for the user's next attempt.
2. Manual Dispatching:
For scenarios where resetting the captcha is not directly tied to validation, you can manually dispatch the event using Filament's event dispatcher:
$this->dispatch('reset-captcha');
Using Reset Event in Login Page:
To automatically reset the captcha on a failed login attempt in your login form's Livewire component, leverage the throwFailureValidationException
method:
protected function authenticate(): void { // Perform authentication logic // ... if (! Auth::attempt($this->data)) { $this->throwFailureValidationException( [ 'email' => 'Invalid email or password.', ] ); } // Redirect to success page or perform other actions }
By throwing a validation exception with appropriate error messages, you trigger the onValidationError
method, which in turn dispatches the reset-captcha
event, effectively resetting the captcha for the next login attempt.
Real-Life Example:
To implement the Turnstile captcha with the Login
page in Filament, follow these steps:
Create a new App/Filament/Pages/Auth/Login.php
class:
namespace App\Filament\Pages\Auth; use Coderflex\FilamentTurnstile\Forms\Components\Turnstile; use Filament\Forms\Form; use Filament\Http\Responses\Auth\Contracts\LoginResponse; use Filament\Pages\Auth\Login as AuthLogin; class Login extends AuthLogin { /** * @return array<int|string, string|Form> */ protected function getForms(): array { return [ 'form' => $this->form( $this->makeForm() ->schema([ $this->getEmailFormComponent(), $this->getPasswordFormComponent(), $this->getRememberFormComponent(), Turnstile::make('captcha') ->label('Captcha') ->theme('auto'), ]) ->statePath('data'), ), ]; } // if you want to reset the captcha in case of validation error protected function throwFailureValidationException(): never { $this->dispatch('reset-captcha'); parent::throwFailureValidationException(); } }
Then, override the login()
method in your PanelProvider
(e.g., AdminPanelProvider
):
namespace App\Providers\Filament; use App\Filament\Auth\Login; use Filament\Panel; use Filament\PanelProvider; class AdminPanelProvider extends PanelProvider { public function panel(Panel $panel): Panel { return $panel ->default() ->id('admin') ->path('admin') ->login(Login::class); // override the login page class. ... } }
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see the License File for more information.