Captcha Laravel Package

Product Decisions This Supports

• Build vs. buy for bot mitigation on public forms: v1.0.0 establishes this as a zero-vendor, zero-API-key option — it removes the recurring cost line and third-party data-processing agreement that come with reCAPTCHA/hCaptcha/Turnstile. That's a procurement and privacy-review decision, not just a technical one.
• Choosing between captcha strategies (image math vs. invisible score-based): The bundle ships an explicit, human-visible challenge with server-side answer storage in session. This is a defensible choice for low-to-moderate abuse volumes and privacy-sensitive audiences (no Google script, no user fingerprinting), but it is a weaker signal than risk-scoring vendors for high-volume credential-stuffing or scraping.
• Form-level UX policy: Features like per-render tokens (no cross-tab session collisions), error_bubbling disabled by default, and distinct "wrong answer" vs. "expired token" messages are direct inputs to the signup/contact/checkout error-state design. The refresh endpoint also lets us decide whether a failed submission re-renders a fresh challenge or reuses one.
• Accessibility and support burden trade-off: An image-only, low-quality-JPEG challenge is inherently hostile to screen readers and to users with cognitive or visual impairments. Adopting this is a decision to accept an accessibility gap (and likely a manual/audio alternative requirement) in exchange for simplicity — that needs to be an explicit, documented call, not a side effect.
• Scoping a roadmap item: This release is a credible "ship it this sprint" component for a single Symfony app, not a platform-wide standard. It informs whether captcha is a 1-day integration or a multi-week build.

When to Consider This Package

Consider it when:

• The application is on Symfony 6.4 / 7.x / 8.x with PHP 8.4+ — this is a hard gate; the release notes describe a Symfony bundle (CaptchaType, ValidCaptcha constraint, Twig form theme, auto-registered routes), not a Laravel package. Despite the framing of this assessment, there is no Laravel service provider, validation rule, or Blade integration here. Do not plan a Laravel adoption around v1.0.0.
• You need self-hosted, no-third-party captcha for data-residency, GDPR, or offline/air-gapped reasons.
• Expected abuse is opportunistic bots, not determined adversaries. The stated defenses (noise pixels, random lines, low-quality JPEG) are explicitly "basic OCR" resistance — modern ML-based solvers will defeat this. Treat it as a speed bump, not a security control.
• You have ext-gd available and a session-backed state model. Session-stored answers mean it will not work cleanly for stateless/API-only flows, multi-node setups without shared session storage, or mobile/native clients.
• You want minimal configuration overhead — auto-registered routes and form theme are a genuine win for time-to-ship.

Look elsewhere when:

• You are on Laravel (no support), or on PHP < 8.4, or Symfony < 6.4.
• You need accessibility conformance (WCAG 2.1 AA) out of the box — no audio alternative is mentioned.
• You face targeted or high-volume abuse, or need per-request risk scoring rather than a binary puzzle.
• You need horizontally scaled, session-less validation — require shared session infrastructure first.
• You want a maintained, long-lived dependency: v1.0.0 is a first release, with no stated LTS, security policy, or maintainer track record. That's a real adoption risk for a security-adjacent component.

How to Pitch It (Stakeholders)

For executives: This is a self-hosted bot filter for public web forms that eliminates a third-party vendor, its subscription cost, and its data-sharing exposure. It runs entirely on our own servers with no API keys and no external calls, which simplifies privacy and procurement review. The trade-off is that it is a basic deterrent — appropriate for routine form spam, not for defending against a determined attacker — and it introduces an accessibility gap we would need to address separately before shipping to all audiences.

For engineering: A first-release (v1.0.0) Symfony bundle targeting PHP 8.4+ and Symfony 6.4/7.x/8.x, requiring ext-gd. It provides a compound CaptchaType form field, a ValidCaptcha constraint, an auto-registered Twig theme and /captcha/refresh endpoint, server-side session answer storage with 10-minute token TTL and a 5-token-per-session cap, and CSP-nonce-aware JavaScript. Integration cost is low. Key caveats: it is Symfony-only — not Laravel; it is session-dependent, so confirm shared session storage before relying on it across multiple nodes; it is image-only with no audio fallback; and it carries standard v1.0.0 maturity risk on a security-adjacent component. Recommend a scoped pilot on one low-risk public form, with a documented accessibility workaround and a fallback plan, before broad rollout.