Recaptcha Bundle Laravel Package

Technical Evaluation

Architecture fit

The first thing to flag: despite being queued as a "Laravel/PHP package," victor-prdh/recaptcha-bundle is a Symfony bundle, not a Laravel package. It ships a Symfony DI extension, bundle class, and YAML configuration — there is no ServiceProvider, no publishable config/recaptcha.php, and no Laravel validation rule. It cannot be installed and used inside a Laravel application the way the intake ticket implies.

What is framework-agnostic and reusable is the underlying dependency, google/recaptcha, which is a plain PHP library (one verification call, one secret, one token). That is the real integration surface for us; the bundle is essentially a thin Symfony wiring layer around it.

Scope-wise this is also server-side verification only. No client-side widget, no JS, no blade/view helpers. Front-end integration (v2 checkbox, v3 score token issuance) remains our responsibility either way.

Net: architecture fit for this package in a Laravel estate is low. Fit for its core dependency is medium-high.

Integration feasibility

Feasible, but only by deliberately bypassing the bundle:

• Take google/recaptcha directly, pin it, and write a ~150-line Laravel binding: config file, singleton registration, a Recaptcha facade/contract, and a recaptcha validation rule.
• Effort estimate: 1–2 dev-days including tests and a staging verification pass.
• Alternative: adopt a Laravel-native captcha package instead, and treat this bundle as out of scope entirely.

The 2.2.0 release adds no bundle-level functionality — it is a single-line constraint widening (google/recaptcha now allows 2.x alongside the existing 1.x). So it does not change the integration calculus for us; it only changes which underlying library version Composer may resolve.

Technical risk

Overall: Medium, and almost all of it is transitive rather than in the release itself.

Nothing here is a breaking change for existing bundle consumers — 2.2.0 is additive. Urgency is low; this release is not a reason to adopt or accelerate.

Key questions

1. Does the bundle's CI actually run against both google/recaptcha 1.x and 2.x, or is the wider constraint aspirational?
2. Is the bundle's internal API usage identical across both majors (client injection, score threshold handling), or are there conditional code paths we'd inherit?
3. What is the project's release cadence and last-commit date? Has it shipped anything since tracking Google API deprecations?
4. Do we need v3 score thresholds, hostname validation, or Enterprise? Each narrows the candidate set.
5. Is there a maintained Laravel-native alternative we'd prefer to standardize on, retiring this evaluation entirely?
6. If we go direct on google/recaptcha, do we pin ^2.0 only (recommended) to keep a single code path?

Integration Approach

Stack fit

Laravel 10/11 on PHP 8.2 fits google/recaptcha 2.x cleanly: it wants PHP 8.1+, a PSR-18 HTTP client and a PSR-17 request factory, and Laravel already ships Guzzle 7, whose Client implements PSR-18. So wiring is a container binding, not a dependency fight.

The Symfony bundle itself does not fit and should not be forced. Do not attempt to register Symfony bundles or the Symfony DI container inside a Laravel app.

Migration path

Assuming an existing call-site set (custom code, or an older Laravel wrapper on google/recaptcha 1.x):

1. Pin the dependency explicitly: "google/recaptcha": "^2.0" — do not mirror the bundle's ^1 || ^2 tolerance. One code path only.
2. Adapt construction from new ReCaptcha($secret) to the 2.x creation surface, injecting Laravel's Guzzle client.
3. Re-verify call sites: verify() return shape, setScoreThreshold(), and any error/exception handling differences.
4. Replace ad-hoc verification with a single Recaptcha contract resolved from the container, plus a recaptcha validation rule, so future library bumps touch one file.
5. Remove the old integration once staging traffic is clean.

Compatibility

• PHP floor moves to 8.1 if 2.x is allowed — confirm every app in scope already meets it.
• Check for constraint conflicts on guzzlehttp/guzzle and guzzlehttp/psr7 against existing Laravel dependencies.
• Confirm timeout, proxy, and retry configuration parity with the current setup — these are common silent regressions.
• Verify behavior against Google's published test keys for both v2 and v3 before touching production keys.

Sequencing

1. Spike (0.5 day): throwaway branch, install google/recaptcha:^2.0, verify a real token end-to-end in staging.
2. Decide (0.5 day): build-our-own binding vs. adopt a Laravel-native package. Do not defer this — it determines everything downstream.
3. Build (1–2 days): config, contract, container binding, validation rule, unit tests with an HTTP client mock.
4. Rollout: feature-flag behind config (recaptcha.enabled), enable per-endpoint, starting with the lowest-traffic protected form.
5. Cleanup: remove legacy verification paths, document the pinning policy in the repo README.

Operational Impact

Maintenance

Runtime surface is tiny — one outbound verification call per protected request — but we own the Laravel binding, because the bundle won't provide it. Budget roughly 1–2 days per year for dependency bumps and re-verification against Google API changes. Pin to a single google/recaptcha major and treat major bumps as planned work, not composer update noise.

Support

Two decisions need to be made explicitly and documented, because they will otherwise be made accidentally during an incident:

• Fail-open vs. fail-closed when Google is unreachable. Default to fail-closed on high-risk flows (registration, password reset) and fail-open on low-risk ones.
• Config validation at boot. A missing or malformed secret currently degrades silently into "verification always fails" or "verification always passes" depending on the wrapper. Add a boot-time check that fails loudly outside production.

Log every verification outcome with the score and the failure reason; that is the only signal you'll have when conversion drops.

Scaling

CPU cost is negligible. The real cost is latency: a synchronous outbound HTTPS call to Google adds ~50–200 ms to any request that verifies a token. Mitigations:

• Verify only on state-changing endpoints, never on GETs or static assets.
• Set aggressive connect/read timeouts (2s / 3s) so a Google slowdown doesn't become our slowdown.
• Watch outbound quota and rate limits on the Google side during traffic spikes.
• Reuse a single HTTP client instance; don't construct a client per request.

Failure modes

Ramp-up

Low. A Laravel developer needs roughly half a day to learn the google/recaptcha verification API and the v2/v3 distinction. No Symfony knowledge is required, because no one on the team should be touching the bundle. The larger ramp-up cost is organizational: correcting the assumption that this is a drop-in Laravel package, and re-running intake against Laravel-native candidates or an in-house binding before committing to a path.