Captcha Laravel Package

Product Decisions This Supports

• Build vs. buy for form-level bot defense. A bespoke image CAPTCHA is a week or two of engineering with a good chance of getting the security-relevant details wrong (phrase entropy, timing-safe comparison, one-time invalidation, OCR hardening). gregwar/captcha is MIT-licensed, Composer-installable, and has an API narrow enough to learn from one README read. This is a "borrow" decision, not a "build" one.
• Per-surface friction scoping. The package exposes the knobs needed to make an endpoint-by-endpoint call rather than a library-by-library one: PhraseBuilder(4) for length and alphabet, digit-only phrases for low-literacy contexts, configurable width/height/font, JPEG/PNG/GIF output, background images, transparency, and distort/scatter/line effects. Registration, password reset, contact forms, guest checkout, and admin login can each be tuned for friction vs. solvability without adding a second dependency.
• Self-hosted vs. third-party challenge. Keeping generation and verification in-house avoids shipping user signals to a third party, sidesteps a DPA/GDPR review, removes a per-request external call and a vendor outage mode, and keeps the flow testable offline in CI. For regulated or privacy-sensitive products this is often the deciding factor, not the price (which is zero either way).
• Roadmap slot for a security-hardening milestone. v2.1.0 moved phrase generation to a CSPRNG; v2.0.0 raised the floor to PHP 8.2+, added strict typing and package-specific exceptions. If we're on PHP 8.1, this package is a forcing function for an upgrade we should schedule anyway — frame it as a discrete hardening task, not an open-ended migration.
• A forcing function for accessibility. The library emits an image challenge and nothing else. Adopting it makes us decide — explicitly — what the alternative path is (audio challenge, email-verified fallback, allowlist, or lowering friction for authenticated users). Better to surface that in design than to discover it in an audit.
• Correct placement in the defense stack. This is one control among rate limiting, honeypots, disposable-email/phone checks, and device signals. Treating it as the primary defense is how teams end up over-investing in image distortion and under-investing in throttling.

When to Consider This Package

Adopt it when:

• You want a self-hosted image challenge on a handful of Laravel forms and the goal is hours of work, not a sprint.
• Your runtime is PHP 8.2+ and you can confirm GD plus writable font paths exist in local, CI, and production containers — a container that lacks ext-gd fails at runtime, not at install.
• The threat model is opportunistic spam, scrapers, and scripted form submission, not a funded adversary.
• You accept that session binding, expiry, one-time use, and constant-time comparison are your code. getPhrase() and testPhrase() are primitives; the Laravel glue (session key, TTL, invalidate-on-success, validation rule, rate limiter) is a small but real deliverable — scope it as such.
• You want a small, auditable, MIT-licensed dependency with no service contract and a stable surface.
• You're on Filament and can use marcogermani87/filament-captcha instead of hand-rolling the view/validation wiring.

Look elsewhere when:

• Accessibility is a hard requirement and no alternative path is funded. Image CAPTCHAs are a WCAG liability regardless of implementation quality.
• You face adversarial pressure at scale. buildAgainstOCR() is honest about its own ceiling: it loops until ocrad fails, which says little about a current ML solver. At that threat level the answer is risk-based/invisible scoring, not a harder image.
• You need invisible or app-native challenges (mobile SDKs, no visual step) — hCaptcha/Turnstile/reCAPTCHA are the comparison, each with its own privacy and vendor tradeoffs.
• You are pinned below PHP 8.2 and would be holding v1.x. Plan the upgrade instead of adopting a pinned version.
• You expect a first-party Laravel experience — service provider, publishable config, captcha validation rule, Blade component. This is framework-agnostic; if that glue exceeds your maintenance appetite, evaluate a Laravel-specific wrapper.
• Note the packaging signal: the "0 dependents" figure reflects what the crawl captured, not reality (Filament and Symfony wrappers exist), so don't read it as abandonment — but do read the single-maintainer, small-contributor-base profile as a factor in how much glue you're willing to own.

How to Pitch It (Stakeholders)

For executives: We have public forms — signup, password reset, contact, guest checkout — that scripted abuse can hit at near-zero cost to the attacker. We can close that gap with a free, MIT-licensed library we generate and verify ourselves: no new vendor, no per-request fee, no user data leaving our systems, no procurement or DPA cycle, and no external call in the request path. The integration is roughly one engineering day plus tests, and the recent releases already fixed the weak-randomness issue that would have been the obvious audit finding. It is a low-cost hardening line item, not a platform bet: I'd recommend piloting on two or three high-abuse endpoints, measuring spam volume before and after, and deciding on broader rollout from that data. The one thing it does not solve is accessibility — image challenges are a known WCAG problem — so the pilot should ship alongside a documented alternative path, or we should not ship it at all.

For engineering: Framework-agnostic PHP library, composer require gregwar/captcha, requires PHP 8.2+ and GD. CaptchaBuilder gives you build(), inline(), output(), save(), getPhrase(), testPhrase(). We own the Laravel wiring: session storage with TTL, single-use invalidation, a custom validation rule, a cache-busting image route, and a rate limiter in front of the verify endpoint. Keep phrase comparison constant-time and never log the phrase.