### Example View Reference

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/service-provider.md

Demonstrates how to reference a view provided by the package using its registered namespace.

```php
view('turnstile::components.turnstile')
```

--------------------------------

### Field Configuration Example

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/REFERENCE.md

Example of how to configure the Turnstile field within your application.

```APIDOC
## Field Configuration

### Example
```php
Turnstile::make('captcha')
    ->theme('light' | 'dark' | 'auto')    // Default: 'auto'
    ->size('normal' | 'compact')           // Default: 'normal'
    ->language('en-us' | 'fr' | 'de' |...) // Default: 'en-us'
```
```

--------------------------------

### Install Filament Turnstile

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/QUICKSTART.md

Install the package using Composer. Ensure you are using version ^4.0.

```bash
composer require coderflex/filament-turnstile "^4.0"
```

--------------------------------

### Full Example: Login Page with Turnstile

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/QUICKSTART.md

A complete example of a Filament login page incorporating the Turnstile component and custom validation error handling.

```php
namespace App\Filament\Pages\Auth;

use Coderflex\FilamentTurnstile\Forms\Components\Turnstile;
use Filament\Pages\Auth\Login as AuthLogin;
use Filament\Schemas\Schema;
use Illuminate\Validation\ValidationException;

class Login extends AuthLogin
{
    public function form(Schema $form): Schema
    {
        return $form
            ->schema([
                $this->getEmailFormComponent(),
                $this->getPasswordFormComponent(),
                $this->getRememberFormComponent(),
                Turnstile::make('captcha')
                    ->theme('auto'),
            ]);
    }

    protected function throwFailureValidationException(): never
    {
        $this->dispatch('reset-captcha');
        parent::throwFailureValidationException();
    }
}
```

--------------------------------

### Facade Registration Example

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/REFERENCE.md

Shows how the FilamentTurnstile facade is registered in composer.json. This facade is not actively used by the package.

```php
'FilamentTurnstile' => 'Coderflex\FilamentTurnstile\Facades\FilamentTurnstile'
```

--------------------------------

### Install Filament Turnstile for Filament V3

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/README.md

Use this command to install the version of Filament Turnstile compatible with Filament V3.

```bash
composer require coderflex/filament-turnstile "^2.0"
```

--------------------------------

### Install Filament Turnstile for Filament V2

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/README.md

Use this command to install the version of Filament Turnstile compatible with Filament V2.

```bash
composer require coderflex/filament-turnstile "^1.0"
```

--------------------------------

### Example .env File Configuration

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/configuration.md

A sample .env file demonstrating the inclusion of Turnstile configuration variables alongside other Laravel application settings.

```env
APP_NAME=Laravel
APP_ENV=local
APP_DEBUG=true

# Turnstile Configuration
TURNSTILE_SITE_KEY=1x00000000000000000000AA
TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
```

--------------------------------

### Install Filament Turnstile for Filament V4

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/README.md

Use this command to install the version of Filament Turnstile compatible with Filament V4.

```bash
composer require coderflex/filament-turnstile "^3.0"
```

--------------------------------

### Method Chaining Example

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Illustrates the use of fluent method chaining to configure field properties declaratively. All inherited methods support chaining.

```APIDOC
## Method Chaining

### Description
All inherited methods support fluent method chaining, allowing you to configure the field declaratively.

### Request Example
```php
Turnstile::make('captcha')
    ->label('Verify you are human')
    ->required()
    ->theme('dark')
    ->size('normal')
    ->language('en-us')
```
```

--------------------------------

### Form Schema Definition with Turnstile

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/types.md

Example of integrating the Turnstile component into a Filament form schema. Ensure the Turnstile class is imported.

```php
use Filament\Schemas\Schema;

public function form(Schema $form): Schema
{
    return $form->schema([
        Turnstile::make('captcha'),
    ]);
}
```

--------------------------------

### Production Environment Variables

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/configuration.md

Example of production environment variables for Turnstile, using actual keys obtained from the Cloudflare Dashboard. Ensure these are kept secure.

```env
# Use production keys from Cloudflare Dashboard
TURNSTILE_SITE_KEY=1xAbCdEfGhIjKlMnOpQrStUvWxYz123456
TURNSTILE_SECRET_KEY=1xAbCdEfGhIjKlMnOpQrStUvWxYz123456789012345678901234
```

--------------------------------

### Implement Turnstile on Filament Login Page

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/README.md

Create a custom Login page in App/Filament/Pages/Auth/Login.php to include the Turnstile captcha component in the login form schema. This example shows how to add the Turnstile component and configure its label and theme. It also includes a method to reset the captcha on validation errors.

```php
namespace App\Filament\Pages\Auth;

use Coderflex\FilamentTurnstile\Forms\Components\Turnstile;
use Filament\Pages\Auth\Login as AuthLogin;
use Filament\Schemas\Schema;

class Login extends AuthLogin
{
    public function form(Schema $form): Schema
    {
        return $form
            ->schema([
                $this->getEmailFormComponent(),
                $this->getPasswordFormComponent(),
                $this->getRememberFormComponent(),
                Turnstile::make('captcha')
                    ->label('Captcha')
                    ->theme('auto'),
            ]);
    }

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

        parent::throwFailureValidationException();
    }
}
```

--------------------------------

### required(): static

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Marks the field as required. This method is inherited from the Field base class and is automatically applied by Turnstile's setUp method.

```APIDOC
## required()

### Description
Marks the field as required. This is automatically applied by Turnstile's setUp method.

### Method
Validation Method

### Returns
#### Success Response (static)
- **static** - Returns the component instance for method chaining.

### Request Example
```php
Turnstile::make('captcha')
    ->required()  // Already applied by default
```
```

--------------------------------

### Basic Turnstile Field Implementation

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/turnstile-field-component.md

Use this basic implementation to add a Turnstile CAPTCHA field to your form. Ensure the Coderflex
FilamentTurnstile package is installed.

```php
use Coderflex\FilamentTurnstile\Forms\Components\Turnstile;

Turnstile::make('captcha')
```

--------------------------------

### rule(Rule | string $rule, Rule | string ...$rules)

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Applies validation rules to the field. The Turnstile field automatically applies the TurnstileCheck rule during setUp.

```APIDOC
## rule(Rule | string $rule, Rule | string ...$rules)

### Description
Applies validation rules to the field. The Turnstile field automatically applies `TurnstileCheck` rule during setUp.

### Method
Validation Method

### Parameters
#### Path Parameters
- **rule** (Rule | string) - Required - A rule instance or string
- **...rules** (Rule | string) - Optional - Additional rules

### Returns
#### Success Response (static)
- **static** - Returns the component instance for method chaining.

### Request Example
```php
use Coderflexx\FilamentTurnstile\Rules\TurnstileCheck;

Turnstile::make('captcha')
    ->rule(new TurnstileCheck)  // Already applied by default
    ->rule('unique:contacts')   // Additional rule
```

### Default Rule
`new TurnstileCheck` (applied automatically)
```

--------------------------------

### Access Facade (PHP)

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/MODULES.md

Demonstrates how to access the FilamentTurnstile facade. Note that this facade is not currently functional and is available for future extensibility.

```php
use FilamentTurnstile;

// Currently not functional
```

--------------------------------

### Configure Package Metadata and Assets

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/service-provider.md

This method configures the package's name and registers its views. Use this to set up the package's identity and make its views accessible.

```php
protected function configurePackage(Package $package): void
{
    $package
        ->name('filament-turnstile')
        ->hasViews('turnstile');
}
```

--------------------------------

### Resetting CAPTCHA on Validation Error

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/turnstile-field-component.md

Example of how to dispatch the 'reset-captcha' event within the onValidationError method to reset the CAPTCHA widget when validation fails.

```php
protected function onValidationError(ValidationException $exception): void
{
    $this->dispatch('reset-captcha');
}
```

--------------------------------

### Turnstile Component with Full Qualification

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/MODULES.md

Demonstrates using the Turnstile component with its fully qualified namespace.

```php
\Coderflex\FilamentTurnstile\Forms\Components\Turnstile::make('captcha')
```

--------------------------------

### Run Tests with Composer

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/README.md

Execute the test suite for the Filament Turnstile package using Composer.

```bash
composer test
```

--------------------------------

### Package Discovery Configuration

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/MODULES.md

Details the service provider and facade aliases for automatic package discovery in Laravel.

```json
{
  "extra": {
    "laravel": {
      "providers": [
        "Coderflex\FilamentTurnstile\FilamentTurnstileServiceProvider"
      ],
      "aliases": {
        "FilamentTurnstile": "Coderflex\FilamentTurnstile\Facades\FilamentTurnstile"
      }
    }
  }
}
```

--------------------------------

### Publish Package Views with Artisan

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/service-provider.md

Use this Artisan command to publish the package's views to your application's resources directory, allowing for customization.

```bash
php artisan vendor:publish --provider="Coderflex\FilamentTurnstile\FilamentTurnstileServiceProvider" --tag="views"
```

--------------------------------

### Required Site Key Environment Variable

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/configuration.md

Set the TURNSTILE_SITE_KEY environment variable with your Cloudflare Turnstile site key. This is a 32-character alphanumeric string starting with '1x' or '2x'.

```env
TURNSTILE_SITE_KEY=1x00000000000000000000AA
```

--------------------------------

### Turnstile Component with Custom Alias

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/MODULES.md

Illustrates importing the Turnstile component and assigning it a custom alias for brevity.

```php
use Coderflex\FilamentTurnstile\Forms\Components\Turnstile as CaptchaField;

CaptchaField::make('captcha')
```

--------------------------------

### Package Architecture

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/REFERENCE.md

Illustrates the directory structure of the filament-turnstile package, highlighting key files and their purposes.

```text
filament-turnstile/
├── src/
│   ├── FilamentTurnstileServiceProvider.php    # Package service provider
│   └── Forms/Components/
│       └── Turnstile.php                       # Main CAPTCHA field component
├── resources/views/
│   └── components/
│       └── turnstile.blade.php                 # Blade template (Alpine.js)
├── composer.json                               # Package metadata
└── ...
```

--------------------------------

### Get Turnstile Widget Properties in Blade

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/blade-template.md

Obtain the current theme, size, and language settings of the Turnstile widget using its getter methods within a Blade view.

```blade
{{ $getTheme() }}
{{ $getSize() }}
{{ $getLanguage() }}
```

--------------------------------

### CAPTCHA Token Form Data Example

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/types.md

Illustrates how the CAPTCHA token is represented as a string within form data. This token is validated server-side by the `TurnstileCheck` rule and is not persisted to the database.

```php
// Field name: any string, typically 'captcha' or 'cfCaptcha'
// Field value type: string (CAPTCHA token from Cloudflare)
// Stored in: Form state/Livewire property
// Example structure:

$data = [
    'email' => 'user@example.com',
    'password' => 'secret',
    'captcha' => 'XXXX.DUMMY.TOKEN.XXXX',  // ← Token string
];
```

--------------------------------

### Setting Field Label

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Demonstrates how to set the field label displayed to the user using the `label` method. It supports string values, closures for dynamic labels, or null to use the default.

```APIDOC
## label(string | Closure | null $label): static

### Description
Sets the field label displayed to the user.

### Parameters
#### Path Parameters
- **label** (string|Closure|null) - Required - The display label

### Request Example
```php
Turnstile::make('captcha')
    ->label('Security Check')

// Or with closure
->label(fn() => __('captcha.label'))

// Empty label (default for Turnstile)
->label('')
```

### Response
#### Success Response (static)
Returns `static` for method chaining.
```

--------------------------------

### Evaluate Closures or Static Values

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Demonstrates the use of the `evaluate()` method, available to all fields, for processing closures or static values internally. This is crucial for evaluating configuration options like theme, size, and language.

```php
protected function setUp(): void
{
    parent::setUp();
    
    // Used internally to evaluate configuration
    $theme = $this->evaluate($this->theme);
}
```

--------------------------------

### Turnstile Field in a Form Schema

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/turnstile-field-component.md

Integrate the Turnstile field within a Filament form schema alongside other form components. This example shows how to add it with specific theme and language configurations.

```php
use Coderflex\FilamentTurnstile\Forms\Components\Turnstile;
use Filament\Forms;
use Filament\Schemas\Schema;

public function form(Schema $form): Schema
{
    return $form
        ->schema([
            Forms\Components\TextInput::make('email')
                ->label('Email')
                ->required(),
            Forms\Components\TextInput::make('password')
                ->label('Password')
                ->required()
                ->password(),
            Turnstile::make('captcha')
                ->theme('auto')
                ->language('en-us'),
        ]);
}
```

--------------------------------

### Customize Turnstile Widget Colors in Blade

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/blade-template.md

Modify the appearance of the Turnstile widget by adding custom CSS within the vendor's Blade component file. This example targets light and dark themes.

```blade
<style>
    [data-theme="light"] {
        background: #f0f0f0;
    }
    [data-theme="dark"] {
        background: #1a1a1a;
    }
</style>
```

--------------------------------

### FilamentTurnstileServiceProvider Usage

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/MODULES.md

The FilamentTurnstileServiceProvider is automatically bootstrapped by Laravel. No manual registration is required.

```php
// Automatically bootstrapped by Laravel
// No manual registration needed
```

--------------------------------

### Size Options

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/types.md

Configuration for the size of the Turnstile widget.

```APIDOC
## Size Options

### Description
Sets the size of the Turnstile widget.

### Method
`size(string $option): static`

### Parameters
#### Query Parameters
- **size** (SizeOption) - Required - The size to apply.

### Valid Values
- `'normal'` — Standard size (default)
- `'compact'` — Compact size

### Example
```php
use Filament	urnstile	urnstile;

Turnstile::make('captcha')->size('normal');
```
```

--------------------------------

### Required Secret Key Environment Variable

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/configuration.md

Set the TURNSTILE_SECRET_KEY environment variable with your Cloudflare Turnstile secret key for server-side validation. This key must be 32 or more characters long and start with '1x' or '2x'.

```env
TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
```

--------------------------------

### Turnstile Testing Keys

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/REFERENCE.md

Use these dummy keys for testing Cloudflare Turnstile integration. One set always passes, the other always fails.

```env
# Always passes
TURNSTILE_SITE_KEY=1x00000000000000000000AA
TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA

# Always fails
TURNSTILE_SITE_KEY=2x00000000000000000000AB
TURNSTILE_SECRET_KEY=2x0000000000000000000000000000000AA
```

--------------------------------

### Adding Turnstile to a Filament Form Component

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/service-provider.md

Use the Turnstile::make('captcha') component within your Filament form schema to add the Turnstile captcha field. This example shows its placement alongside other input fields.

```php
namespace App\Filament\Resources\LoginResource\Pages;

use Coderflex\FilamentTurnstile\Forms\Components\Turnstile;
use Filament\Forms\Components\TextInput;
use Filament\Schemas\Schema;

class LoginPage extends Page
{
    public function form(Schema $form): Schema
    {
        return $form
            ->schema([
                TextInput::make('email'),
                TextInput::make('password')->password(),
                Turnstile::make('captcha'),
            ]);
    }
}
```

--------------------------------

### Register Package Views

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/service-provider.md

Registers the directory containing the package's views. Views are published to `resources/views/vendor/turnstile/` and can be overridden.

```php
->hasViews('turnstile')
```

--------------------------------

### Turnstile Configuration Structure

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/types.md

The default structure for the `turnstile.php` configuration file. It maps configuration keys to environment variables.

```php
return [
    'turnstile_site_key' => env('TURNSTILE_SITE_KEY'),
    'turnstile_secret_key' => env('TURNSTILE_SECRET_KEY'),
];
```

--------------------------------

### Initialize Turnstile Field

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/turnstile-field-component.md

Use the make() static method to create a new Turnstile field instance. The 'fieldName' parameter is required and used to store the CAPTCHA token.

```php
Turnstile::make('fieldName')
```

--------------------------------

### Composer Extra Configuration for Facade

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/service-provider.md

This JSON configuration in composer.json registers the FilamentTurnstile facade, making it available for use in your application.

```json
{
  "extra": {
    "laravel": {
      "aliases": {
        "FilamentTurnstile": "Coderflex\FilamentTurnstile\Facades\FilamentTurnstile"
      }
    }
  }
}
```

--------------------------------

### Accessing Turnstile Configuration

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/types.md

Demonstrates how to access the Turnstile site key and secret key from Laravel's configuration array. These values are typically set in the `.env` file.

```php
config('turnstile.turnstile_site_key'): string
config('turnstile.turnstile_secret_key'): string
```

--------------------------------

### Fluent Method Chaining for Turnstile Configuration

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Configure the Turnstile field declaratively using fluent method chaining for various properties like label, required status, theme, size, and language.

```php
Turnstile::make('captcha')
    ->label('Verify you are human')
    ->required()
    ->theme('dark')
    ->size('normal')
    ->language('en-us')
```

--------------------------------

### Registering Turnstile in a Filament Panel Provider

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/service-provider.md

Include this code in your Filament PanelProvider to automatically bootstrap the Turnstile package. No further configuration is needed within the panel itself.

```php
namespace App\Providers\Filament;

use Filament\Panel;
use Filament\PanelProvider;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->default()
            ->id('admin')
            ->path('admin')
            // Package is automatically bootstrapped
            ;
    }
}
```

--------------------------------

### Testing Configuration: Always-Fail Keys

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/configuration.md

Use these dummy environment variables to test failed CAPTCHA verification. Any token value will fail validation with these keys, useful for testing error handling.

```env
TURNSTILE_SITE_KEY=2x00000000000000000000AB
TURNSTILE_SECRET_KEY=2x0000000000000000000000000000000AA
```

--------------------------------

### Create Turnstile Field Instance

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Use the `make` method to create a new instance of the Turnstile component, specifying its unique name.

```php
Turnstile::make('captcha')
```

--------------------------------

### Test Autoload Configuration

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/MODULES.md

Defines the PSR-4 autoloading for the test namespace.

```json
{
  "autoload-dev": {
    "psr-4": {
      "Coderflex\FilamentTurnstile\Tests\": "tests/"
    }
  }
}
```

--------------------------------

### Configure Filament Panel Provider with Custom Login

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/REFERENCE.md

Configures the Filament panel provider to use a custom login page that includes the Turnstile CAPTCHA. This sets the default panel, ID, path, and the custom login class.

```php
namespace App\Filament\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);
    }
}
```

--------------------------------

### make(string $name)

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Creates a new instance of the Turnstile component. This is a factory method inherited from the base Field class.

```APIDOC
## make(string $name)

### Description
Creates and returns a new instance of the component.

### Method
Factory Method

### Parameters
#### Path Parameters
- **name** (string) - Required - The field name

### Request Example
```php
Turnstile::make('captcha')
```

### Response
#### Success Response (static)
- **instance** (Turnstile) - A new instance of the Turnstile component.
```

--------------------------------

### Theme Options

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/types.md

Configuration for the visual theme of the Turnstile widget.

```APIDOC
## Theme Options

### Description
Sets the visual theme for the Turnstile widget.

### Method
`theme(string $option): static`

### Parameters
#### Query Parameters
- **theme** (ThemeOption) - Required - The theme to apply.

### Valid Values
- `'light'` — Light theme
- `'dark'` — Dark theme
- `'auto'` — Automatic (default)

### Example
```php
use Filament	urnstile	urnstile;

Turnstile::make('captcha')->theme('auto');
```
```

--------------------------------

### Form Component Methods

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/REFERENCE.md

Provides methods for creating and configuring the Turnstile form component.

```APIDOC
## Form Component Methods

### `make()`

#### Description
Creates a new instance of the Turnstile component.

#### Method
`static make(string $name): Turnstile`

### `theme()`

#### Description
Sets the visual theme for the Turnstile widget.

#### Method
`theme(string $theme): static`

### `size()`

#### Description
Sets the size of the Turnstile widget.

#### Method
`size(string $size): static`

### `language()`

#### Description
Sets the display language for the Turnstile widget.

#### Method
`language(string $language): static`

### `getTheme()`

#### Description
Retrieves the currently set theme for the Turnstile widget.

#### Method
`getTheme(): string`

### `getSize()`

#### Description
Retrieves the currently set size for the Turnstile widget.

#### Method
`getSize(): string`

### `getLanguage()`

#### Description
Retrieves the currently set language for the Turnstile widget.

#### Method
`getLanguage(): string`
```

--------------------------------

### PSR-4 Autoloading Configuration

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/MODULES.md

This JSON snippet shows the PSR-4 autoloading configuration in composer.json, mapping the package's namespace to its source directory.

```json
{
  "autoload": {
    "psr-4": {
      "Coderflex\\FilamentTurnstile\\": "src/"
    }
  }
}
```

--------------------------------

### Configure Cloudflare Keys in .env

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/QUICKSTART.md

Add your Cloudflare Site Key and Secret Key to your .env file for Turnstile integration.

```env
TURNSTILE_SITE_KEY=1x00000000000000000000AA
TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
```

--------------------------------

### Configure Turnstile Theme

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/QUICKSTART.md

Set the theme for the Turnstile widget. Options include 'auto', 'light', and 'dark'.

```php
->theme('auto')    // Matches system preference (default)
->theme('light')   // Light theme
->theme('dark')    // Dark theme
```

--------------------------------

### Set Package Name

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/service-provider.md

Sets the unique identifier for the package. This impacts asset publishing, configuration file locations, and view namespaces.

```php
->name('filament-turnstile')
```

--------------------------------

### Service Provider

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/MANIFEST.txt

Details on the Coderflex\FilamentTurnstile\FilamentTurnstileServiceProvider class, primarily focusing on package configuration.

```APIDOC
## Service Provider API

This section covers the `FilamentTurnstileServiceProvider` and its role in configuring the package.

### Methods

- **configurePackage()**: This method is responsible for setting up the Filament Turnstile package, including loading configurations and publishing assets.
```

--------------------------------

### Check Turnstile Site Key Configuration in Blade

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/blade-template.md

Verify if the Turnstile site key is configured. If not set, config('turnstile.turnstile_site_key') will return null, potentially causing the widget to fail silently.

```blade
config('turnstile.turnstile_site_key') // Returns null
```

--------------------------------

### Handle Token Callback

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/blade-template.md

This callback function is executed upon successful CAPTCHA verification. It sets the received token into the Livewire component's state.

```javascript
callback: function (token) {
    $wire.set('{{ $statePath }}', token)
}
```

--------------------------------

### Initialize Turnstile Widget on Load

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/blade-template.md

This function is called when the Cloudflare Turnstile script is loaded. It should be used to initiate the rendering of the widget.

```javascript
window.onTurnstileLoad = () => {
    renderWidget();
}
```

--------------------------------

### Field-Level Theme Configuration

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/configuration.md

Configure the visual theme of the Turnstile widget using the 'theme' method. Options include 'auto', 'light', and 'dark'. 'auto' matches the system preference by default.

```php
Turnstile::make('captcha')
    ->theme('auto')  // or 'light', 'dark'
```

--------------------------------

### Livewire Communication with Blade

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/blade-template.md

Shows how to update Livewire component state and listen for events from within a Blade template using Livewire's JavaScript API.

```javascript
$wire.set('{{ $statePath }}', value)  // Update state
$wire.on('reset-captcha', callback)   // Listen for events
```

--------------------------------

### Language Options

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/types.md

Configuration for the display language of the Turnstile widget.

```APIDOC
## Language Options

### Description
Sets the display language for the Turnstile widget.

### Method
`language(string $code): static`

### Parameters
#### Query Parameters
- **language** (string) - Required - The ISO language code.

### Valid Values
Any ISO 639 language code supported by Cloudflare. Common examples:
- `'en-us'` — English (US) (default)
- `'en-gb'` — English (UK)
- `'fr'` — French
- `'de'` — German
- `'es'` — Spanish
- `'ja'` — Japanese
- `'zh-cn'` — Chinese (Simplified)
- `'zh-tw'` — Chinese (Traditional)
- `'ar'` — Arabic
- `'pt-br'` — Portuguese (Brazil)
- `'pt-pt'` — Portuguese (Portugal)
- `'ru'` — Russian

[Full language list](https://developers.cloudflare.com/turnstile/reference/supported-languages/)

### Example
```php
use Filament	urnstile	urnstile;

Turnstile::make('captcha')->language('en-us');
```
```

--------------------------------

### Composer Extra Configuration for Service Provider

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/service-provider.md

This JSON configuration in composer.json enables automatic discovery and registration of the Filament Turnstile service provider by Laravel.

```json
{
  "extra": {
    "laravel": {
      "providers": [
        "Coderflex\FilamentTurnstile\FilamentTurnstileServiceProvider"
      ]
    }
  }
}
```

--------------------------------

### Turnstile Component API

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/MANIFEST.txt

Documentation for the Coderflex\FilamentTurnstile\Forms\Components\Turnstile class, covering its available methods for customization.

```APIDOC
## Turnstile Component API

This section details the public methods available on the `Turnstile` component for customization.

### Methods

- **make()**: Creates a new instance of the Turnstile component.
- **theme(string $theme)**: Sets the theme for the Turnstile widget. Accepts 'light' or 'dark'.
- **size(string $size)**: Sets the size of the Turnstile widget. Accepts 'normal' or 'compact'.
- **language(string $language)**: Sets the language for the Turnstile widget. Accepts standard language codes (e.g., 'en', 'fr').

### Getters

- **getTheme()**: Returns the currently set theme.
- **getSize()**: Returns the currently set size.
- **getLanguage()**: Returns the currently set language.
```

--------------------------------

### Configure Turnstile Size

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/QUICKSTART.md

Adjust the size of the Turnstile widget. Options are 'normal' (default) and 'compact'.

```php
->size('normal')   // Standard size (default)
->size('compact')  // Compact size
```

--------------------------------

### Turnstile Component Initialization

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/turnstile-field-component.md

Initializes the Turnstile component with a given field name. This is the base method for creating a Turnstile field.

```APIDOC
## Turnstile::make()

### Description
Initializes the Turnstile component with a unique field name.

### Method
`static make(string $name)`

### Parameters
#### Path Parameters
- **name** (string) - Required - The field name used to store the CAPTCHA token.

### Returns
`Turnstile` instance
```

--------------------------------

### Turnstile Widget Configuration Options

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/blade-template.md

Defines the configuration object for the Cloudflare Turnstile widget, including sitekey, theme, size, language, and callbacks for success and error events.

```javascript
let options = {
    sitekey: '{{ config('turnstile.turnstile_site_key') }}',
    theme: '{{ $theme }}',
    size: '{{ $size }}',
    language: '{{ $language }}',
    callback: function (token) {
        $wire.set('{{ $statePath }}', token)
    },
    'error-callback': function () {
        $wire.set('{{ $statePath }}', null)
    }
}
```

--------------------------------

### Setting CAPTCHA Theme

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/turnstile-field-component.md

Configures the visual theme of the CAPTCHA widget. Supports 'light', 'dark', and 'auto' modes.

```APIDOC
## theme(string $theme)

### Description
Sets the CAPTCHA widget theme to control its appearance.

### Method
`theme(string $theme): static`

### Parameters
#### Path Parameters
- **theme** (string) - Required - Theme mode: 'light', 'dark', or 'auto'. Defaults to 'auto'.

### Returns
`static` (for method chaining)

### Example
```php
Turnstile::make('captcha')
    ->theme('dark')
```
```

--------------------------------

### Accessing Turnstile Field Configuration

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Retrieve configuration values like theme, size, and language from the Turnstile field component using getter methods.

```php
$theme = $component->getTheme();      // 'auto'
$size = $component->getSize();        // 'normal'
$language = $component->getLanguage(); // 'en-us'
```

--------------------------------

### Lazy Load Turnstile Script

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/blade-template.md

Use `x-load-js` to defer the loading of the Turnstile API script until Alpine.js mounts the component, improving initial page load performance.

```blade
x-load-js="['https://challenges.cloudflare.com/turnstile/v0/api.js?...']"
```

--------------------------------

### Data Binding with Livewire

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Details how the Turnstile field utilizes Livewire's data binding for automatic token updates in the form state upon CAPTCHA completion.

```APIDOC
## Data Binding

### Description
The Turnstile field uses Livewire's data binding.

### Request Example
```php
// In the Blade template
$wire.entangle('{{ $statePath }}').defer
```

### Response
#### Success Response
The token is automatically updated in the form state when the CAPTCHA is completed.
```

--------------------------------

### Register Custom Login Page

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/QUICKSTART.md

Register your custom login page, which includes the Turnstile component, in your `AdminPanelProvider`.

```php
public function panel(Panel $panel): Panel
{
    return $panel
        ->default()
        ->id('admin')
        ->path('admin')
        ->login(Login::class);
}
```

--------------------------------

### Field Configuration for Turnstile Component

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/REFERENCE.md

Configure the Turnstile component within your Filament forms. Options include setting the theme, size, and language for the CAPTCHA widget. Defaults are provided for each option.

```php
Turnstile::make('captcha')
    ->theme('light' | 'dark' | 'auto')    // Default: 'auto'
    ->size('normal' | 'compact')           // Default: 'normal'
    ->language('en-us' | 'fr' | 'de' |...) // Default: 'en-us'
```

--------------------------------

### Configure Turnstile Language

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/QUICKSTART.md

Set the display language for the Turnstile widget. Supports over 40 languages.

```php
->language('en-us')   // English (default)
->language('fr')      // French
->language('de')      // German
->language('es')      // Spanish
->language('ja')      // Japanese
// ... and 40+ more languages
```

--------------------------------

### Component Nesting

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Lists the contexts where the Turnstile field can be utilized within form structures.

```APIDOC
## Component Nesting

### Description
The Turnstile field can be used in:

### Request Example
- **Schemas:** `$form->schema([Turnstile::make('captcha')])`
- **Sections:** `Section::make()->schema([Turnstile::make('captcha')])`
- **Tabs:** `Tab::make()->schema([Turnstile::make('captcha')])`
- **Fieldsets:** `Fieldset::make()->schema([Turnstile::make('captcha')])`
```

--------------------------------

### Filament Turnstile Service Provider

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/types.md

The service provider for the Filament Turnstile package, extending `PackageServiceProvider`. It is used to configure the package.

```php
class FilamentTurnstileServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
}
```

--------------------------------

### Field-Level Size Configuration

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/configuration.md

Set the size of the Turnstile widget using the 'size' method. Choose between 'normal' for the standard widget or 'compact' for an inline version. 'normal' is the default.

```php
Turnstile::make('captcha')
    ->size('normal')  // or 'compact'
```

--------------------------------

### Initialize Alpine.js Component for Turnstile

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/blade-template.md

This Alpine.js component is used for the widget container, handling lazy loading of the Cloudflare API script and initializing the widget state.

```blade
<div wire:ignore
     x-load-js="['https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit&onload=onTurnstileLoad']"
     x-data="{...}"
     x-init="(()=>{...})()">

```

--------------------------------

### Cloudflare Turnstile JavaScript API Usage

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/blade-template.md

Demonstrates the core functions of the Cloudflare Turnstile JavaScript API for rendering, retrieving responses, resetting, and removing widgets.

```javascript
// Load the API
window.turnstile

// Render a widget
turnstile.render('#selector', options)

// Get the response
turnstile.getResponse(widgetId)

// Reset widget
turnstile.reset(widgetId)

// Remove widget
turnstile.remove(widgetId)
```

--------------------------------

### Turnstile Field Callbacks

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Implement `afterStateUpdated` and `beforeStateDehydrated` callbacks to hook into the field's lifecycle events for custom logic.

```php
Turnstile::make('captcha')
    ->afterStateUpdated(function ($state) {
        // Called when the CAPTCHA token is received
    })
    ->beforeStateDehydrated(function ($state) {
        // Called before the form is processed
    })
```

--------------------------------

### Turnstile Component Class Definition

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/types.md

Defines the structure and default attributes for the Turnstile component. Use the fluent methods like `theme()`, `size()`, and `language()` to configure its behavior.

```php
class Turnstile extends Field
{
    protected string $viewIdentifier = 'turnstile';
    protected string $view = 'turnstile::components.turnstile';
    protected string $theme = 'auto';
    protected string $size = 'normal';
    protected string $language = 'en-us';
    
    public function theme(string $theme): static
    public function size(string $size): static
    public function language(string $language): static
    public function getTheme(): string
    public function getSize(): string
    public function getLanguage(): string
}
```

--------------------------------

### Setting CAPTCHA Size

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/turnstile-field-component.md

Adjusts the size of the CAPTCHA widget to either 'normal' or 'compact'.

```APIDOC
## size(string $size)

### Description
Sets the CAPTCHA widget size to control its dimensions on the form.

### Method
`size(string $size): static`

### Parameters
#### Path Parameters
- **size** (string) - Required - Widget size: 'normal' or 'compact'. Defaults to 'normal'.

### Returns
`static` (for method chaining)

### Example
```php
Turnstile::make('captcha')
    ->size('compact')
```
```

--------------------------------

### Render Turnstile Widget

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/blade-template.md

Renders the Turnstile widget into a specified DOM element. Ensure the Turnstile API is loaded and the target element exists before calling.

```javascript
const renderWidget = () => {
    if (!window.turnstile || !$refs.turnstile || widgetId !== null) {
        return;
    }
    widgetId = turnstile.render($refs.turnstile, options);
}
```

--------------------------------

### Debug reset-captcha Event in Browser Console

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/errors.md

Use these console logs to debug issues with the `reset-captcha` Livewire event. Ensure `window.turnstile` is defined and `widgetId` is a valid number.

```javascript
// In browser console
console.log(window.turnstile); // Should be defined
console.log(widgetId);          // Should be a number >= 0
```

--------------------------------

### Set Turnstile Widget Size

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/turnstile-field-component.md

Adjust the size of the CAPTCHA widget with the size() method. Options include 'normal' and 'compact'.

```php
Turnstile::make('captcha')
    ->size('compact')
```

--------------------------------

### Events

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/REFERENCE.md

Details the events that can be triggered by the Turnstile component.

```APIDOC
## Events

### `reset-captcha`

#### Description
This event is used to reset the CAPTCHA widget. It is typically triggered via Livewire.

#### Type
Livewire
```

--------------------------------

### getTheme()

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/turnstile-field-component.md

Retrieves the evaluated theme value for the Turnstile component.

```APIDOC
## getTheme()

### Description
Retrieves the evaluated theme value.

### Returns
`string` - The theme setting ('light', 'dark', or 'auto')
```

--------------------------------

### Set Turnstile Widget Theme

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/turnstile-field-component.md

Configure the visual theme of the CAPTCHA widget using the theme() method. Supported themes are 'light', 'dark', and 'auto'.

```php
Turnstile::make('captcha')
    ->theme('dark')
```

--------------------------------

### FilamentTurnstileServiceProvider

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/MODULES.md

The service provider for the Filament Turnstile package. It is automatically registered by Laravel and handles package bootstrapping, view registration, and asset configuration.

```APIDOC
## FilamentTurnstileServiceProvider

### Description

Bootstrap the package, register views, and configure assets.

### Fully Qualified Name

`Coderflex\FilamentTurnstile\FilamentTurnstileServiceProvider`

### Location

`src/FilamentTurnstileServiceProvider.php`

### Type

Class extending `Spatie\LaravelPackageTools\PackageServiceProvider`

### Registration

- Automatically registered via Laravel's package discovery
- Registered in `composer.json` under `extra.laravel.providers`

### Usage

```php
// Automatically bootstrapped by Laravel
// No manual registration needed
```

### Methods

- `configurePackage(Package $package): void` — Configures package metadata
```

--------------------------------

### Add Turnstile CAPTCHA to Filament Login Form

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/REFERENCE.md

Integrates the Turnstile CAPTCHA component into the Filament login form. Ensures the CAPTCHA is displayed and handles token validation.

```php
namespace App\Filament\Pages\Auth;

use Coderflex\FilamentTurnstile\Forms\Components\Turnstile;
use Filament\Pages\Auth\Login as AuthLogin;
use Filament\Schemas\Schema;

class Login extends AuthLogin
{
    public function form(Schema $form): Schema
    {
        return $form
            ->schema([
                $this->getEmailFormComponent(),
                $this->getPasswordFormComponent(),
                Turnstile::make('captcha')->theme('auto'),
            ]);
    }

    protected function throwFailureValidationException(): never
    {
        $this->dispatch('reset-captcha');
        parent::throwFailureValidationException();
    }
}
```

--------------------------------

### Blade Template Variables for Turnstile

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/types.md

Lists the variables available in the Blade view when using the Turnstile component. These include Livewire property paths, getter functions, and component instance details.

```php
$statePath: string              // Livewire property path
$getStatePath(): callable       // Getter function
$fieldWrapperView: string       // Field wrapper component
$getFieldWrapperView(): callable // Getter function
$getTheme(): string             // Theme getter
$getSize(): string              // Size getter
$getLanguage(): string          // Language getter
$turnstile: Turnstile           // Component instance
```

--------------------------------

### Apply Multiple Validation Rules to Turnstile Field

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

The `rules` method allows applying multiple validation rules at once using an array.

```php
Turnstile::make('captcha')
    ->rules([
        'required',
        new TurnstileCheck,
    ])
```

--------------------------------

### Setting CAPTCHA Language

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/turnstile-field-component.md

Specifies the display language for the CAPTCHA widget using ISO language codes.

```APIDOC
## language(string $language)

### Description
Sets the display language for the CAPTCHA widget.

### Method
`language(string $language): static`

### Parameters
#### Path Parameters
- **language** (string) - Required - ISO language code (e.g., 'en-us', 'fr', 'de'). Defaults to 'en-us'.

### Returns
`static` (for method chaining)

### Example
```php
Turnstile::make('captcha')
    ->language('fr')
```
```

--------------------------------

### Field State Property

Source: https://github.com/coderflexx/filament-turnstile/blob/4.x/_autodocs/api-reference/field-inheritance.md

Explains how the field's value is stored in the form state under its name and its type and value.

```APIDOC
## State Property

### Description
The field's value is stored in the form state under its name.

### Request Example
```php
$form->model()->captcha  // ← CAPTCHA token
```

### Response
#### Success Response
- **Type**: `string`
- **Value**: Cloudflare-generated CAPTCHA token
- **Dehydration**: Not saved to model by default
```