Google Recaptcha Bundle Laravel Package

Getting Started

Read this first: it's a Symfony bundle, not a Laravel package. There is no service provider, no config/recaptcha.php, and no facade. Composer will install it into a Laravel app, but nothing will auto-wire — you'd be pulling in Symfony's Form/HttpKernel abstractions for a single HTTP POST to Google. For a Laravel codebase, the honest day-to-day answer is to skip this package and use google/recaptcha (official PHP client) wrapped in a custom validation rule, or a maintained Laravel package. The rest of this assessment describes what you'd actually do if you inherited a Symfony app already using it.

Minimal setup in Symfony:

1. composer require kleegroup/google-recaptcha-bundle
2. Register the bundle — config/bundles.php on Symfony 4+, AppKernel::registerBundles() on Symfony 2/3.
3. Create a reCAPTCHA v2 site in the Google admin console and copy the site key (public) and secret key (server-side only).
4. Add config under the bundle's root key (see the bundle's DependencyInjection/Configuration.php — the README does not spell it out) with both keys, ideally sourced from %env(...)%.

Where to look first, in order:

• DependencyInjection/Configuration.php — the only reliable source of truth for config keys; the docs are thin.
• Resources/config/services.* — tells you the service IDs you can inject or decorate.
• Resources/views/ — the Twig template that emits the g-recaptcha div and the Google script tag.
• Any Form/ or Validator/ directory — if present, this is the intended integration path.

First use case: a contact or registration form. Render the widget in Twig, let the browser post g-recaptcha-response, and verify that token server-side before persisting anything.

Implementation Patterns

Form-type pattern (preferred if the bundle ships one). Add the bundle's reCAPTCHA field type to your form builder and let its validator run on submit. Because the token is bound to the request, this only works for a normal full-page POST — not for an AJAX/JSON endpoint unless you pass the token as a named field and validate manually.

Manual verification pattern (most portable). Inject the bundle's verification service into your controller, read $request->request->get('g-recaptcha-response'), and call the verify method before your business logic. Treat a missing token, a success: false response, and a transport exception as three distinct failure modes.

Twig rendering. Keep the widget in your layout or a partial and render it inside the <form>. The site key is public and fine in markup; the secret key must never reach a template or any client-side bundle.

Configuration hygiene. Put both keys in .env and reference them via %env(RECAPTCHA_SITE_KEY)% / %env(RECAPTCHA_SECRET_KEY)%. Never commit them; never reuse the same key pair across staging and production if you rely on domain restrictions.

Local and CI environments. Google publishes test keys that always return success: true. Wire those into dev and test config so test suites and local form submissions don't fail. Do this via environment-specific config, not by branching inside controllers.

Laravel equivalent, for comparison. composer require google/recaptcha, bind a client in a service provider, and implement a Rule object that calls verify() and returns a message. That's roughly the same amount of code as configuring this bundle, minus an unmaintained Symfony dependency.

Gotchas and Tips

• Archived since 2018 with 6 stars and zero dependents. There is no security response, no compatibility work for modern Symfony, and effectively no community to google errors against. If the bundle's composer.json constrains symfony/form to ^2.8|^3.0, it will fight your Symfony 5/6/7 app.
• Assume v2 only. A 2018 bundle almost certainly has no score-based v3 support and no action parameter checking. If you need v3, plan to bypass the bundle and call the siteverify endpoint yourself.
• Token single-use and short-lived. Each g-recaptcha-response is valid for roughly two minutes and only once. Double-submits, back-button resubmissions, and retried requests after a network failure will fail verification — handle that as a user-facing "please try again" rather than a 500.
• Verify server-side, always. The client-side checkbox proves nothing on its own. If the bundle's Twig template includes the script but your controller never verifies, you have no protection at all.
• Fail-open vs fail-closed. When Google's endpoint times out, decide deliberately: reject the submission (fail-closed, safer, worse UX) or allow it and log (fail-open). Make it explicit in code and add a timeout to the HTTP call so a hung request doesn't stall your worker.
• success: false is not the only failure. Inspect error-codes (e.g. timeout-or-duplicate, invalid-input-secret, missing-input-response). A misconfigured secret key looks identical to a bot from the outside; log the error codes or you'll debug blind.
• Extension points, in order of preference: (1) override the bundle's Twig template in templates/bundles/, (2) decorate the verification service to add logging, retries, or your own HTTP client, (3) if the bundle's validator is too rigid, drop it and call the verifier from a listener on kernel.request for the routes you care about. Never fork the bundle — it's not coming back.
• Migration tip. Because the surface area is small, replacing it is cheap: swap the bundle for google/recaptcha, keep your Twig widget, and route verification through one small service of your own. Do that before adding a second form, not after.
• Debugging. Turn on Symfony's profiler and check the HTTP client logs for the siteverify request and response body — most "it doesn't work" reports are a wrong secret key, a domain mismatch on the site key, or a token that was already consumed.