Recaptcha Bundle Laravel Package

Getting Started

• Read the README first, then the DependencyInjection/ and Validator/ (or Service/) directories. This is a Symfony bundle, not a Laravel package: there is no service provider, no facade, and no config/recaptcha.php. The useful part is the server-side siteverify call and score/action validation logic, which you will re-implement in Laravel.
• Do not composer require this into a Laravel app expecting it to work. It registers as a Symfony bundle via bundles.php, wires services through Symfony's container, and typically renders through Twig. None of that is discoverable by Laravel's container. Treat it as a reference implementation.
• Minimal Symfony usage (if you are actually in Symfony): require the bundle, register it in config/bundles.php, create config/packages/pr_recaptcha.yaml with site_key and secret_key from env, render the v3 script in your base template, and verify the token in a controller or via the bundle's validator constraint.
• Your first Laravel use case: invisible v3 on a contact or login form. Render https://www.google.com/recaptcha/api.js?render=SITE_KEY in Blade, call grecaptcha.execute(SITE_KEY, {action: 'contact'}) on submit, post the token, and verify server-side with score >= 0.5 and action === 'contact'.
• Where to look first in the bundle: the exact siteverify payload it builds, how it checks success, score, action, and hostname, and how it exposes the threshold. Those four checks are the whole job.

Implementation Patterns

• Port the verification into a Laravel service, not a bundle. Create app/Services/Recaptcha.php wrapping Http::asForm()->post('https://www.google.com/recaptcha/api/siteverify', [...]) and returning a result object with success, score, action, and errorCodes. This mirrors what the bundle's validator does while staying idiomatic.
• Wrap it in a validation rule or FormRequest. A RecaptchaRule that accepts an expected action and minimum score keeps controllers clean and makes the check reusable across forms. Pass the action per form so v3's action binding is meaningful.
• Render via a Blade component. A <x-recaptcha :action="'contact'" /> component that emits the script tag and a hidden input keeps the site key in one place and avoids duplicating the JS bootstrap. The bundle's Twig helper is the equivalent; do not try to reuse it.
• Verify on the server for every state-changing request. v3 tokens are single-use and short-lived; verify immediately on submit, not in a queued job. If the score is below threshold, either reject or fall back to a visible challenge.
• Config through env. Mirror the bundle's site_key / secret_key config with config/services.php entries reading RECAPTCHA_SITE_KEY and RECAPTCHA_SECRET_KEY. Never expose the secret in Blade or JS.
• Log scores, not tokens. Emit a structured log line with action, score, hostname, and error codes. This is the single most useful operational pattern for tuning thresholds.
• Keep an interface so you can swap providers. RecaptchaVerifier contract with a Google implementation lets you add a fallback (hCaptcha, Turnstile) without touching call sites — something the archived bundle cannot offer.

Gotchas and Tips

• Archived and unmaintained since 2020-02-26. No security patches, Symfony 5-era APIs, zero dependents. Do not build a new integration on it; the opportunity score reflects an unmaintained niche, not maturity.
• Not Laravel-compatible by design. Bundle registration, Symfony service tags, Twig extensions, and Configuration trees have no Laravel equivalent. Installing it will autoload classes but won't register services, and any Twig dependency will fail.
• v3 is score-based, not pass/fail. A "valid" token can still be a bot. Always check score, action, and hostname; validating only success is the most common mistake.
• Tokens expire in ~2 minutes and are single-use. Do not cache or re-verify. Fetch a fresh token right before submit; re-executing on a timer can produce stale tokens.
• Action mismatch is silent. If the JS action and the server-side expected action differ, verification fails or scores are meaningless. Pass the action explicitly from the component to the rule.
• Google's error codes are the debugging key. Log error-codes (invalid-input-secret, timeout-or-duplicate, invalid-input-response). The bundle does not surface these richly; your port should.
• Threshold tuning is per-form. 0.5 is a default, not a rule. Login forms often need a higher bar with a fallback challenge for legitimate low scorers.
• Use Google's test keys in local/CI (6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI / 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe) so tests don't hit the live endpoint or fail on network egress.
• Extension point is the HTTP call itself. The cleanest place to add retries, timeouts, and circuit-breaking is your verifier service, not the form rule. Keep the network boundary thin and the validation rule pure.