Recaptcha2 Bundle Proxyable Laravel Package

Technical Evaluation

Architecture fit. Poor as packaged. Despite the task framing, this is a Symfony bundle, not a Laravel package. It ships a Bundle subclass, a DependencyInjection extension with a Configuration tree, and presumably a form type / Twig extension — all bound to Symfony's kernel and container lifecycle. Laravel's Illuminate container does not process Bundle::build() or Extension::load(); there is no auto-discovery for config/bundles.php equivalents. Anything reusable here is the verification client buried inside the bundle wiring, not the bundle itself. The proxy capability is explicitly marked "in progress," which puts the one differentiated feature on the wrong side of stable.

Integration feasibility. Feasible only via extraction. The underlying work is small — build a verify($token, $ip) call against https://www.google.com/recaptcha/api/siteverify, POSTing secret, response, remoteip, and route it through an HTTP client with a proxy option. Guzzle and Laravel's Http facade both expose proxy (including socks5 and per-scheme auth), so the capability is a one-line option, not a reason to adopt a dependency. Practical path: install google/recaptcha (official, PSR-18 injectable) or hand-roll ~150 lines, and wrap it in a Laravel service provider + FormRequest rule. Pulling in a 0-star Symfony bundle to obtain a Guzzle option is net-negative value.

Technical risk. Several compounding items:

Key questions.

1. Why a proxy? Geo-blocking (Google reachability), egress-restricted VPC with a mandatory NAT/proxy, or corporate TLS-inspection? The answer changes whether CONNECT tunneling is acceptable or you're leaking secrets to an inspecting proxy.
2. Fail-open or fail-closed when siteverify times out? For a registration form, fail-closed blocks revenue; fail-open disables the control. This is a product decision, not a library one.
3. What's the latency budget on the request path — are we tolerating 2–3s added per submission?
4. Is reCAPTCHA v2 the right control in 2025, versus Turnstile/hCaptcha/Enterprise (v2 legacy support, UX friction)?
5. Does the "proxy" flag actually work in the fork, or is it a TODO? One hour of reading the diff answers this.

Verdict: Do not adopt. Score (opportunity 24.46, 0 stars, 0 dependents) matches the technical read: the capability is trivial to reproduce in-house, and the package carries security-surface and license risk disproportionate to its value.

Integration Approach

Stack fit. Laravel-native equivalent is a four-piece build, none of which requires Symfony:

• config/services.php → recaptcha.site_key, secret, verify_url, proxy (from .env, null in local).
• App\Services\Recaptcha\Verifier → constructor-injected Illuminate\Http\Client\Factory, calls Http::asForm()->withOptions(['proxy' => $proxy, 'timeout' => 3, 'connect_timeout' => 2])->post(...), returns a typed result object (success, score/error codes, latency, degraded flag).
• Rules\ValidRecaptcha / RecaptchaRequest → validation layer, so call sites stay declarative.
• Blade component for the widget + a @recaptchaScripts directive; site key from config so environments don't cross-wire.

If legal insists on the LGPL path, the fallback is: composer require jakreiter/recaptcha2-bundle-proxyable, do not register the bundle, and use only the verifier class via a manual binding — but verify first that the class has no container-trait dependencies.

Migration path. Nothing to migrate from if reCAPTCHA isn't live yet. If a prior Laravel app used greggilbert/recaptcha or inline file_get_contents calls, replace them behind the new Verifier interface in one PR and delete the old clients; keep the interface stable so the swap is invisible to controllers.

Compatibility. Confirm composer.json PHP and symfony/* constraints before any spike — a bundle pinned to Symfony 7 / PHP 8.2+ will conflict with an older Laravel 10 app on PHP 8.1. Laravel 10–12 and PHP 8.1–8.4 are safe for the in-house build. Proxy support in Guzzle requires curl ext; verify the proxy honors HTTPS_PROXY/NO_PROXY so the same image works in dev and prod.

Sequencing.

1. Day 1–2 — spike. Read the fork's diff; stand up a throwaway verifier through the corporate proxy and prove siteverify reachability. This answers the only question the package could have answered.
2. Week 1 — decision gate. Confirm proxy purpose, fail-open policy, and license position. Almost always resolves to build.
3. Week 2 — build + test. Verifier, rule, Blade component, and tests for: valid token, invalid token, timeout, proxy 502, proxy auth failure, DNS failure. Include a Http::fake() suite so CI needs no network.
4. Week 3 — canary. Ship on low-risk forms (contact, newsletter) behind a flag; watch verification success rate, p95 latency, proxy egress errors for 5–7 days.
5. Week 4 — rollout to registration/checkout with the fail-open policy baked in and an alert on success-rate drop.

Operational Impact

Maintenance. In-house: ~200 LOC plus tests, owned by the team that owns the form. Adopting the bundle: you inherit an unmaintained fork, so you are de facto the maintainer of a security dependency with no upstream you control (upstream Beelab is the real project; this fork's release date reflects fork activity, not a support commitment). Net, the build option is lower total cost of ownership from month two onward.

Support. No vendor, no SLA, no issue triage on a 0-star fork. The one thing you'd want supported — a proxy regression — is exactly the part labeled "in progress." Budget on-call ownership explicitly; reCAPTCHA failures page someone.

Scaling. Verification adds one outbound HTTPS round trip per submission (~100–300ms via a healthy proxy). Volume is low relative to typical form traffic, but three things scale badly:

• The proxy becomes a shared chokepoint — if it also fronts other services, a proxy incident silently disables bot protection or blocks all forms.
• Connection setup per request; enable keep-alive/pooling in the client so you don't pay TLS handshake per submission.
• Google-side quota/rate limits under burst load (campaign launches, bot floods) — the control fails precisely when traffic spikes.

Failure modes. Enumerate and instrument these up front:

• Proxy down / 502 / auth expiry → all verifications fail → forms either block (revenue loss) or silently degrade to unprotected (security loss). Pick one deliberately per form.
• TLS inspection → certificate validation errors; do not fix by disabling verification — pin the proxy CA instead.
• Credential rotation → proxy creds in .env/secret manager must rotate without redeploy drift.
• Latency creep → without connect_timeout, a hung proxy stalls PHP-FPM workers and cascades into an availability incident.
• Silent fail-open → the most dangerous mode: forms keep working, bots get through, nobody notices. Emit a metric and alert on degraded=true rate > 0 for more than N minutes.
• Secret exposure in proxy access logs if the request URI is logged — verify proxy logging config before go-live.

Ramp-up. Low for the build path: the team already operates Laravel's HTTP client, service container, and validation; the only new concepts are Google's response codes and proxy semantics. The Symfony-bundle path inverts this — the team would need Symfony bundle internals to debug wiring, for zero product benefit. Expected ramp: a mid-level engineer ships and tests the in-house verifier in 2–3 days; a junior can then add it to a new form in under an hour once the Blade component and rule exist.