laranail/captcha

laranail/captcha is not published to Packagist, so there is no registry-version badge to show: see Install.

One captcha contract for Laravel across eleven providers — from Cloudflare Turnstile to self-hosted arithmetic — with environment-scoped credentials, a database-backed settings store, and the token checks most integrations skip.

Requires PHP ^8.4.1 and Laravel ^13.0.

Install

composer require laranail/captcha

That is the whole setup. The default provider is self-hosted: no account, no keys, no third-party request, no JavaScript. Publish the config only when you want to change something — php artisan laranail::captcha.install.

This family resolves through git VCS repositories rather than Packagist — deliberately, and the version badge above points at the git tag for that reason. The repository entries are already in composer.json. See Installation.

Quick start guide and usage

Getting started

Nothing to configure: the default provider is self-hosted arithmetic, so a fresh install works with no account, no keys and no JavaScript. Two optional commands:

php artisan laranail::captcha.install   # publish config/laranail/captcha.php, only to change something
php artisan laranail::captcha.doctor    # report the active provider and where each credential resolves from

To switch provider, set CAPTCHA_PROVIDER, CAPTCHA_SITE_KEY and CAPTCHA_SECRET_KEY in .env.

Usage

<form method="post" action="/register">
    @csrf

    <x-laranail-captcha::captcha />

    <button type="submit">Create account</button>
</form>

$request->validate([
    'email' => ['required', 'email'],
    'captcha' => ['laranail_captcha'],
]);

Bind a token to one form, so a token minted for another form cannot be replayed on login:

use Simtabi\Laranail\Captcha\Rules\Captcha;

$request->validate([
    'captcha' => [Captcha::for('login')],
]);

Switching to Turnstile later is one config line. The markup and the rule do not change.

The two axes

Captcha and bot management solve different problems and fail in opposite directions.

	Captcha	Bot management
Runs	on one form, at submit	on every request, at the edge
Asks	did a human solve a challenge	does this connection look automated
Providers	Turnstile, hCaptcha, reCAPTCHA v2/v2-invisible/v3/Enterprise, Friendly Captcha, Arkose, ALTCHA, math	DataDome
On provider outage	fails closed — letting a submission through defeats the point	fails open — blocking every request to stop some traffic is a self-inflicted outage

One captcha provider is active at a time, chosen by config and resolved through a frozen enum allow-list. Bot management is separate middleware you opt into.

Documentation

The hosted copy at opensource.simtabi.com is the canonical home; every link below also renders on GitHub.

Guides

• Installation — requirements, VCS repositories, what publishing gets you
• Getting started — protected form to verified submission in one page
• Configuration — every block, and what each one changes
• Providers — the eleven, what each is good at, and what each costs you
• Credentials — database, config and test keys, and the order they resolve in
• Architecture — ports, adapters, actions, and why the layering is enforced
• Security model — what is guaranteed, how, and what is not promised
• Migration — from rahul900day/laravel-captcha and from laranail/toolkit
• Release — versioning and what CI gates

Reference

• Turnstile · hCaptcha · reCAPTCHA — the hosted big three
• Friendly Captcha · Arkose Labs — EU-hosted, and enterprise
• ALTCHA · Math — self-hosted, no account, no third party
• Blade components — the one tag, the two tags, and CSP nonces
• Validation rule — why it is implicit, and which field it reads
• Commands — doctor, keys, install, cache-clear
• Bot management — the edge tier, and why it fails open
• Testing — faking it in your app, and the adapter contract suite
• Octane — what is cleared between requests, and what is kept

Recipes

• Use your own settings model
• Ask for a second factor instead of rejecting
• Protect a Livewire form
• Add a custom provider

Project

• Changelog
• Upgrade guide
• Contributing
• Security policy

Stability

Pre-1.0. The public surface — the Captcha facade, the captcha rule, the Blade components and the CaptchaAdapter port — is settled and covered by tests. Internals may still move.

Local development

composer install
composer test     # pest
composer lint     # pint, phpstan (level max), rector

The live group hits real provider endpoints with their published test keys and is excluded by default: vendor/bin/pest --group=live.

Sister packages

Part of the laranail family of Laravel package tools. The captcha module that used to live in laranail/toolkit was relocated here.

Community

Questions and ideas belong in Discussions; bugs in Issues.

Contributing & security

See CONTRIBUTING.md. Report vulnerabilities privately to opensource@simtabi.com — see SECURITY.md, and never in a public issue.

License

MIT — see LICENSE. Copyright (c) 2026 Simtabi LLC. Originally rahul900day/laravel-captcha, copyright (c) Rahul Dey.