Captcha Bundle Laravel Package

Product Decisions This Supports

• Scoping bot defense to unauthenticated, high-cost public forms. This is the decision it enables: which public form endpoints get a human check. Registration, login, password reset, contact/support, newsletter, guest checkout, promo-code redemption — anywhere a fake submission costs money (spam triage, fake accounts, credential stuffing, support queue load, SMS/email spend). It does not address authenticated-user abuse, account takeover, scraping of authenticated content, or API abuse. Framing it as a general "security feature" in a roadmap will overpromise; framing it as "form-fill friction" is accurate.
• Build vs. buy, settled in favor of buy. A text-image CAPTCHA is image generation, font rasterization, distortion/interpolation effects, session binding, per-key storage, expiry, and garbage collection. That is weeks of engineering plus ongoing upkeep. The underlying gregwar/captcha library collapses that to a dependency. The PM-level decision to record is: "we will not build our own image CAPTCHA." This package is the artifact that holds that line.
• A framework-fit decision that must be made before anyone estimates. This repository is a Symfony Form Component bundle, not a Laravel package. composer require gregwar/captcha-bundle in a Laravel app is a dead end — the bundle registers against Symfony's bundle/DI/form-type machinery. For a Laravel codebase the real decision is: adopt the standalone gregwar/captcha library and build the Laravel-side integration ourselves (a validation rule, session/state handling, a route for image serving, Blade partial for the widget, cache/GC for generated images). That is a meaningfully larger piece of work than "one Composer dependency," and it should be scoped as such — roughly a small, well-bounded ticket, not a ten-minute install. Getting this distinction wrong inflates the perceived win and then disappoints at delivery.
• Friction as a tunable product knob rather than a code change. The configuration surface is unusually PM-friendly: length/width/height (difficulty), humanity (only 1 in N forms shows a challenge after a success — a direct lever on completion rate), bypass_code (QA and internal testing), disabled (globally off in dev/staging so QA isn't blocked), invalid_message (user-facing copy, translatable), reload (recovery affordance). This lets product dial challenge frequency and messaging without an engineering ticket, which is what makes a measured rollout or a conversion-vs-spam experiment feasible at all.
• Privacy and vendor posture. Challenges are generated and stored server-side on our own infrastructure. No user data, fingerprint, or behavioral signal leaves our systems, there is no third-party script in the page, no additional cookie-consent surface, and no vendor DPA to negotiate. In a regulated, health, finance, education, or EU-facing product this is the single strongest argument for choosing this over reCAPTCHA or hCaptcha, and it is worth writing down explicitly in the privacy review rather than leaving implicit.
• Cost and dependency posture. MIT licensed, no per-request billing, no seat minimums, no vendor rate limits, no external availability dependency on the challenge path. At scale, reCAPTCHA/hCaptcha enterprise tiers are a real line item; this is zero marginal cost, traded against the maintenance burden of a small open-source dependency.
• A staged-rollout plan the package actually supports. The defensible sequence is: pilot on one low-traffic, high-spam form → measure spam volume delta and form completion-rate delta → widen. Per-form configuration and the disabled flag make each step reversible, which is what a PM needs to approve a pilot rather than a flag-day launch.

When to Consider This Package

Adopt when:

• The stack is Symfony 6.x–8.x on PHP ≥ 8.0.2 for the bundle itself (v2.5.0 added Symfony 8 support; older Symfony lines map to older bundle majors per the compatibility table). For Laravel, the equivalent decision is to adopt the standalone gregwar/captcha library and own the integration layer — treat that as the real unit of work.
• The forms are server-rendered HTML. This is a form-type/widget integration; it is not designed for JSON APIs, SPA front-ends, or mobile native clients. If the endpoint is consumed by a React/Vue/mobile client, this is the wrong shape and you should be looking at token-based challenges instead.
• Bot pressure is low to moderate: form spam, scripted signups, naive scrapers, credential-stuffing scripts hitting a login form. Not a determined adversary.
• You want self-hosted, zero-cost, no-third-party-script verification and privacy/legal has flagged external CAPTCHA vendors.
• Engineering bandwidth is the binding constraint and a small, contained integration beats a bespoke build.
• You need configurability without forking: multiple CAPTCHAs on one page (session_key), embedded base64 vs. file vs. URL-served images (as_file/as_url for multi-server deployments or legacy browser support), custom fonts and background images, and automatic image cleanup via expiration/gc_freq.

Look elsewhere when:

• You are on Laravel and expect a drop-in. As above: the bundle does not apply. The library does, but budget for the wiring, and check whether a maintained Laravel-specific CAPTCHA package better fits the framework's conventions before committing to a hand-rolled integration.
• Accessibility is a hard requirement. Image-only CAPTCHA with no documented audio alternative is a WCAG 2.x barrier on any public-facing flow. Under ADA/EAA obligations, or with a materially visually-impaired user base, this needs a documented alternative path — which this package does not appear to provide. Do not ship it on a mandated public flow without solving that separately, and get that decision in writing from legal/accessibility rather than discovering it in an audit.
• You need risk-scoring, invisible, or behavioral challenges. This is a static text-image challenge with distortion. It is defeatable by OCR and modern vision models. It raises the cost of abuse; it does not eliminate it. reCAPTCHA v3, hCaptcha, or Cloudflare Turnstile are solving a different problem, and if the threat model is "determined attacker with automation," this is the wrong tool.
• You expect targeted or high-volume abuse. There is no rate limiting, no IP reputation, no telemetry on pass/fail rates here. Those are adjacent infrastructure builds — plan them as separate line items, not as part of "adding a CAPTCHA."
• You need operational visibility. No dashboard, no metrics, no analytics on challenge outcomes. If you want to know whether the CAPTCHA is working (spam down? completion rate holding?), you must instrument it yourself around the validation result.
• You need vendor-grade support or an SLA. ~350 stars, low visible dependent count, and a release history driven by a small contributor set. It is maintained and actively kept current with Symfony releases (Symfony 8 support landed, PHP/dependency modernization shipped), and the README references PHPStan and ECS quality tooling — which is a genuine positive signal. But this is a community dependency with no support contract, and that risk belongs in the adoption decision, especially if it lands on a revenue-critical flow.
• The team needs a drop-in, framework-idiomatic component with strong test coverage. This package's visible maturity signals are readme and releases; there is no prominently documented test suite or security policy. That does not disqualify it, but it shifts the burden of regression testing onto your own integration tests.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: We have a recurring, low-grade abuse problem on our public forms: fake signups, contact-form spam, and scripted login attempts that consume support time and, in some cases, real money in downstream email/SMS. Buying a CAPTCHA vendor solves it but introduces a third-party script on every page, a data-sharing arrangement our privacy posture makes awkward, and a per-request cost that scales with our traffic. This package lets us add a self-hosted human check for zero marginal cost, zero third-party data sharing, and roughly one to two engineering days of work on the relevant forms. It is the cheap, reversible pilot: run it on one form for four weeks, measure spam volume and form completion rate, decide whether to widen or drop it. The trade is honest — it stops scripts and naive bots, not a determined attacker, and we'd need to add an accessibility alternative before it goes anywhere public-facing.

For engineering — the framing that saves a sprint: Be clear about what this is and isn't. It's a Symfony Form bundle wrapping the standalone gregwar/captcha generator. In a Symfony app the integration is genuinely two lines ($builder->add('captcha', CaptchaType::class)) plus optional YAML config, and Flex auto-registers it — that is a real, honest win. In a Laravel app the bundle is unusable; we adopt the underlying library and build the FormRequest validation rule, the session/replay handling, an image-serving route, a Blade partial, and cache cleanup ourselves. The library's options are strong and we should use them deliberately rather than shipping defaults: humanity to reduce challenge frequency for legitimate repeat users, disabled for local/staging so QA isn't blocked, expiration/gc_freq so image files don't accumulate, as_url if we're behind multiple app servers (session-key whitelisting is already handled), and invalid_message translated rather than left as "Bad code value." Two engineering notes worth stating up front: this is defeatable by modern OCR/vision models, so pair it with rate limiting on the same endpoints rather than treating it as a standalone control; and there is no built-in telemetry, so we need to instrument pass/fail and submission rates on our side if we want to prove it worked.

For security/privacy/legal: The verification happens entirely on our infrastructure; no user data, fingerprint, or behavioral signal is transmitted to a third party, and no additional tracking script or cookie-consent surface is introduced. That is the primary reason to pick this over reCAPTCHA/hCaptcha. Two caveats to record: it is an image-based challenge with no documented audio alternative, which is a WCAG 2.x gap we must address before deploying on any public-facing flow; and it is a deterrent, not a control — it raises the cost of automated abuse but does not prevent a motivated actor, so it belongs alongside rate limiting and monitoring, not in place of them.