Laravel Recaptchav3 Laravel Package

Technical Evaluation

Architecture fit

• Thin, single-purpose adapter that lives entirely in Laravel's cross-cutting validation layer: service provider + publishable config + Facade/helper + a custom validation rule. No migrations, no models, no queues, no views to override.
• Integration point is the standard FormRequest::rules() / $request->validate() pipeline, so it composes with existing form objects rather than requiring an architectural change.
• Coupling surface is narrow and explicit: (1) Google's siteverify REST contract, (2) the token transport convention (hidden g-recaptcha-response field), (3) two env vars (RECAPTCHAV3_SITEKEY, RECAPTCHAV3_SECRET).
• The package deliberately scopes to backend verification only. Frontend token generation (grecaptcha.execute) is the implementing team's responsibility — this is the single largest hidden cost in the assessment.

Integration feasibility

• Install path is trivial: composer require, two env vars, optional vendor:publish for the config. A Laravel developer can have a rule firing in an afternoon.
• Real effort sits outside the package: adding the reCAPTCHA v3 script, wiring execute() to form submit, handling token single-use and ~2-minute TTL, and defining an action-naming convention that the backend rule can validate against.
• Estimated effort for a first form: 1–3 dev days including frontend, plus QA time for threshold tuning. Additional forms are near-zero marginal cost once the JS helper exists.
• Testability depends on whether the underlying HTTP call is fakeable (Http::fake) — this must be confirmed before adoption, otherwise CI will hit Google or need network stubbing.

Technical risk

• Score governance risk: v3 returns a 0.0–1.0 score, not a pass/fail. Choosing the threshold is a product decision with direct conversion impact; too high blocks legitimate users, too low provides no protection. This requires an observe-then-enforce rollout, not a big-bang cutover.
• Failure-mode ambiguity: the critical unknown is behavior on Google timeout/5xx. Fail-open silently disables protection; fail-closed creates an availability dependency on a third party for your login/payment flows. This must be read from the source, not assumed.
• Client-side dependency: ad blockers, privacy browsers, and consent-gated setups block the Google script, producing missing tokens for real users. No package can solve this; the team must own a degradation policy.
• Maintainer concentration: single-maintainer package. Mitigant is that the codebase is small enough (~a few hundred lines) to vendor or fork at negligible cost.
• Version drift: Laravel major releases move fast; verify the composer constraint against your target framework version before committing.

Key questions for the maintainer/team

• Which Laravel and PHP versions are supported by the latest release, and is there a CI matrix proving it?
• Does the validation rule accept per-rule action and minimum-score parameters, or is score threshold global config only?
• What is returned/raised on HTTP error, timeout, or malformed Google response — and is fail-open configurable?
• Does it validate that the returned action matches the expected action (prevents cross-form token reuse)?
• Is the response object exposed (score, hostname, challenge timestamp) for logging and analytics?
• Can the HTTP client be faked in tests?
• Any Enterprise/AMP/recaptcha-v2 fallback support, or is that out of scope?
• Licensing/privacy: any DPA or data-residency implications of shipping the Google script?

Integration Approach

Stack fit

• Fit is strongest in a conventional Laravel app using Blade, Livewire, or Inertia with server-rendered form validation. It slots into existing FormRequest classes without touching controllers.
• Lower fit where forms are fully API-driven with no Laravel validation layer, or where a SPA owns submit logic and token generation is duplicated client-side.
• No database, cache, or queue assumptions — stateless per request, which is exactly what you want in a horizontally scaled deployment.

Migration path

• From no captcha: additive. Add script + token field + rule. Expect a small, invisible UX change (v3 is frictionless, no checkbox).
• From reCAPTCHA v2: net removal of the widget; the frontend changes are the bulk of the work, the backend swap is a one-line rule change. Keep the same hidden field name to minimize churn.
• From another v3 package: map env var names and config keys, keep the token field convention, and re-verify threshold semantics (some packages treat "min score" differently or default to 0.5).

Compatibility

• Pin the package version explicitly in composer.json; do not float a caret range on a single-maintainer dependency in a production app.
• Validate the config key namespace and Facade alias don't collide with an existing captcha package during any parallel-run period.
• Separate Google key pairs per environment (staging vs. production) with hostname restrictions — never share secrets across environments.

Sequencing

1. Spike in a branch against your actual Laravel/PHP version; confirm the rule, the HTTP fake story, and error behavior.
2. Provision keys for staging and production in the Google admin console with hostname allowlists.
3. Frontend token plumbing: shared JS helper that calls execute(sitekey, {action}) and injects the token; establish the action naming convention here.
4. Observe mode: deploy the rule on a low-risk form (contact/newsletter) with the threshold set to 0.0 and log score + action for 1–2 weeks. This builds the score distribution you need to pick a threshold.
5. Tune and enforce per form, starting at a conservative threshold and tightening with data.
6. Roll to sensitive surfaces last (login, registration, password reset, checkout), each with its own threshold and its own rollback flag.

Operational Impact

Maintenance

• Low ongoing maintenance: small API surface, MIT license, no runtime services to operate. The recurring cost is version bumps aligned to Laravel major releases.
• Keep a one-page internal note covering: where keys live, who owns the Google console account, how to rotate secrets, and how to change thresholds. Key rotation is the most likely operational task and the most likely to cause an outage if undocumented.
• Have an exit plan on file: because the package is thin, vendoring the verifier into app/ is a realistic 1-day contingency if the project is abandoned.

Support

• GitHub issues only — no SLA, no vendor. Internalize triage: distinguish "our keys/threshold are wrong" from "Google is degraded" from "package bug." Log the raw Google response code so this is diagnosable.
• Add alerting on the rate of verification failures, not just absolute counts; a sudden spike is the earliest signal of a key misconfiguration or a Google-side incident.

Scaling

• Every protected submission incurs one synchronous HTTPS round trip to Google (~100–400 ms typical). This is added directly to request latency on your most latency-sensitive endpoints — measure p95 before and after on login and checkout.
• Tokens are single-use, so no caching or deduplication is possible; the cost is strictly per submission. Size against Google's free tier (roughly 1M assessments/month) and confirm the billing/quota path for peak events.
• Stateless design means no scaling concerns on your side; the constraint is outbound egress and Google availability.

Failure modes

Ramp-up

• A mid-level Laravel developer reaches productive use in under a day; the README covers installation and the rule, and the surface area is small enough to read in full.
• The non-obvious skills are product/ops, not engineering: picking score thresholds from data, deciding fail-open vs. fail-closed per endpoint, and owning the Google console relationship. Assign those explicitly — they are the most common cause of a botched reCAPTCHA v3 rollout.