Filament Grecaptcha Field Laravel Package

Getting Started

• Install with composer require abanoubnassem/filament-grecaptcha-field. v0.0.12 is the release that widened the constraints for Filament 5, Laravel 13 and PHP 8.4 — confirm your resolved versions with composer show abanoubnassem/filament-grecaptcha-field after install rather than assuming it pulled the newest tag.
• Publish the config (php artisan vendor:publish and pick the package's config tag — check the README for the exact tag name) so the site key, secret key, and version settings live in config/filament-grecaptcha-field.php instead of hardcoded values.
• Put credentials in .env and reference them from config. Re-run php artisan config:cache after any change in production, otherwise you'll be editing a file the app never reads.
• Add the field to a form schema alongside your other Filament components, e.g. GRecaptcha::make('captcha'), typically as the last field before the submit action. Confirm the exact class name and namespace against the README, since the package is pre-1.0 and the surface has moved between tags.
• First use case: protecting a login or contact form. Before you debug anything in PHP, register both localhost and your staging/production domains in the Google reCAPTCHA admin console. On an unregistered domain the widget usually renders but never resolves a token, which presents as an unexplained validation failure.
• Where to look first: the README usage block (it is short and is the de-facto API reference), the published config file, and the field class source itself for the available fluent methods (theme, type, action, size, and so on).

Implementation Patterns

• Standard form protection. Add the field to a Resource form or a custom Livewire form schema, call ->required() on it, and let the package's rule do the server-side siteverify. Keep the field dehydrated so the value reaches your submit handler.
• v3 / invisible mode. No user interaction, so the field alone is not enough: pass an action name at render time and check that same action plus a score threshold in verification. Treat a bare success: true as insufficient.
• Reusable verification outside forms. If you need captcha checks on API endpoints or queued flows, extract a small service or action class that wraps the siteverify HTTP call, rather than instantiating the form field. This also makes it trivially fakeable in tests.
• Testing. Http::fake() the siteverify endpoint and return a canned success payload, or conditionally disable/omit the field in the testing and local environments via config. Never let the suite hit Google.
• Multiple forms on one page. Each captcha field needs a unique field name and its own widget instance; reusing a name causes the second form to inherit the first form's token state.
• Environment parity. Keep the same reCAPTCHA key pair across environments only if the domains are registered; otherwise use separate keys per environment so a staging failure never blocks production traffic.

Gotchas and Tips

• Pre-1.0 versioning. 0.0.x carries no semver promise. Pin the exact version ("0.0.12") or at minimum ~0.0.12, and read the changelog before any composer update. Minor-looking bumps in this range have changed compatibility constraints.
• Filament 5 / Laravel 13 coupling. This release exists largely to widen those constraints. If you upgrade Filament, you must bump this package in lockstep. A mismatch typically shows up as an unresolvable dependency tree (use composer why-not abanoubnassem/filament-grecaptcha-field) or as a field that silently fails to render.
• Tokens are single-use and short-lived. They expire in roughly two minutes and are bound to the hostname and action. A Livewire re-render that re-mounts the widget between page load and submit can invalidate the token, producing intermittent "captcha failed" errors that are hard to reproduce.
• Don't double-verify. If you also call siteverify from a saved hook, an observer, or a job, the second call fails because the token is already consumed. Verify exactly once, and let the form rule own it.
• SPA navigation. With wire:navigate, the Google script isn't always re-executed on the new page, leaving the widget inert after client-side navigation. A full page load on the form route, or re-initialising on livewire:navigated, works around it.
• CSP and proxies. Allow www.google.com/recaptcha/, www.gstatic.com/recaptcha/ and the challenge iframe origins in your Content-Security-Policy, or the widget will be blocked while the server-side validation looks fine.
• Debugging failures. Failing keys fail closed and surface as a generic validation message. Log the error-codes array from Google's siteverify response — invalid-input-secret, timeout-or-duplicate and invalid-input-response each point at a very different root cause, and the generic form error hides which one you hit.
• Extension points. Beyond the config file, the practical escape hatches are a custom validation message via the package translations, and subclassing the field to override the verification endpoint or payload — useful for pinning a fake in CI or pointing at an enterprise endpoint.