Search by

abitechdev / antibot-laravel

abitechdev

Protege los formularios de Laravel contra bots con Cloudflare Turnstile o Google reCAPTCHA desde una sola regla de validación.

v1.0.1 2026-11-15 21:12 UTC

This package is auto-updated.

Last update: 2026-11-15 21:16:21 UTC


README

AntiBot para Laravel

Protege tus formularios de bots con una sola regla de validación

Versión en Packagist Descargas Integración continua PHP 7.3 o superior Laravel 8 a 13 Licencia MIT

Inicio rápido  |  Uso  |  Configuración  |  En las pruebas  |  English


Los formularios públicos, como el registro, el inicio de sesión o el de contacto, reciben envíos automáticos de bots. AntiBot valida en el servidor el token que generan Cloudflare Turnstile o Google reCAPTCHA, con la misma regla para los tres proveedores. Cambiar de uno a otro es cambiar una variable de entorno.

El formulario envía el token, AntiBotRule lo verifica con el proveedor, y la solicitud sigue al controlador o se rechaza con 422 o 403

Inicio rápido

1. Instala el paquete. Laravel lo registra solo.

composer require abitechdev/antibot-laravel

2. Agrega la clave secreta de tu proveedor al .env.

ANTIBOT_DEFAULT=turnstile
TURNSTILE_SECRET=tu-clave-secreta

3. Valida el formulario con la regla.

use Abitech\AntiBot\Rules\AntiBotRule;

$request->validate([
    'email' => ['required', 'email'],
    'cf-turnstile-response' => ['required', new AntiBotRule()],
]);

Listo. Si el token no es válido, Laravel devuelve el error de validación como con cualquier otra regla.

Características

🛡️ Una sola API

Turnstile, reCAPTCHA v2 y reCAPTCHA v3 se validan igual, con new AntiBotRule().

🧩 Regla, middleware o fachada

Se usa donde encaja mejor, sin repetir código en cada formulario.

🎯 Acción y puntaje

Comprueba que la acción del token sea la esperada y que reCAPTCHA v3 pase el puntaje mínimo.

🧪 Fácil de probar

ANTIBOT_ENABLED=false apaga la verificación en local y en las pruebas automatizadas.

💬 Mensajes en español

Los errores llegan traducidos y se pueden cambiar publicando sus textos.

✅ Probado de Laravel 8 a 13

La integración continua corre las pruebas en cada versión, con su PHP mínimo.

Proveedores

Proveedor ANTIBOT_DEFAULT Comprueba
turnstile Token y acción
recaptcha_v2 Token
recaptcha_v3 Token, acción y puntaje

Compatibilidad

Laravel PHP mínimo Estado
13 8.3 ✅ Probado
12 8.2 ✅ Probado
11 8.2 ✅ Probado
10 8.1 ✅ Probado
9 8.0 ✅ Probado
8 7.3 ✅ Probado

Uso

Con la regla de validación

Es la forma recomendada. Valida el token junto con la IP de quien envía el formulario. Con reCAPTCHA el campo se llama g-recaptcha-response.

'g-recaptcha-response' => ['required', new AntiBotRule()],

Con el middleware

Protege una ruta completa. Lee el token de la cabecera X-AntiBot-Token o del campo antibot_token, y responde 403 si no es válido.

Route::post('/contacto', ContactoController::class)->middleware('antibot');

Con la fachada

Para decidir en el código qué hacer con el resultado.

use Abitech\AntiBot\Facades\AntiBot;

$resultado = AntiBot::verify($token, $request->ip());

if (! $resultado->success) {
    // $resultado->errors trae los códigos de error del proveedor.
}
Exigir una acción

Turnstile y reCAPTCHA v3 adjuntan al token el nombre de la acción. Si no coincide con la esperada, la validación falla. Así un token generado en otro formulario no sirve en este.

new AntiBotRule('login');                               // En la regla
Route::post('/login', ...)->middleware('antibot:login'); // En el middleware
AntiBot::verify($token, $request->ip(), 'login');       // Con la fachada
Usar otro proveedor en una sola parte

El proveedor por defecto sale de ANTIBOT_DEFAULT. Para usar otro en un lugar concreto, pídelo por su nombre.

AntiBot::driver('recaptcha_v3')->verify($token, $request->ip(), 'suscripcion');

Configuración

Todo se configura con variables de entorno.

Variable Por defecto Para qué sirve
ANTIBOT_ENABLED true false aprueba todo sin consultar al proveedor
ANTIBOT_DEFAULT turnstile Proveedor de la regla y el middleware
TURNSTILE_SECRET Clave secreta de Cloudflare Turnstile
RECAPTCHA_V2_SECRET Clave secreta de reCAPTCHA v2
RECAPTCHA_V3_SECRET Clave secreta de reCAPTCHA v3
RECAPTCHA_V3_SCORE 0.5 Puntaje mínimo de reCAPTCHA v3, de 0 a 1

Cada proveedor acepta también su *_TIMEOUT, en segundos (10 por defecto). Para cambiar algo más, publica el archivo de configuración o los mensajes:

php artisan vendor:publish --tag=antibot-config
php artisan vendor:publish --tag=antibot-translations

En las pruebas

Apaga la verificación en phpunit.xml para que las pruebas no dependan de internet.

<env name="ANTIBOT_ENABLED" value="false"/>

Para probar el rechazo, deja el paquete encendido y simula la respuesta del proveedor con Http::fake().

Más información

Licencia

Publicado con la licencia MIT. Puedes usarlo, modificarlo y distribuirlo, también en proyectos comerciales.


Hecho en Huánuco, Perú, por Abimael Fernandez