Filament Hcaptcha Laravel Package

Getting Started

1. Install the package

   composer require danie1net0/filament-captcha
   

2. Look here first

   • config/filament-captcha.php — the driver/site-key/secret-key settings. Publish it with php artisan vendor:publish --tag="filament-captcha-config" before touching anything else.
   • The package service provider — it registers the form component and validation rule; useful when you need to understand the exact field name and macro registration.
   • Your .env — every driver (reCAPTCHA v2/v3, hCaptcha, Turnstile) is driven by env-backed keys, so a blank key is the most common cause of a "widget doesn't render" report.

3. First use case Add the captcha component to a form schema, typically a public-facing contact or registration form:

   use Danie1net0\FilamentCaptcha\Forms\Components\Captcha;
   
   public static function form(Form $form): Form
   {
       return $form->schema([
           TextInput::make('name')->required(),
           TextInput::make('email')->email()->required(),
           Captcha::make('captcha'),
       ]);
   }
   

   Submit once in local to confirm the widget renders and the validation rule fires, then verify again with production keys — reCAPTCHA keys are domain-scoped, so localhost behaviour and deployed behaviour are not the same.

Implementation Patterns

• Treat the captcha as a normal form component. It lives in the schema alongside other fields, so it composes with Grid, Section, and ->columnSpanFull(). For narrow layouts, let it span the full width rather than putting it in a 1/3 column — the widget has a fixed intrinsic width and will look cramped otherwise (this is exactly the class of issue v1.1.2 addressed by centering the widget and fixing v2 rendering).
• Centralise driver choice in config, not in code. Pick reCAPTCHA v2 vs v3 vs hCaptcha vs Turnstile via the config/env driver key so you can swap providers per environment without editing form schemas.
• Panel-wide defaults. If every public form in a panel needs protection, add the component in a shared schema/trait (or a base form class) rather than copy-pasting Captcha::make('captcha') into each resource.
• Pair with server-side rate limiting. The captcha rule validates the token; it does not throttle submissions. Combine with RateLimiter/throttle middleware on the underlying route or Livewire action for meaningful abuse protection.
• Validation placement. Keep the captcha field required and let the package's rule handle verification; avoid writing a second ->rule() on top of it, as double-verification against the provider API will consume tokens and can fail the second call.
• Testing. In feature tests, either disable the driver via config for the test environment or stub the provider HTTP call (Http::fake()); attempting real verification in CI will fail because tokens are single-use and domain-bound.

Gotchas and Tips

• Site key vs secret key. The site key is public and rendered into the page; the secret key is used server-side only. Mixing them up produces a widget that renders but never validates (or vice versa), with a generic "captcha failed" message.
• Domain registration. reCAPTCHA keys must have the exact hostname registered in the Google admin console, including localhost if you want local testing and any staging subdomain. A correct key that "works in prod but not staging" is almost always this.
• reCAPTCHA v2 rendering. v1.1.2 fixed v2 widget rendering and centering; if you pinned 1.1.1 or below, the checkbox could render misaligned or fail to mount inside Filament's form wrapper. Upgrade before debugging CSS yourself.
• v3 is invisible and score-based. A passing form submit with v3 still depends on the action and score threshold; if legitimate users are blocked, check the score threshold and that the action name matches between client and server config, not the widget.
• Multiple forms on one page. v2 checkboxes and Turnstile widgets are per-form; if you render two forms on a single page, confirm each gets its own token, otherwise the second submit reuses an already-consumed token.
• CSP and iframes. All supported providers load a third-party script/iframe. A strict Content-Security-Policy needs script-src/frame-src entries for google.com, gstatic.com, hcaptcha.com, or challenges.cloudflare.com; otherwise the widget silently fails to appear.
• Config caching. After changing driver or keys, run php artisan config:clear (and in production config:cache) — stale cached config is a frequent cause of "I changed the env and nothing happened".
• Debugging failed validation. Log the provider response (error codes like invalid-input-secret, timeout-or-duplicate) rather than surfacing it to the user; the raw error immediately tells you whether it's a key, domain, or token-reuse problem.
• Extension points. Because the widget is a standard Filament form component, override its view or wrap it in a custom component if you need different sizing/theming; for provider-specific edge cases, bind a custom validation rule and point the config at it instead of forking the package.