Getting Started

Installation Add the package via Composer:

composer require captchaapi/laravel

Publish the config:

php artisan vendor:publish --tag=captchaapi-config

Set credentials in .env:

CAPTCHAAPI_SITE_KEY=pk_live_...
CAPTCHAAPI_SECRET_KEY=sk_live_...

First Use Case: Basic Form Protection

Add the widget to your layout's <head>:
```
<x-captchaapi::widget />
```

Mark your form with data-captcha:

<form method="POST" data-captcha>
    @csrf
    <!-- form fields -->
</form>

Validate the response:

$request->validate([
    'captchaapi_response' => ['required', new \Captchaapi\Laravel\Rules\ValidCaptcha],
]);

Implementation Patterns

1. Livewire Integration

Trait Usage: Use WithCaptcha in Livewire components for seamless validation:

use Captchaapi\Laravel\Concerns\WithCaptcha;

class MyComponent extends Component {
    use WithCaptcha;

    public function submit() {
        $this->validateWithCaptcha(['field' => 'required']);
        // Proceed...
    }
}

Livewire Form Wrapper: Use <x-captchaapi::livewire-form> in Blade:

<x-captchaapi::livewire-form action="submit">
    <input wire:model="email">
    <button>Submit</button>
</x-captchaapi::livewire-form>

2. Validation Workflows

Plain Forms: Use the ValidCaptcha rule or alias 'captcha':

$request->validate([
    'response' => ['required', 'captcha'], // Alias
]);

Livewire: Leverage validateWithCaptcha() for concise validation:
```
$this->validateWithCaptcha(['email' => 'required']);
```

3. Status Feedback

Add a status element to forms:

<form data-captcha>
    <div data-captcha-status></div>
    <!-- Form fields -->
</form>

Customize styling via CSS:

[data-captcha-status][data-captcha-state="ready"] {
    color: #059669;
}

4. Conditional Disabling

Disable CAPTCHA in .env for testing/staging:
```
CAPTCHAAPI_ENABLED=false
```

Toggle dynamically in code:

\Captchaapi\Laravel\Facades\Captchaapi::disable();

Gotchas and Tips

Pitfalls

Secret Key Exposure
- Never expose CAPTCHAAPI_SECRET_KEY in client-side code. The package ensures server-side-only usage via the ValidCaptcha rule.
Livewire Double Validation
- Fortify/Livewire may validate twice. Use FakeCaptchaapi::enforceSingleUse() in tests to simulate this:
```
FakeCaptchaapi::enable()->enforceSingleUse();
```
Status Element Dependencies
- The status element (data-captcha-status) requires the widget script. Omitting it runs silently.
Rate Limiting
- Excessive rate_limited states may indicate bot attacks. Monitor logs for CAPTCHAAPI_DEBUG=true.

Debugging

Enable debug mode to log timing/errors:
```
CAPTCHAAPI_DEBUG=true
```
Check browser console for widget initialization errors (e.g., missing site_key).

Configuration Quirks

fail_open Behavior:
- Defaults to true (allow submissions if the server fails). Set to false for sensitive actions (e.g., logins).
```
CAPTCHAAPI_FAIL_OPEN=false
```
Locale Fallback:
- Widget language defaults to <html lang>. Force a locale via:
```
CAPTCHAAPI_LOCALE=en
```
Preload Mode:
- CAPTCHAAPI_PRELOAD=eager triggers CAPTCHA on page load (rarely needed).

Extension Points

Custom Error Handling

Override the default error component:

@error('captchaapi_response')
    <p class="custom-error">{{ $message }}</p>
@enderror

API Overrides

Change the base URL for testing:

CAPTCHAAPI_BASE_URL=https://staging.captchaapi.eu

Testing

Use FakeCaptchaapi to bypass real API calls:

FakeCaptchaapi::enable(); // Allows any response
FakeCaptchaapi::disable(); // Re-enables real validation

Livewire-Specific Tips

Event Mode: The livewire-form wrapper uses data-captcha-mode="event" for Livewire’s wire:submit compatibility.
Hidden Field: The wrapper auto-injects captchaapi_response; avoid manual inclusion to prevent conflicts.

Performance

Lazy Loading: Default CAPTCHAAPI_PRELOAD=lazy delays widget initialization until form interaction.
Octane Compatibility: Stateless design ensures safe use with Swoole/RoadRunner (no request leakage).


```markdown
---

Laravel Laravel Package