[2.x] Adds livewire helpers.

Author: DarkGhostHunter

.github/workflows/php.yml

@@ -61,6 +61,10 @@ jobs:
           - 12.*
           - 13.*
         dependencies: [ lowest, highest ]
+        include-filament: [ true ]
+        exclude:
+          - laravel-constraint: "13.*"
+            include-filament: true
 
     steps:
       - name: Set up PHP
@@ -73,6 +77,11 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v6
 
+      # Remove this once Filament PHP v5 gets Laravel 13 compatibility.
+      - name: Remove Filament for Laravel 13 compatibility
+        if: matrix.laravel-constraint == '13.*'
+        run: composer remove "filament/filament" --dev --no-update
+
       - name: Install dependencies
         uses: ramsey/composer-install@v3
         with:

README.md

@@ -564,7 +564,7 @@ $request->validate([
 ]);
 ```
 
-#### Rule accepts failed challenges 
+#### Rule accepts failed challenges
 
 The rule supports not checking if the challenge is successful by setting the `accept-failed` parameter. This can be useful to retrieve the response later and programmatically continue based on the response result through the `sucess()` and `failed()` methods of the `Turnstile` facade.
 
@@ -840,6 +840,83 @@ return Application::configure(basePath: dirname(__DIR__))
     ->create();
 ```
 
+## Livewire & Filament trait
+
+If you're using Liveware or Filament PHP, you may use the `Laragear\Turnstile\Livewire\InteractsWithTurnstile` trait in your Filament Pages or components.
+
+The trait will register a hook _after validation_, that only runs on non-Precognitive requests. This way, the Turnstile Challenge is consumed only when the form is completely validated. It also avoids using an idempotency key based on the request fingerprint, saving you a request to Cloudflare Turnstile servers.
+
+```php
+use Filament\Forms\Concerns\InteractsWithForms;
+use Filament\Forms\Contracts\HasForms;
+use Filament\Pages\Page;
+use Filament\Schemas\Schema;
+use Laragear\Turnstile\Livewire\InteractsWithTurnstile;
+
+class MyCustomPage extends Page implements HasForms
+{
+    use InteractsWithForms;
+    use InteractsWithTurnstile;
+
+    public function form(Schema $schema) : Schema
+    {
+        return $schema->components([
+            // ...
+        ]);
+    }
+}
+```
+
+If you're using a custom challenge key in your form, you may override the `turnstileToken()` method to retrieve the value of the token.
+
+```php
+/**
+ * Return token for the Turnstile Challenge present in the form.
+ *
+ * @return string|null|void
+ */
+protected function turnstileToken(string $key)
+{
+    return $this->data['cloudflare-turnstile-token'];
+}
+```
+
+> [!IMPORTANT]
+> 
+> The trait injects the Turnstile challenge validation on all forms. If you need more customization, use the [`afterValidate()` hook](https://filamentphp.com/docs/5.x/resources/creating-records#lifecycle-hooks).
+
+### Handling the Turnstile Challenge
+
+You have access to some useful methods to handle if the challenge should be deemed successful or not, and how to handle successes and failures:
+
+* `skipTurnstileValidation()`: Returns if the challenge verification should run when authenticated.
+* `handleTurnstileChallengeStatus()`: Returns if the challenge is successful or not.
+* `handleSuccessfulTurnstileChallenge()`: Handle a successful Turnstile challenge.
+* `handleFailedTurnstileChallenge()`: Handle a failed Turnstile challenge.
+
+For example, for non-admins, you may check if the challenge is successful if it matches the component action:
+
+```php
+use Illuminate\Support\Str;
+use Laragear\Turnstile\Challenge;
+
+/**
+ * Check if the Turnstile challenge validation should be skipped if authenticated.
+ */
+protected function skipTurnstileValidation(): bool
+{
+    return auth('admins')->check();
+}
+
+/**
+ * Handles the Turnstile challenge and returns true or false if it has succeeded or failed.
+ */
+protected function handleTurnstileChallengeStatus(Challenge $challenge): bool
+{
+    return $challenge->successful && $challenge->isAction(Str::snake(static::class));
+}
+```
+
 ## Advanced configuration
 
 Laragear Turnstile is intended to work out-of-the-box, but you can publish the configuration file for fine-tuning the Challenge verification.

composer.json

@@ -35,6 +35,7 @@
         "illuminate/session": "12.*|13.*"
     },
     "require-dev": {
+        "filament/filament": "4.*|5.*",
         "orchestra/testbench": "10.*|11.*"
     },
     "autoload": {

lang/en/notification.php

@@ -0,0 +1,8 @@
+<?php
+
+return [
+    'failed' => [
+        'title' => 'The Turnstile Challenge is invalid',
+        'body' => 'Please try again or refresh the page.',
+    ],
+];

lang/es/interstitial.php

@@ -0,0 +1,6 @@
+<?php
+
+return [
+    'title' => 'Comprobando la conexión segura',
+    'description' => 'Su navegador será redirigido automáticamente',
+];

lang/es/notification.php

@@ -0,0 +1,7 @@
+<?php
+return [
+    'failed' => [
+        'title' => 'El desafío de Turnstile no es válido',
+        'body' => 'Por favor, inténtalo de nuevo o recarga la página.',
+    ],
+];

lang/es/validation.php

@@ -0,0 +1,5 @@
+<?php
+
+return [
+    'invalid' => 'El desafío de Turnstile es inválido, ausente o falló.',
+];

src/Challenge.php

@@ -2,9 +2,9 @@
 
 namespace Laragear\Turnstile;
 
+use Carbon\CarbonInterface;
 use ErrorException;
 use Illuminate\Support\Arr;
-use Carbon\CarbonInterface;
 use Illuminate\Support\Stringable;
 use InvalidArgumentException;
 use function in_array;
@@ -84,7 +84,7 @@ public function isAction(string $action): bool
     }
 
     /**
-     * Check if the action is not the same as the developer expects.
+     * Check if the action is different from the developer expects.
      */
     public function isNotAction(string $action): bool
     {
@@ -110,7 +110,7 @@ public function isCustomerData(string|iterable $customerData): bool
     }
 
     /**
-     * Checks if the Customer Data is not the same pattern as the developer expects.
+     * Checks if the Customer Data is a different pattern as the developer expects.
      *
      * @param  string|iterable<string>  $customerData
      */

src/Livewire/InteractsWithTurnstile.php

@@ -0,0 +1,141 @@
+<?php
+
+namespace Laragear\Turnstile\Livewire;
+
+use Filament\Notifications\Notification;
+use Illuminate\Contracts\Validation\Validator as ValidatorContract;
+use Illuminate\Support\Arr;
+use Illuminate\Validation\ValidationException;
+use Laragear\Turnstile\Challenge;
+use Laragear\Turnstile\Turnstile;
+use Throwable;
+use function __;
+use function app;
+use function request;
+
+trait InteractsWithTurnstile
+{
+    /**
+     * Boots the trait.
+     */
+    public function bootInteractsWithTurnstile(): void
+    {
+        $this->withValidator(function (ValidatorContract $validator): void {
+            $validator->after($this->validateTurnstile(...));
+        });
+    }
+
+    /**
+     * Check if the Turnstile challenge validation should be skipped.
+     */
+    protected function skipTurnstileValidation(): bool
+    {
+        return false;
+    }
+
+    /**
+     * Validates the Turnstile captcha token provided in the request data.
+     */
+    protected function validateTurnstile(): void
+    {
+        if ($this->skipTurnstileValidation() || request()->isPrecognitive()) {
+            return;
+        }
+
+        $turnstile = app(Turnstile::class);
+
+        // If Turnstile is disabled, we don't need to use it at all.
+        if ($turnstile->isDisabled()) {
+            return;
+        }
+
+        if (!$token = $this->turnstileToken($turnstile->key())) {
+            $this->handleFailedTurnstileChallenge();
+        }
+
+        try {
+            $challenge = $this->retrieveTurnstileChallenge($turnstile, $token);
+        } catch (Throwable $exception) {
+            $this->handleTurnstileException($exception);
+        }
+
+        $challenge && $this->handleTurnstileChallengeStatus($challenge)
+            ? $this->handleSuccessfulTurnstileChallenge($challenge)
+            : $this->handleFailedTurnstileChallenge($challenge);
+    }
+
+    /**
+     * Return token for the Turnstile Challenge present in the form.
+     *
+     * @return string|null|void
+     */
+    protected function turnstileToken(string $key)
+    {
+        return Arr::get($this->data ?? $this->form?->getFormSnapshot(), $key);
+    }
+
+    /**
+     * Retrieves the token challenge.
+     */
+    protected function retrieveTurnstileChallenge(Turnstile $turnstile, string $token): ?Challenge
+    {
+        return $turnstile->getChallenge($token);
+    }
+
+    /**
+     * Handles the Turnstile challenge and returns true or false if it has succeeded or failed.
+     */
+    protected function handleTurnstileChallengeStatus(Challenge $challenge): bool
+    {
+        return $challenge->successful;
+    }
+
+    /**
+     * Handle a successful Turnstile challenge.
+     */
+    protected function handleSuccessfulTurnstileChallenge(Challenge $challenge): void
+    {
+        //
+    }
+
+    /**
+     * Handle a failed Turnstile challenge.
+     */
+    protected function handleFailedTurnstileChallenge(?Challenge $challenge = null): void
+    {
+        $this->notifyFailedTurnstileChallenge($challenge);
+        $this->throwTurnstileValidationError($challenge);
+    }
+
+    /**
+     * Send a notification to the user if the challenge has failed.
+     */
+    protected function notifyFailedTurnstileChallenge(?Challenge $challenge = null): void
+    {
+        Notification::make('turnstile-challenge')
+            ->title(__('turnstile::notification.failed.title'))
+            ->body(__('turnstile::notification.failed.body'))
+            ->danger()
+            ->send();
+    }
+
+    /**
+     * Throw a Validation exception for the failed Turnstile challenge.
+     */
+    protected function throwTurnstileValidationError(?Challenge $challenge = null): never
+    {
+        throw ValidationException::withMessages([
+            Turnstile::KEY => __('turnstile::validation.invalid'),
+        ]);
+    }
+
+    /**
+     * Handle a Turnstile challenge exception.
+     *
+     * @return void|never
+     */
+    protected function handleTurnstileException(Throwable $exception)
+    {
+        throw $exception;
+    }
+}