Filament Captcha Laravel Package

Getting Started

1. composer require dominion-solutions/filament-captcha (note the 1.0.0 major bump — see Gotchas before upgrading from 0.2.x).
2. Publish what ships: php artisan vendor:publish --tag="filament-captcha-config" (and -views / -translations if you need to restyle or localize). Then re-run php artisan filament:assets if views were published.
3. Pick a provider and create keys: Cloudflare Turnstile (cheapest friction, invisible mode), hCaptcha, or reCAPTCHA v2/v3. Put the site key in a *_SITE_KEY env var and the secret in *_SECRET_KEY — the secret must never reach the browser.
4. Add both to .env, .env.example, and your deploy pipeline's secret store. Run php artisan config:clear locally (and config:cache in deploy) so the new keys are actually read.
5. First use case: protect your panel's auth pages. In your PanelProvider (or per-page form schema) attach the captcha component next to the email/password fields on Login, Register, and RequestPasswordReset.

Where to look first, in order: the README's install + config table, config/filament-captcha.php (driver, keys, theme/size, enable flags), the Filament field/component class under src/ (to see which validation rule it registers), and the package's own tests (the fastest source of truth for the public API in 1.0.0, since the release notes are thin).

Implementation Patterns

• Panel-wide auth protection. Register the component once in each panel that has auth pages rather than copy-pasting per page. Remember there are three distinct forms (login, register, password reset) — it's easy to protect login and leave reset wide open.
• Custom Filament forms. Drop the component into any Schema/Form alongside your other fields. Validation happens server-side through the rule the component registers; you don't call the provider yourself.
• Non-Filament surfaces. For API endpoints, Livewire components you built by hand, or plain controllers/FormRequests, reuse the package's validation rule directly on the request instead of duplicating HTTP calls to the provider. Keep one code path.
• Multi-panel / multi-tenant keys. If panels are separate brands or domains, publish the config and select keys per panel/env. Provider keys are domain-scoped, so a shared key across staging and production will fail verification in confusing ways.
• Testing pattern. Disable the captcha in phpunit.xml (or the package's bypass flag in your TestCase) so the suite never makes a network call. Assert the rule behavior with a fake client in a dedicated test rather than exercising the real provider.
• Local development. Use the providers' documented test keys (Turnstile and reCAPTCHA both publish always-pass keys) or the config bypass, and keep that switch env-driven so it can't ship to production.
• Defence in depth. Pair the captcha with RateLimiter/Filament's built-in login throttling — a captcha stops bots, throttling stops credential stuffing from a single IP.

Gotchas and Tips

• 1.0.0 is effectively a breaking release. "Modernization / Laravel 13" means the Filament and Laravel constraints moved. Check composer.json requirements against your app before bumping; expect renamed namespaces, changed config keys, and republished views/assets being required. Read PR #26 or the diff, not just the changelog line — the changelog here says nothing about migration steps.
• Config caching. Deploying new keys without php artisan config:cache (or with a stale cache) silently keeps old keys. "Captcha always fails in staging" is almost always this or a domain mismatch.
• Token reuse and expiry. Turnstile/hCaptcha tokens are single-use and short-lived. If validation fails and the form re-renders without resetting the widget, the second submit fails with timeout-or-duplicate and users get stuck in a loop. Make sure the widget resets on validation error.
• Livewire navigation. With wire:navigate, provider scripts loaded once in the layout won't re-initialize on subsequent page loads. Either exclude the auth pages from SPA navigation or add a re-init hook.
• CSP. Turnstile/hCaptcha/reCAPTCHA all need script-src and frame-src allowances for the provider domains. A silent, non-rendering widget is usually a CSP violation, not a package bug — check the browser console before filing an issue.
• Multiple widgets on one page. Two captcha fields (e.g. a modal login plus a page login) can collide on widget IDs. Scope each instance explicitly.
• Not a complete defence. It only guards forms where the component/rule is attached. Bots posting directly to your login POST route bypass the rendered widget unless the server-side rule is on that request too.
• Localization. Error strings come from the package's translations — publish and edit lang/ rather than hardcoding messages in your form.
• Extension points. Custom drivers/providers, view overrides, and per-instance theme/size options are the usual seams; prefer config + published views over forking, so the next release stays upgradeable.