You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+77-8Lines changed: 77 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -107,7 +107,7 @@ Finally, you can also set a custom callback name to be executed once the script
107
107
108
108
#### Site Key on JavaScript frontend
109
109
110
-
If you put the script on the `<head>` part of your HTML view, you may set the `meta` attribute to render a `<meta>` tag alongside the script. This tag will contain your Turnstile sitekey so your JavaScript frontend can retrieve use it to render the widget.
110
+
If you put the script on the `<head>` part of your HTML view, you may set the `meta` attribute to render a `<meta>` tag alongside the script. This tag will contain your Turnstile site-key so your JavaScript frontend can use it to render the widget.
111
111
112
112
```blade
113
113
<!DOCTYPE html>
@@ -161,11 +161,24 @@ Alternatively, you may set a custom name for the tag by setting a value to the `
You can also add a [resource hint to Cloudflare servers](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/#2-optional-optimize-performance-with-resource-hints) by setting the `preconnect` attribute in the component.
> Remember that the Widget Mode is controlled via your [Cloudflare Dashboard](https://dash.cloudflare.com), not here. On development, this is controlled with [testing keys](#testing-keys).
181
+
> Remember that the Widget Mode is controlled via your [Cloudflare Dashboard](https://dash.cloudflare.com), not here. In development, this is controlled with [testing keys](#testing-keys).
169
182
170
183
You can use the `<x-turnstile::widget />` Blade Component to add the Turnstile Widget in your forms. Depending on the Widget Mode, the Widget may render as usual or be invisible at Turnstile discretion.
If you're using Liveware or Filament PHP, you may use the `Laragear\Turnstile\Livewire\InteractsWithTurnstile` trait in your Filament Pages or components.
858
+
If you're using Liveware, you may use the `Laragear\Turnstile\Livewire\InteractsWithTurnstile` trait in your Livewire pages or components.
846
859
847
860
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.
848
861
862
+
For example, you can use it on Filament custom pages to handle form submission.
863
+
849
864
```php
850
865
use Filament\Forms\Concerns\InteractsWithForms;
851
866
use Filament\Forms\Contracts\HasForms;
@@ -881,10 +896,6 @@ protected function turnstileToken(string $key)
881
896
}
882
897
```
883
898
884
-
> [!IMPORTANT]
885
-
>
886
-
> 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).
887
-
888
899
### Handling the Turnstile Challenge
889
900
890
901
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:
@@ -917,6 +928,64 @@ protected function handleTurnstileChallengeStatus(Challenge $challenge): bool
917
928
}
918
929
```
919
930
931
+
## Filament Widget Field
932
+
933
+
If you're using Filament, you may use the `Laragear\Turnstile\Filament\Forms\TurnstileWidget` field in your forms. It will automatically inject the Turnstile Script in the page and render the Turnstile Widget. The Turnstile Challenge will be validated only on complete form submission.
934
+
935
+
```php
936
+
use Filament\Forms\Components\Textarea;
937
+
use Filament\Forms\Components\TextInput;
938
+
use Filament\Forms\Concerns\InteractsWithForms;
939
+
use Filament\Forms\Contracts\HasForms;
940
+
use Filament\Pages\Page;
941
+
use Filament\Schemas\Schema;
942
+
use Laragear\Turnstile\Filament\Forms\TurnstileWidget;
943
+
use Laragear\Turnstile\Livewire\InteractsWithTurnstile;
944
+
945
+
class ContactPage extends Page implements HasForms
946
+
{
947
+
use InteractsWithForms;
948
+
use InteractsWithTurnstile;
949
+
950
+
public function form(Schema $schema) : Schema
951
+
{
952
+
return $schema->components([
953
+
TextInput::make('subject')->required(),
954
+
Textarea::make('message')->required(),
955
+
// Add the Turnstile Widget
956
+
TurnstileWidget::make(),
957
+
]);
958
+
}
959
+
}
960
+
```
961
+
962
+
The Widget includes some convenient methods based on the [Cloudflare Turnstile Widget configuration](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/widget-configurations/):
|`normal()`| Sets the size of the widget to normal. |
967
+
|`flexible()`| Sets the size of the widget to flexible. |
968
+
|`compact()`| Sets the size of the widget to compact. |
969
+
|`system()`| Sets the theme of the widget to system/browser default. |
970
+
|`light()`| Sets the theme of the widget to light. |
971
+
|`dark()`| Sets the theme of the widget to dark. |
972
+
|`appearanceAlways()`| Sets the appearance of the widget to always appear. |
973
+
|`appearanceExecute()`| Sets the appearance of the widget to appear on manual execution. |
974
+
|`appearanceInteractionOnly()`| Sets the appearance of the widget to appear only when required. |
975
+
|`executionRender()`| Sets the execution of the widget challenge as it renders. |
976
+
|`executionExecute()`| Sets the execution of the widget challenge on manual execution. |
977
+
|`languageAuto()`| Sets the language of the widget to browser locale. |
978
+
|`language(string $lang)`| Sets the language of the widget to given locale. |
979
+
|`languageApp()`| Sets the language of the widget to application locale. |
980
+
|`tabindex(int $tabindex)`| Sets the tab order of the widget to one set. |
981
+
|`callback(string $functionName)`| Adds an additional function names to execute on successful challenges. |
982
+
|`actionName(string $functionName)`| Sets the action name for the challenge. |
983
+
|`implicit(bool $condition = true)`| Makes the widget be rendered automatically by the script. |
984
+
985
+
> [!IMPORTANT]
986
+
>
987
+
> The Filament Turnstile Widget is rendered **implicitly** by default, meaning its rendering is handled internally by AlpineJS. This makes all the options to be passed as a JavaScript object. You can use **explicit** rendering, but you may have problems if Livewire or Filament are configured to run in [SPA mode](https://filamentphp.com/docs/5.x/panel-configuration#spa-mode) or [use islands](https://livewire.laravel.com/docs/4.x/islands).
988
+
920
989
## Advanced configuration
921
990
922
991
Laragear Turnstile is intended to work out-of-the-box, but you can publish the configuration file for fine-tuning the Challenge verification.
0 commit comments