En este tutorial vamos a ver cómo integrar reCAPTCHA en Laravel con Livewire. Construiremos un formulario de contacto que utiliza la casilla de reCAPTCHA v2, valida los datos en el servidor y muestra el resultado dentro de la misma página.
Contenidos
Usaremos el componente Blade y el trait de Laracaptcha para que Livewire pueda recibir y comprobar el token. Al final tendrás también las indicaciones necesarias para adaptar la integración a reCAPTCHA v3.
Introducción
Para seguir los pasos conviene conocer estas herramientas:
- PHP: Tutorial de PHP.
- HTML: Tutorial de HTML.
- Livewire: Ejemplo de un formulario con Laravel y Livewire.
- Consola: Introducción a la línea de comandos.
Necesitarás PHP 8.3 o posterior y Composer. El formulario terminado tendrá este aspecto:

Instala las dependencias
Al combinar Livewire con reCAPTCHA hay dos estados que deben mantenerse coordinados: los campos del componente PHP y la respuesta que Google genera en el navegador. Laracaptcha conecta ambas partes y ofrece el método verifyCaptcha() para autorizar la operación.
El ejemplo utiliza componentes de clase de Livewire 4 sobre Laravel 13. Podemos instalar sus dependencias con estos comandos:
composer create-project laravel/laravel:^13.0 contacto-recaptcha-livewire
cd contacto-recaptcha-livewire
composer require edulazaro/laracaptcha:^1.2 livewire/livewire:^4.0
Configura reCAPTCHA
Comenzaremos con reCAPTCHA v2 y las claves que Google publica para pruebas. Con ellas aparecerá la advertencia de desarrollo dentro del widget. Añade este bloque a tu archivo .env y reserva las claves del sitio real para producción:
CAPTCHA_DRIVER=recaptcha_v2
RECAPTCHA_KEY=6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI
RECAPTCHA_SECRET=6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe
CACHE_STORE=file
SESSION_DRIVER=file
MAIL_MAILER=log
MAIL_FROM_ADDRESS=web@example.com
MAIL_FROM_NAME="Mi aplicación"
CONTACT_RECIPIENT=contacto@example.com
El archivo de sesión y la caché nos permiten probar este formulario sin preparar una base de datos. Si vienes de otra configuración, ejecuta php artisan config:clear después de modificar las variables.
Prepara el correo de contacto
Para que el formulario haga algo útil, enviaremos el mensaje a una dirección configurada en el servidor. Durante el desarrollo lo dejaremos en el log. Esto permite revisar el remitente y el contenido sin depender de una cuenta SMTP mientras ajustamos la parte de Livewire.
Generaremos el correo de contacto antes de escribir la acción de Livewire:
php artisan make:mail ContactMessage --view=mail.contact
La consulta se representará mediante app/Mail/ContactMessage.php. Su constructor recogerá el contenido y envelope() indicará a quién podemos responder:
<?php
namespace App\Mail;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Address;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
class ContactMessage extends Mailable
{
public function __construct(
public string $senderName,
public string $senderEmail,
public string $messageBody,
) {}
public function envelope(): Envelope
{
return new Envelope(
subject: 'Consulta desde la web',
replyTo: [new Address($this->senderEmail, $this->senderName)],
);
}
public function content(): Content
{
return new Content(text: 'mail.contact');
}
}
El cuerpo del mensaje saldrá de resources/views/mail/contact.blade.php. Bastará con imprimir estos datos:
Nombre: {{ $senderName }}
Email: {{ $senderEmail }}
{{ $messageBody }}
Para elegir a quién enviar las consultas, añade el archivo config/contact.php con esta entrada:
<?php
return ['recipient' => env('CONTACT_RECIPIENT', 'contacto@example.com')];
Con esta configuración, responder al mensaje llevará al email del visitante; el correo saldrá desde la cuenta que hayas configurado en Laravel.
Crea el componente de Livewire
La lógica irá en app/Livewire/ContactForm.php. Tendremos una propiedad por campo y un método público send. El token pertenece al trait WithCaptcha; una vez validados los datos, llamaremos a su comprobación antes de construir el correo:
php artisan make:livewire ContactForm --class
<?php
namespace App\Livewire;
use App\Mail\ContactMessage;
use EduLazaro\Laracaptcha\Livewire\WithCaptcha;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\View\View;
use Livewire\Component;
class ContactForm extends Component
{
use WithCaptcha;
public string $name = '';
public string $email = '';
public string $message = '';
public string $notice = '';
public function send(): void
{
$this->resetErrorBag();
$this->notice = '';
$key = 'contact:'.request()->ip();
if (RateLimiter::tooManyAttempts($key, 5)) {
$this->addError('form', 'Demasiados intentos. Espera un minuto antes de repetir.');
return;
}
RateLimiter::hit($key, 60);
$data = $this->validate([
'name' => ['required', 'string', 'max:100'],
'email' => ['required', 'email', 'max:254'],
'message' => ['required', 'string', 'min:10', 'max:3000'],
]);
$this->verifyCaptcha(action: 'contact');
Mail::to(config('contact.recipient'))->send(new ContactMessage(
$data['name'], $data['email'], $data['message'],
));
$this->reset('name', 'email', 'message');
$this->notice = 'Hemos recibido tu mensaje.';
}
public function render(): View
{
return view('livewire.contact-form');
}
}
Define las rutas
La URL de entrada puede mantenerse como una ruta web que renderiza Blade. No necesitaremos un controlador para el envío, ya que Livewire resolverá esa parte. Escribe lo siguiente en routes/web.php:
<?php
use Illuminate\Support\Facades\Route;
Route::view('/contacto', 'contact')->name('contact.create');
Enlaza los campos y el captcha
La vista generada para el componente está en resources/views/livewire/contact-form.blade.php. Vamos a enlazar sus campos y colocar la casilla antes del botón. Los mensajes de Laravel quedarán junto al campo correspondiente:
<main>
<p class="eyebrow">reCAPTCHA · Laravel + Livewire</p>
<h1>Escríbenos</h1>
<p>Envíanos tu consulta desde este formulario.</p>
@if ($notice)
<p class="success" role="status">{{ $notice }}</p>
@endif
@error('form') <p class="error" role="alert">{{ $message }}</p> @enderror
<form wire:submit="send">
<label for="name">Nombre</label>
<input id="name" wire:model="name" required maxlength="100" autocomplete="name">
@error('name') <p class="error">{{ $message }}</p> @enderror
<label for="email">Email</label>
<input id="email" wire:model="email" type="email" required maxlength="254" autocomplete="email">
@error('email') <p class="error">{{ $message }}</p> @enderror
<label for="message">Mensaje</label>
<textarea id="message" wire:model="message" required minlength="10" maxlength="3000"></textarea>
@error('message') <p class="error">{{ $message }}</p> @enderror
<div class="captcha">
<x-laracaptcha::widget wire:model="captcha" action="contact" language="es" />
@error('captcha') <p class="error">{{ $message }}</p> @enderror
</div>
<button wire:loading.attr="disabled" wire:target="send">Enviar mensaje</button>
</form>
</main>
La llamada verifyCaptcha(action: 'contact') queda preparada para verificar esa acción si después eliges v3. Con v2 se comprueba el token sin utilizar una acción.
Fíjate en el reinicio del captcha: el trait lo solicita después de verificar y limpia su propiedad PHP. Esto evita conservar en el componente una respuesta que ya se ha consumido. El contador de intentos se ejecuta en la acción pública, de manera que cubre los envíos posteriores al primer renderizado.
Muestra la página de contacto
El componente necesita una página contenedora. Crea resources/views/contact.blade.php para cargarlo junto a los estilos y los scripts de Livewire:
<!doctype html>
<html lang="es">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Formulario de contacto</title>
<link rel="stylesheet" href="{{ asset('contacto.css') }}">
@livewireStyles
</head>
<body>
<livewire:contact-form />
@livewireScripts
</body>
</html>
Añade los estilos
La apariencia será deliberadamente sencilla para que puedas integrar después el formulario con tus componentes. Crea public/contacto.css y coloca en él estas reglas, que utilizará la vista contenedora:
* { box-sizing: border-box; }
body { margin: 0; background: #f2f5f9; color: #172033; font: 16px/1.5 system-ui, sans-serif; }
main { width: min(560px, calc(100% - 32px)); margin: 40px auto; padding: 24px; background: white; border: 1px solid #dce3ed; border-radius: 16px; }
h1 { margin: 4px 0 12px; font-size: 28px; }
.eyebrow { color: #4255b5; font-weight: 700; font-size: 14px; }
label { display: block; margin: 16px 0 5px; font-weight: 600; }
input, textarea { width: 100%; padding: 10px; border: 1px solid #aab6c7; border-radius: 6px; font: inherit; }
textarea { min-height: 100px; resize: vertical; }
.captcha { margin: 20px 0; }
button { width: 100%; padding: 12px; color: white; background: #344caa; border: 0; border-radius: 7px; font: inherit; cursor: pointer; }
button:disabled { opacity: .6; cursor: wait; }
.error { color: #a31521; }
.success { padding: 10px; background: #e5f5eb; color: #195e35; }
@media (max-width: 420px) { main { width: calc(100% - 16px); padding: 12px; margin: 16px auto; } }
Prueba el formulario
Una vez arrancado Laravel, entra en /contacto y completa la casilla junto con los campos. El mensaje de éxito aparecerá al terminar y el captcha se reiniciará. Podrás consultar el correo en el log y volver a enviar sin que desaparezca el componente.
Vamos a servir el componente con Artisan:
php artisan serve
Podrás seguir el resultado del envío desde la terminal:
tail -f storage/logs/laravel.log
Adapta la integración a reCAPTCHA v3
Si eliges v3 para este componente, necesitarás sus propias claves. El par de pruebas de v2 no sirve para evaluar la puntuación; configura las variables de esta manera:
CAPTCHA_DRIVER=recaptcha_v3
RECAPTCHA_V3_KEY=tu_clave_publica_v3
RECAPTCHA_V3_SECRET=tu_clave_secreta_v3
RECAPTCHA_V3_MIN_SCORE=0.5
Hemos dejado contact tanto en el widget como en la llamada a verifyCaptcha. Livewire recibirá el token a través de la propiedad captcha y el trait lo reiniciará después de comprobarlo.
El umbral 0.5 debe ajustarse según las visitas de la aplicación. Consulta la documentación de v3 para interpretar las puntuaciones. verifyCaptcha también comprobará que la acción recibida sea contact.
Revisa la configuración del servidor
El formulario de producción debe utilizar sus propias credenciales y un servicio real de envío. Además de HTTPS, conviene configurar los dominios esperados en la respuesta:
CAPTCHA_HOSTNAMES=ejemplo.com,www.ejemplo.com
Registra en esa lista los dominios de tu web al cambiar a las claves definitivas. Google admite una sola verificación por token y limita su duración a dos minutos. El componente nunca necesita conocer el secreto.
Fuera del desarrollo necesitarás cambiar MAIL_MAILER y preparar el servicio de correo. Puedes llevar ese envío a una cola, siempre después de aceptar el captcha en la acción.
Comprueba la validación con tests
Vamos a probar la acción del componente con Captcha::fake(), que sustituye al proveedor durante el test. Para revisar errores del captcha puedes cambiarlo por Captcha::fake(false). En la aplicación mantendremos la verificación normal de reCAPTCHA.
Vamos a crear un test específico para esta acción:
php artisan make:test ContactFormTest --phpunit
La clase de prueba necesitará los siguientes imports y un método que invoque la acción de Livewire:
use App\Livewire\ContactForm;
use App\Mail\ContactMessage;
use EduLazaro\Laracaptcha\Facades\Captcha;
use Illuminate\Support\Facades\Mail;
use Livewire\Livewire;
public function test_contact_form_sends_a_verified_message(): void
{
Captcha::fake();
Mail::fake();
Livewire::test(ContactForm::class)
->set('name', 'Edu')
->set('email', 'edu@example.com')
->set('message', 'Una consulta de prueba para el formulario.')
->set('captcha', 'test-token')
->call('send')
->assertHasNoErrors()
->assertSet('captcha', '');
Mail::assertSent(ContactMessage::class);
}
Inicia la prueba con php artisan test --filter=ContactFormTest. Incluye después los casos sin token, con verificación negativa y con un token usado, comprobando que no se mandan mensajes.
Finalizando
Tenemos el formulario de Livewire conectado a reCAPTCHA y listo para recibir mensajes. Puedes sustituir el correo por otra operación del servidor manteniendo el mismo orden de comprobaciones. Si utilizas v3, revisa el comportamiento de las puntuaciones con visitas reales antes de endurecer el umbral.
-
Turnstile con Livewire: Cómo integrar Turnstile en Laravel con Livewire.
-
reCAPTCHA con Blade: Cómo integrar reCAPTCHA en Laravel.
Esto ha sido todo. ¡Espero que te resulte útil!