Getting Started

Minimal Steps

Installation:

composer require captchaapi/laravel
php artisan vendor:publish --tag=captchaapi-config

Add credentials to .env:

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

First Use Case (HTML Form):

Add the widget to your layout <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', 'captcha'],
]);

First Use Case (Livewire):

Include the widget in your layout (same as above).

Use the WithCaptcha trait in your Livewire component:

use Captchaapi\Laravel\Concerns\WithCaptcha;

class MyComponent extends Component {
    use WithCaptcha;

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

Use the Livewire form wrapper in your view:

<x-captchaapi::livewire-form action="submit">
    <!-- form fields -->
</x-captchaapi::livewire-form>

Implementation Patterns

Workflows

Form Submission Workflow:
- HTML Forms: Use data-captcha on the <form> and validate with the captcha rule.
- Livewire: Use validateWithCaptcha() in your component method and the livewire-form wrapper in your view.
- Error Handling: Display errors with <x-captchaapi::error /> or manually with @error('captchaapi_response').
Dynamic Form Integration:
- For dynamically loaded forms (e.g., via AJAX), ensure the widget script is loaded before form interaction. Use CAPTCHAAPI_PRELOAD=eager in .env to preload the widget on page load.
Multi-Step Forms:
- Use validateWithCaptcha() in each step’s submission method. The captchaapi_response is automatically included in the validation.
Conditional CAPTCHA:
- Disable CAPTCHA for specific forms by conditionally rendering the widget or using middleware to skip validation:
```
if (!$shouldUseCaptcha) {
    $request->validateWithoutCaptcha(['field' => 'required']);
}
```

Integration Tips

Livewire Integration:
- Always use <x-captchaapi::livewire-form> instead of plain <form> to ensure proper event handling.
- For custom Livewire actions, use rulesForCaptcha() to manually compose validation rules:
```
$this->validate(array_merge($rules, $this->rulesForCaptcha()));
```
Status Feedback:
- Add a status element to provide user feedback:
```
<div data-captcha-status></div>
```
- Style it using the provided CSS classes or override defaults with custom CSS.
Configuration:
- Adjust CAPTCHAAPI_TIMEOUT for slower networks or CAPTCHAAPI_FAIL_OPEN for sensitive actions (e.g., logins).
- Set CAPTCHAAPI_LOCALE to enforce a specific language for the widget.

Testing:

Use FakeCaptchaapi::enable() in tests to bypass real API calls:

use Captchaapi\Laravel\Testing\FakeCaptchaapi;

beforeEach(function () {
    FakeCaptchaapi::enable();
});

For Fortify testing, enforce single-use behavior:
```
FakeCaptchaapi::enforceSingleUse();
```

Gotchas and Tips

Pitfalls

Missing Widget Script:
- Forgetting to include <x-captchaapi::widget /> in your layout will cause the CAPTCHA to fail silently. Always include it in the <head> of layouts where forms are used.
Livewire Event Mode:
- If using Livewire, ensure data-captcha-mode="event" is set by using <x-captchaapi::livewire-form>. Manual forms with data-captcha will use submit mode, which may not work with Livewire’s event-driven flow.
Secret Key Exposure:
- Never expose CAPTCHAAPI_SECRET_KEY in client-side code. The package is designed to keep it server-side only.
Double Validation in Fortify:
- Fortify validates login forms twice in a single request. Use FakeCaptchaapi::enforceSingleUse() in tests to simulate this behavior and avoid false positives.
Status Element Overrides:
- If you override the widget’s default colors with data-captcha-no-color, ensure you distinguish between waiting and ready states visually, as they share the same icon by default.

Debugging

Validation Errors:
- If ValidCaptcha fails unexpectedly, check:
  - The captchaapi_response field name in your form.
  - The .env keys (CAPTCHAAPI_SITE_KEY and CAPTCHAAPI_SECRET_KEY).
  - The CAPTCHAAPI_ENABLED flag (set to false disables validation silently).
Livewire Debugging:
- Use dd($this->rulesForCaptcha()) to inspect the generated CAPTCHA rules.
- Check browser console for CAPTCHA widget errors (e.g., network issues or invalid responses).
API Issues:
- If the CAPTCHA service is unreachable, set CAPTCHAAPI_FAIL_OPEN=false to block submissions during outages. Monitor logs for timeout errors.
Status Element Not Updating:
- Ensure the <div data-captcha-status> is a direct child of the form or nearby in the DOM. The widget only styles elements with this attribute.

Extension Points

Custom Validation Logic:

Extend the ValidCaptcha rule by creating a custom rule class:

use Captchaapi\Laravel\Rules\ValidCaptcha as BaseValidCaptcha;

class CustomValidCaptcha extends BaseValidCaptcha {
    public function passes($attribute, $value) {
        // Custom logic
        return parent::passes($attribute, $value);
    }
}

Use it in validation:

$request->validate([
    'captchaapi_response' => ['required', new CustomValidCaptcha],
]);

Custom Status Styling:
- Override the default styles by targeting the data-captcha-state attribute:
```
[data-captcha-status][data-captcha-state="ready"] {
    background-color: #d1fae5;
}
```
Testing Extensions:
- Mock the CAPTCHA API responses in tests by extending FakeCaptchaapi:
```
FakeCaptchaapi::fake([
    'response' => 'valid_token_123',
]);
```

Dynamic Configuration:

Override config values dynamically in your service provider:

$this->app->singleton('config', function ($app) {
    return array_merge(
        require __DIR__.'/../config/captchaapi.php',
        ['timeout' => 10] // Override timeout
    );
});

Configuration Quirks

CAPTCHAAPI_PRELOAD:
- Set to eager to load the CAPTCHA widget immediately on page load (useful for single-page applications). Default (lazy) waits for form interaction.
CAPTCHAAPI_DEBUG:
- Enable (true) to log timing breakdowns in the browser console for debugging performance issues.
CAPTCHAAPI_MODE:
- Explicitly set to submit or event if you need to override the default behavior (e.g., for custom form handlers). Defaults to null (auto-detects based on context).
Locale Fallback:
- The widget falls back to the <html lang> attribute if CAPTCHAAPI_LOCALE is not set. Ensure your app’s locale is correctly configured.

Laravel Laravel Package