antibot-laravel maintained by abitechdev
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.
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
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.
}
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
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
- 📚 Guía completa, con la configuración y el uso avanzado.
- 🔒 Política de seguridad. Las vulnerabilidades se reportan en privado.
- 🤝 Guía para contribuir. Las propuestas son bienvenidas.
- 📝 Cambios de cada versión.
Licencia
Publicado con la licencia MIT. Puedes usarlo, modificarlo y distribuirlo, también en proyectos comerciales.