Cloudflare Turnstile

• Installation
• Customizing the Reset Event
• Turnstile Keys
• Usage
• Turnstile Events
  • Reset event
  • Dispatching the reset event
  • Resetting the login captcha
• Real-life example
• Testing
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Filament Turnstile is a lightweight plugin that seamlessly integrates Cloudflare Turnstile with your Filament application.

#Installation

Install the package via Composer:

composer require l3aro/filament-turnstile

Publish the configuration file with:

php artisan vendor:publish --tag="filament-turnstile-config"

Optionally publish the views with:

php artisan vendor:publish --tag="filament-turnstile-views"

The published configuration file contains:

return [
    'key' => env('TURNSTILE_SITE_KEY'),
    'secret' => env('TURNSTILE_SECRET_KEY'),
    'reset_event' => env('TURNSTILE_RESET_EVENT', 'reset-captcha'),
];

#Customizing the Reset Event

You can customize the name of the reset event globally by modifying the TURNSTILE_RESET_EVENT in your .env file:

TURNSTILE_RESET_EVENT=your-custom-event-name

Or by directly modifying the reset_event value in the configuration file. This allows you to use a custom event name that better fits your application's event naming convention or to avoid conflicts with other JavaScript events.

#Turnstile Keys

To use Cloudflare Turnstile, obtain your SiteKey and SecretKey from the Cloudflare dashboard.

Refer to the documentation for step-by-step instructions.

After you generate the keys, add them to your .env file in the following format:

TURNSTILE_SITE_KEY=1x00000000000000000000AA
TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA

For testing, you may use the dummy site and secret keys provided by Cloudflare.

#Usage

Using the plugin is straightforward. In your form, add the following component:

use l3aro\FilamentTurnstile\Enums\TurnstileSize;
use l3aro\FilamentTurnstile\Enums\TurnstileTheme;
use l3aro\FilamentTurnstile\Forms\Turnstile;


Turnstile::make('captcha')
    ->theme(TurnstileTheme::Auto)
    ->size(TurnstileSize::Normal)
    ->language('en-US')
    ->resetEvent('reset-captcha')

See the supported languages list for available locale codes.

The Turnstile field exposes additional options. Review the Cloudflare configuration guide for full details.

#Turnstile Events

The package provides events you can use to control the captcha in different scenarios.

#Reset event

The reset event (default: reset-captcha) resets the captcha challenge. It is helpful when you need to:

• Clear the challenge after a successful submission so the next visitor receives a fresh captcha.
• Reset the challenge after validation errors to avoid reusing a solved captcha when the form fails.

#Dispatching the reset event

There are two primary ways to dispatch reset-captcha:

1. Via onValidationError: Filament automatically calls onValidationError when validation fails. Dispatch the event there to refresh the captcha.

   use l3aro\FilamentTurnstile\Facades\FilamentTurnstileFacade;
   
   protected function onValidationError(ValidationException $exception): void
   {
       $this->dispatch(FilamentTurnstileFacade::getResetEventName());
   
       // Perform additional actions as needed (e.g., display error messages)
   }
   

2. Manually: Dispatch the event whenever your logic requires a reset.

   $this->dispatch(FilamentTurnstileFacade::getResetEventName());
   

#Resetting the login captcha

To automatically reset the captcha after a failed login attempt, use the throwFailureValidationException method in your login form's Livewire component:

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
}

Throwing a validation exception triggers onValidationError, which dispatches reset-captcha and refreshes the captcha for the next attempt.

#Real-life example

To implement the Turnstile captcha on the Login page in Filament, follow these steps:

Create a new App/Filament/Pages/Auth/Login.php class:

namespace App\Filament\Pages\Auth;

use l3aro\FilamentTurnstile\Forms\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'),
                    ])
                    ->statePath('data'),
            ),
        ];
    }

    // if you want to reset the captcha in case of validation error
    protected function throwFailureValidationException(): never
    {
        $this->dispatch(FilamentTurnstileFacade::getResetEventName());

        parent::throwFailureValidationException();
    }
}

Then override the login() method in your PanelProvider (for example, 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

• l3aro
• All Contributors

#License

The MIT License (MIT). Please see License File for more information.