Recaptcha Bundle Laravel Package

Getting Started

First, calibrate expectations: this is a Symfony bundle, not a Laravel package. newscoop/recaptcha-bundle is a fork of Exceliance's EWZRecaptchaBundle, last tagged in 2014, targeting Symfony 2.x and the reCAPTCHA v1/early-v2 era. It has no Laravel service provider, no config/recaptcha.php, and no facade. In a Laravel codebase you will not composer require this and get a working captcha; you will either (a) use it inside a legacy Symfony app, or (b) mine it for the pattern and reimplement it idiomatically in Laravel.

Where to look first, in order:

1. README.md — the canonical usage snippet (form type + Twig widget).
2. DependencyInjection/Configuration.php — the real config surface (public_key, private_key, enabled, locale, secure, theme, type, size).
3. Form/Type/EWZRecaptchaType.php — the field definition and how it reads config.
4. Resources/views/Form/*.twig — the widget markup and the g-recaptcha JS include.

Minimal Symfony usage looks like:

# config.yml
ewz_recaptcha:
    public_key:  '%recaptcha_public%'
    private_key: '%recaptcha_private%'
    enabled:     true

$builder->add('recaptcha', EWZRecaptchaType::class);

For a Laravel developer, the realistic first use case is porting that contract into a custom validation rule plus a Blade partial — not installing the bundle.

Implementation Patterns

Symfony form-type pattern (the bundle's native path). Add the field to a form, render the widget through the bundle's form theme, and rely on server-side verification on submit. This is the pattern the package was built for.

The Laravel equivalent you'll actually ship. Reproduce the same three moving parts — site key in the view, response token in the POST, secret-key verification server-side:

// AppServiceProvider::boot()
Validator::extend('recaptcha', function ($attribute, $value) {
    return Http::asForm()
        ->post('https://www.google.com/recaptcha/api/siteverify', [
            'secret'   => config('services.recaptcha.secret'),
            'response' => $value,
            'remoteip' => request()->ip(),
        ])
        ->json('success') ?? false;
});

<div class="g-recaptcha" data-sitekey="{{ config('services.recaptcha.sitekey') }}"></div>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>

Then 'g-recaptcha-response' => 'required|recaptcha' in the FormRequest.

Config-driven enable/disable. Mirror the bundle's enabled flag with config('services.recaptcha.enabled') so tests and local dev bypass the network call. This is the single most valuable idea to carry over.

Integration tips. Keep the secret in config/services.php + .env; never echo it. Wrap the verify call in a small service so you can fake it in tests (Http::fake()). If you're genuinely inside Symfony, register the bundle in AppKernel, import the routing-free config, and pull the form theme into your Twig config.

Gotchas and Tips

• This is not a Laravel package. No auto-discovery, no container bindings you can resolve, no Recaptcha facade. Treat it as reference source, not a dependency.
• The runtime is dead. The 2014 tag predates modern Symfony and reCAPTCHA v2/v3; reCAPTCHA v1 was shut down in 2018. Installing it against a current framework will likely produce autoload and API conflicts before it produces a captcha.
• Keys are domain-locked. A site key registered for example.com silently fails on localhost; use Google's documented test keys for local work.
• Verification is server-side only. The client widget is cosmetic; a missing g-recaptcha-response or a success: false from siteverify is the only thing that matters. Always check success and consider score/action if you migrate to v3.
• CSP and async loading. The bundle injects api.js; under a strict Content-Security-Policy you must allow https://www.google.com in script-src and often frame-src. This trips people up more than the captcha logic itself.
• Debugging checklist: is the widget rendering (network tab shows api.js)? Is g-recaptcha-response present in the POST? What does the raw siteverify JSON say — error-codes usually names the problem (invalid-input-secret, timeout-or-duplicate)?
• Extension points, if you must stay on Symfony: override the Twig form theme block to restyle, and decorate/replace EWZRecaptchaType to swap in a v2/v3-compatible renderer. Both are cleaner than patching the vendored bundle.
• Token reuse is rejected. Tokens are single-use and expire (~2 minutes); don't cache or re-verify a submitted value.