Yandex Captcha Filament Laravel Package

Technical Evaluation

Architecture fit. This is a thin, purpose-built Filament form component wrapping Yandex SmartCaptcha via a separate SDK (tigusigalpa/yandex-smartcaptcha-php). Architecturally it is a classic Laravel package: service provider with auto-discovery, publishable config, a custom form field, and a validation rule. It slots cleanly into the Filament v4 form layer without touching application domain code — the integration surface is a single YandexCaptcha::make() field plus server-side rule enforcement.

Integration feasibility. Low friction on the happy path: two commands (composer require + vendor:publish) and a one-line field addition. Requirements are reasonable and current (PHP ^8.1, Laravel ^10–^12, Filament ^4). The dependency chain introduces a hard coupling to Filament v4 — this is the single biggest feasibility gate. Teams still on Filament v2/v3 cannot adopt it, and any Filament v5 upgrade is a breaking risk inherited from this package.

Technical risk. Several concerns worth flagging before adoption:

• Single-maintainer package (tigusigalpa) with v1.0.0 as the first release — low bus factor, no track record, no prior stability signal.
• External service dependency (Yandex Cloud) — operational/regional availability, latency, and account/billing requirements. Geopolitical and regulatory considerations may matter for some orgs given the vendor.
• Client-side rendering (Alpine.js + Yandex JS) means the captcha widget is third-party-script-dependent; CSP, ad-blockers, and network filtering can break it.
• "Zero config" claim vs. secret handling — the rule validates server-side, so secret/env var handling and test modes (force_pass/force_fail) need scrutiny to ensure they cannot be enabled in production accidentally.
• Security-critical component: a captcha that silently fails-open (or fails-closed) is a real risk; need to confirm failure behavior.

Key questions. Is the package actively maintained (issues, release cadence, response time)? What is the behavior on Yandex API timeout/error — fail open or closed? How are keys managed per-environment, and is force_pass/force_fail hard-guarded against production? Does it respect Laravel's HTTP client, retry, and timeout config? What's the CSP/asset-loading story? Is there test coverage or CI? What does the transitive SDK (yandex-smartcaptcha-php) bring in?

Integration Approach

Stack fit. Only fits projects already on Filament v4 with Laravel 10–12 / PHP 8.1+. For such projects it is a near drop-in for the form layer. For any Filament v3-or-earlier estate, it does not fit without a Filament upgrade — treat that as a separate program, not a captcha decision.

Migration path. No migration required in the data sense (no schema, no stored data beyond transient validation). If replacing an existing captcha (reCAPTCHA, hCaptcha, custom), the swap is field-for-field but requires: new Yandex Cloud account + keys, config publish, UI/UX differences (invisible mode), and updating any analytics or abuse-monitoring dashboards that referenced the old provider. Recommend running both behind a feature flag in staging first.

Compatibility. Version constraints are tight and sensible (^4.0 Filament, ^1.0 SDK). Risk is forward-compatibility: pinning to a v1 package on a v4 Filament means you inherit two independent upgrade clocks. Verify the transitive SDK's constraint range does not conflict with other Yandex-related or HTTP-client packages.

Sequencing.

1. Spike in a throwaway branch — validate keys, CSP, and the fail-open/closed behavior.
2. Confirm test modes are environment-gated (never live in prod).
3. Integrate on the lowest-risk form (e.g., contact form) behind a flag.
4. Broaden to auth surfaces (login/registration) only after abuse-monitoring is wired.
5. Vendor-risk review (maintainer responsiveness, license, roadmap) before committing to it as a strategic dependency.

Operational Impact

Maintenance. Low code footprint but maintenance is inherited risk: a brand-new v1.0.0 from an individual maintainer. Budget for periodic health checks (release cadence, open issues, dependency bumps). Filament major upgrades will likely require this package to follow — assume a lag and potential fork/PR burden.

Support. Support channels are GitHub Issues/Discussions and an email — no commercial SLA. For anything user-facing (login/registration), that is thin. Have an internal fallback plan (drop to the underlying SDK and a custom field) if the wrapper stalls.

Scaling. Runtime cost is dominated by the Yandex Cloud round-trip on validation, not by the package itself. Under high form-submission volume, watch: added latency on submit, external rate limits/quotas, and error-rate spikes. The widget is client-side, so CDN/script availability and per-request JS load are operational variables. No database or queue impact inherently.

Failure modes. The ones that matter:

• Yandex API down/timeout — validation behavior (fail-open = security hole; fail-closed = user lockout) determines blast radius.
• JS blocked (CSP, ad-blocker, regional filtering) — form may become unsubmittable; need graceful degradation.
• Misconfigured keys — silent validation failures look like user error.
• Test modes leaked to prod (force_pass) — critical if not guarded.
• Filament v5 upgrade — component breakage; captcha disappears or errors.
• Single-maintainer abandonment — no security patches; supply-chain exposure. Mitigations: server-side monitoring on validation error rates, explicit timeout/retry policy, alerting on captcha failures, and an incident runbook to disable the field if the provider degrades.

Ramp-up. Developer ramp-up is genuinely fast — the README/Quick Start, 8-language docs, and 6 examples get a capable Laravel dev productive in well under a day for the basic case. Operational ramp-up is the real cost: security/product must agree on failure behavior, SRE must add monitoring and the kill-switch runbook, and someone must own vendor/key management in Yandex Cloud. Recommend a short internal ADR capturing the vendor dependency and the fail-mode decision before broad rollout.

Verdict for TPM framing. Attractive, low-effort form-layer integration for teams already on Filament v4 who need Yandex SmartCaptcha specifically. Adoption should be gated on: confirming fail-open/closed semantics, verifying test-mode guards, accepting the single-maintainer/v1 risk, and having a fallback path. Not a fit for Filament v3-or-earlier estates or for teams requiring vendor SLAs without a fallback.