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.

coderflex / filament-turnstile

Maintainers

Details