Yandex Captcha Filament Laravel Package

Product Decisions This Supports

• Build vs. buy for bot mitigation: this package turns "add captcha to our Filament admin/portal forms" from a multi-day integration into an afternoon, so the defensible default for Filament-based products is buy the wrapper, build the surrounding policy (where to enforce captcha, thresholds, fallback behavior).
• Market-entry decisions (RU/CIS): Yandex SmartCaptcha is the regionally expected option; first-class support for 8 languages (RU/EN/BE/KK/TT/UK/UZ/TR), light/dark theming, and RTL readiness means captcha no longer blocks a localization or market-launch roadmap item.
• Conversion vs. abuse trade-off: invisible mode plus JS callbacks (success/error/network-error) lets you decide per-form whether friction, telemetry, or completion rate wins — a product call you can now ship and measure rather than debate.
• Scope of protected surfaces: supported use cases (login, registration, contact forms, custom Filament pages) map directly to the forms most exposed to credential stuffing, spam, and signup farming. This informs which flows get hardened in a quarter.
• Roadmap sequencing for anti-abuse: because validation is a server-side rule (YandexCaptchaRule), you can treat captcha as one layer in a stack (rate limiting, email verification, honeypots) and phase it independently.
• Testability as a delivery constraint: force_pass / force_fail test modes mean QA/E2E suites and CI can run against protected forms — removes the usual "captcha breaks our tests" objection and de-risks shipping to staging.
• Platform currency: Laravel 10/11/12 + PHP 8.1+ + Filament 4 support signals alignment with a modern stack; adopting it is consistent with (not a detour from) an upgrade roadmap.

When to Consider This Package

Adopt when all of these hold:

• Your app runs Filament v4 on Laravel 10–12 / PHP 8.1+, and the forms you need to protect are Filament forms or custom Filament pages.
• Your user base or target market includes Russia/CIS, or you already use Yandex Cloud and want captcha consolidated under one vendor and billing relationship.
• You need low-friction captcha (invisible mode) with localization, and you want it shipped in days, not a sprint.
• You want server-side verification with minimal custom code and a testable path for CI/staging.
• You are comfortable with a thin, replaceable abstraction — the component is a single field in a form schema, so switching providers later is a contained change.

Look elsewhere or proceed with caution when:

• You need reCAPTCHA / hCaptcha / Cloudflare Turnstile — different regional expectations, existing Google/Cloudflare contracts, or a preference for those vendors' risk scoring.
• Your protected forms are not Filament forms (public marketing site, API endpoints, mobile clients) — the underlying yandex-smartcaptcha-php package is the relevant layer, not this one.
• You require enterprise support, SLAs, or a security review — this is a v1.0.0, single-maintainer package published November 2024, with a dependency on the same author's base library and no public production track record yet. Budget a spike/pilot and pin versions.
• You need advanced bot mitigation (behavioral scoring, device fingerprinting, adaptive challenges) — a captcha widget alone is not a fraud platform.
• You're on Filament 3 or earlier, or on Laravel versions outside 10–12 — no compatibility path is claimed.
• You operate in a jurisdiction where routing user challenge traffic to Yandex is a privacy/procurement issue; confirm data-residency and vendor-approval status before committing.

How to Pitch It (Stakeholders)

For executives: This is a small, cheap accelerator for a security and market-expansion item we already need. It adds Yandex SmartCaptcha to our Filament-based forms — login, registration, contact — in roughly a day of engineering instead of a multi-day build, with no new platform commitment. It strengthens our position in Russian-speaking markets (8 languages, RTL-ready) while giving us an invisible mode that protects forms without hurting signup conversion. Cost and lock-in are both low: it's one field in a form, and swapping providers later is a contained change. Principal risk is maturity — it's a brand-new 1.0 release from a single maintainer — so we recommend a scoped pilot on one or two forms behind a config flag, version-pinned, before broader rollout.

For engineering: Auto-discovered service provider, publishable config via env vars, strict typing on PHP 8.1+, PSR-12, and usage that is literally one schema entry (YandexCaptcha::make('captcha')->required()) plus a server-side YandexCaptchaRule. Per-component overrides for keys/settings, optional error logging, JS callbacks for success/error/network-error, Alpine.js-powered Blade view, light/dark theming. Critically, force_pass/force_fail test modes keep our E2E and CI suites green. Constraints to note: Filament 4 only, depends on tigusigalpa/yandex-smartcaptcha-php, and we should read the source (it's small — one component, one rule, one provider) and pin versions rather than rely on 1.0.0 semantics.