Contexto

offload-project/laravel-waitlist es un paquete para Laravel 11/12/13 (PHP 8.3+) que permite gestionar una o varias listas de espera. Incluye:

Un modelo Eloquent Waitlist (una lista de espera con nombre y un slug) y un modelo WaitlistEntry (una persona esperando en una lista).
Un WaitlistService (resuelto a través de la fachada Waitlist) con los métodos for(), create(), add(), invite(), reject(), sendVerification(), verify(), y ayudantes para consultas y conteos.
Un flujo opcional de verificación de correo electrónico con una ruta publicada /waitlist/verify/{token}.
Un puente opcional hacia offload-project/laravel-invite-only: al llamar a Waitlist::invite() se crea una Invitation real (token, expiración, eventos) y se persiste la clave foránea en WaitlistEntry::$invitation_id.
Dos notificaciones: WaitlistInvited (opt-in mediante auto_send_invitation) y VerifyWaitlistEmail.
Eventos del ciclo de vida en OffloadProject\Waitlist\Events: WaitlistCreated, WaitlistEntryAdded, WaitlistEntryVerified, WaitlistEntryInvited, WaitlistEntryRejected, además de WaitlistEntrySubscribed, WaitlistEntryUnsubscribed y MailingListSyncFailed.
Una integración con listas de correo (fachada MailingList, MailingListManager) que sincroniza las entradas con Mailchimp, Kit (ConvertKit) o Audienceful en un trabajo encolado, con controladores log y array y un hook extend() para otros.
Excepciones tipadas: UnverifiedEntryException (cuando se intenta invitar a una entrada no verificada y la compuerta de verificación está activa) y MailingListException (fallos de controlador/credenciales/id-lista/API).

Aplica este skill cuando trabajes en una aplicación Laravel que tenga offload-project/laravel-waitlist en el composer.json, o cuando el usuario pida ayuda con Waitlist, WaitlistEntry, las fachadas Waitlist o MailingList, o flujos de listas de espera en este paquete.

Reglas

Uso de fachadas

Usa la fachada Waitlist (OffloadProject\Waitlist\Facades\Waitlist) — no instancies WaitlistService directamente. La fachada es el punto de entrada soportado.
Para apuntar a una lista de espera específica, encadena Waitlist::for($slugOrIdOrModel)->.... Sin for(...), las llamadas operan sobre la lista de espera por defecto (creada automáticamente en el primer uso mediante getDefault()).
Waitlist::for(...) muta el estado interno de un servicio singleton. Para procesos de larga duración (trabajadores de cola, Octane), llama a for(...) para cada operación en lugar de confiar en que el contexto anterior persista.

Listas de espera vs. entradas

Crea listas de espera con Waitlist::create(string $name, string $slug, ?string $description = null, bool $isActive = true). El slug es el identificador canónico — eso es lo que esperan for(...) y find(...).
Añade entradas mediante Waitlist::for($slug)->add($name, $email, $metadata = []). No llames a WaitlistEntry::create([...]) directamente cuando quieras que se ejecute el flujo de verificación — add() activa automáticamente sendVerification() cuando waitlist.verification.enabled es true.
La restricción única en waitlist_entries es ['waitlist_id', 'email'], no solo email. Una misma persona puede unirse a varias listas de espera.

Invitaciones

Invita mediante Waitlist::invite($entryOrId, $options = []). No llames a $entry->markAsInvited() por sí solo cuando quieras notificaciones y un registro de Invitation — invite() crea la Invitation de laravel-invite-only, la vincula mediante invitation_id y marca la entrada como invitada.
$options se pasa a InviteOnly::invite(...). Claves comunes: 'invited_by' (Model o int — por defecto auth()->user()), 'role', 'metadata', 'expires_at'. No dupliques claves que ya hayas establecido en waitlist.invitable.metadata_mapper — las $options explícitas ganan mediante array_merge.
Si waitlist.verification.enabled es true y waitlist.verification.require_before_invite es true, llamar a invite() en una entrada no verificada lanza UnverifiedEntryException. Cógela explícitamente en flujos orientados al usuario; no la ocultes bajo un \Throwable genérico.
La notificación WaitlistInvited es opt-in (waitlist.auto_send_invitation por defecto es false). La notificación de invitación de laravel-invite-only se envía siempre. Activa auto_send_invitation solo cuando quieras un segundo correo electrónico con la marca de la lista de espera además del otro.

Verificación

Activa la verificación mediante Waitlist::sendVerification($entry) — genera un token nuevo (generateVerificationToken() sobrescribe cualquier token existente) y envía VerifyWaitlistEmail. No implementes tu propia generación de tokens; usa la del paquete para que la ruta de verificación siga funcionando.
Confirma tokens mediante Waitlist::verify($token). Devuelve la WaitlistEntry en caso de éxito, null si el token es desconocido. Después de la verificación, el token se borra (un solo uso).
Personaliza la notificación de verificación mediante la configuración waitlist.verification.notification; recibe la WaitlistEntry en su constructor. Lee el token de $entry->verification_token y llama a route('waitlist.verify', ['token' => $entry->verification_token]).
La ruta de verificación del paquete se monta bajo waitlist.routes.prefix (por defecto waitlist) con waitlist.routes.middleware (por defecto ['web']). Para usar tu propio controlador, establece waitlist.routes.enabled => false y llama a Waitlist::verify($token) desde tu acción.

Estado y comprobaciones

Los estados de entrada son los literales de cadena pending, invited, rejected. Prefiere $entry->isPending(), isInvited(), isRejected() sobre comparaciones directas de cadenas.
El estado de verificación reside en verified_at y verification_token. Comprueba mediante isVerified() y isPendingVerification(); no compares marcas de tiempo directamente.
Para la compuerta de UI "bloquear hasta verificar", usa isPendingVerification() (token establecido, aún no verificado). isVerified() solo devuelve false para entradas que nunca iniciaron la verificación — esos dos estados son diferentes.

Cableado de elementos invitables (invitable)

Cuando la aplicación anfitriona invita a personas a una entidad específica (Equipo, Organización, Proyecto), configúralo una vez en config/waitlist.php bajo invitable:
- invitable.model — cadena de clase; el paquete llama a ::first(). Úsalo solo para aplicaciones de un solo inquilino.
- invitable.resolver — clausura fn(WaitlistEntry $entry) => Model|null para el caso multiinquilino. Extrae el ID del inquilino de $entry->metadata u otra columna.
- invitable.metadata_mapper — clausura fn(WaitlistEntry $entry) => array para traducir los metadatos de la entrada en metadatos de invitación (por ejemplo, ['role' => 'beta-tester']).
No codifiques un invitable por cada punto de llamada. Si diferentes flujos necesitan diferentes invitables, usa la clausura resolver con un discriminador en metadata.

Eventos

Conéctate al ciclo de vida usando los eventos del propio paquete en lugar de envolver la fachada o sondear la tabla. Viven en OffloadProject\Waitlist\Events y cada uno lleva el modelo como una propiedad de solo lectura ($event->entry, $event->waitlist).
Los eventos del ciclo de vida se disparan desde los modelos (WaitlistEntryAdded mediante $dispatchesEvents al crear; el resto desde markAsInvited() / markAsRejected() / markAsVerified()), por lo que los oyentes siguen ejecutándose incluso para código que evita la fachada.
Usa Event::fake([SpecificEvent::class]) en las pruebas, no un Event::fake() simple — un fake genérico también se traga WaitlistEntryAdded, lo que impide que el oyente de la lista de correo se ejecute.

Sincronización de listas de correo

Actívala con waitlist.mailing_list.enabled y elige un controlador (mailchimp, kit, audienceful, log, array). Conecta una lista de espera a una lista con Waitlist::for($slug)->connectMailingList($listId, $driver = null) — el id de la lista es un id de audiencia de Mailchimp, un id de formulario de Kit (o id de etiqueta cuando list_type es tag), o un id de publicación de Audienceful (o nombre de etiqueta cuando list_type es tag). Las listas de espera sin lista propia recurren al list_id configurado en el controlador.
No construyas tu propio oyente de "suscribir al registrarse". La suscripción es automática y sigue la configuración de verificación: con waitlist.verification.enabled desactivado, la entrada se sincroniza en add(); con ella activada, la entrada se sincroniza después de Waitlist::verify(). Ese orden es deliberado — una dirección no confirmada nunca debe llegar a la newsletter.
Para cualquier cosa más allá de la suscripción — etiquetar al invitar, eliminar al rechazar, mover entre listas — escucha los eventos del ciclo de vida y llama a MailingList::tagEntry($entry, [...]) o Waitlist::unsubscribeFromMailingList($entry). No añadas esos efectos secundarios dentro de los controladores de la aplicación anfitriona.
La sincronización se ejecuta a través de trabajos encolados (SyncEntryToMailingList, UnsubscribeEntryFromMailingList). Mantén mailing_list.queue.enabled activo en producción para que los registros nunca bloqueen la API del proveedor. Rellena las filas existentes con php artisan waitlist:sync-mailing-list [slug] [--all] [--force] o Waitlist::for($slug)->syncMailingList().
Añade un servicio que el paquete no incluya implementando OffloadProject\Waitlist\Contracts\MailingListDriver y registrándolo con MailingList::extend('name', fn (array $config) => new YourDriver(...)) desde un proveedor de servicios. No bifurques los controladores incluidos.
En las pruebas, usa MailingList::fake(), que intercambia el ArrayDriver en memoria, ejecuta las sincronizaciones en línea y expone hasSubscriber(), subscribers() y tagsFor(). Recurre a Http::fake() solo cuando quieras afirmar la solicitud exacta que envía un controlador real.

Prohibiciones

No realices cambios en el ciclo de vida mediante llamadas directas update() ($entry->update(['status' => 'invited'])). Usa markAsInvited() / markAsRejected() / markAsVerified() para que los casts, los efectos secundarios (marcas de tiempo, borrado de tokens) y los eventos se mantengan consistentes. Mejor aún: impulsa todo a través de la fachada.
No edites las migraciones publicadas para añadir columnas — escribe una migración de seguimiento en la aplicación anfitriona. El paquete puede añadir columnas en versiones futuras y asumirá el esquema publicado.
No subclases Waitlist ni WaitlistEntry; ambas son final. Añade comportamiento en el lado de la aplicación anfitriona mediante oyentes en los eventos del paquete, o extendiendo el servicio mediante un enlace personalizado en el contenedor de tu aplicación.

Ejemplos

Lista de espera única (sin configuración)

use OffloadProject\Waitlist\Facades\Waitlist;

$entry = Waitlist::add('John Doe', '[email protected]', ['source' => 'landing-page']);

Waitlist::invite($entry, [
    'invited_by' => auth()->user(),
    'expires_at' => now()->addDays(14),
]);

Múltiples listas de espera

Waitlist::create('Programa Beta', 'beta');
Waitlist::create('Acceso VIP', 'vip');

Waitlist::for('beta')->add('Jane Smith', '[email protected]');
Waitlist::for('vip')->add('Bob Wilson', '[email protected]');

$pendientesBeta = Waitlist::for('beta')->getPending();
$conteoVip      = Waitlist::for('vip')->count();

Flujo de verificación

// config/waitlist.php
'verification' => [
    'enabled' => true,
    'require_before_invite' => true,
    'notification' => \OffloadProject\Waitlist\Notifications\VerifyWaitlistEmail::class,
],

use OffloadProject\Waitlist\Exceptions\UnverifiedEntryException;
use OffloadProject\Waitlist\Facades\Waitlist;

$entry = Waitlist::add('John Doe', '[email protected]');
// Correo de verificación enviado automáticamente.

try {
    Waitlist::invite($entry);
} catch (UnverifiedEntryException) {
    return back()->withErrors(['email' => 'Por favor, verifica tu correo electrónico primero.']);
}

Cableado de un modelo invitable (invitaciones a equipo)

// config/waitlist.php
'invitable' => [
    'model'    => null,
    'resolver' => fn (\OffloadProject\Waitlist\Models\WaitlistEntry $entry) =>
        \App\Models\Team::find($entry->metadata['team_id'] ?? null),
    'metadata_mapper' => fn (\OffloadProject\Waitlist\Models\WaitlistEntry $entry) => [
        'role' => $entry->metadata['role'] ?? 'member',
    ],
],

Luego:

Waitlist::for('beta')->add('Jane', '[email protected]', [
    'team_id' => $team->id,
    'role'    => 'admin',
]);

Cuando luego llames a Waitlist::invite($entry), la invitación resultante de laravel-invite-only estará limitada a ese equipo con role=admin.

Notificación de verificación personalizada

use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;
use OffloadProject\Waitlist\Models\WaitlistEntry;

class CustomVerifyWaitlistEmail extends Notification
{
    public function __construct(public WaitlistEntry $entry) {}

    public function via($notifiable): array
    {
        return ['mail'];
    }

    public function toMail($notifiable): MailMessage
    {
        $url = route('waitlist.verify', ['token' => $this->entry->verification_token]);

        return (new MailMessage)
            ->subject('Confirma tu lugar en la lista de espera')
            ->greeting("¡Hola {$this->entry->name}!")
            ->action('Verificar correo electrónico', $url);
    }
}

// config/waitlist.php
'verification' => [
    'enabled' => true,
    'notification' => \App\Notifications\CustomVerifyWaitlistEmail::class,
],

Sincronización de registros con Mailchimp

// config/waitlist.php
'mailing_list' => [
    'enabled' => true,
    'default' => 'mailchimp',
    'drivers' => [
        'mailchimp' => [
            'key' => env('MAILCHIMP_API_KEY'),   // el sufijo lleva el centro de datos, p.ej. -us14
            'list_id' => env('MAILCHIMP_LIST_ID'),
        ],
    ],
],

// Una audiencia por lista de espera (opcional — de lo contrario se usa el list_id de la configuración).
Waitlist::for('beta')->connectMailingList('a1b2c3d4e5');

// Suscrito automáticamente, al añadir o al verificar según la configuración.
Waitlist::for('beta')->add('Jane Smith', '[email protected]');

Reaccionando al ciclo de vida

use Illuminate\Support\Facades\Event;
use OffloadProject\Waitlist\Events\WaitlistEntryInvited;
use OffloadProject\Waitlist\Events\WaitlistEntryRejected;
use OffloadProject\Waitlist\Facades\MailingList;
use OffloadProject\Waitlist\Facades\Waitlist;

Event::listen(fn (WaitlistEntryInvited $event) => MailingList::tagEntry($event->entry, ['invited']));
Event::listen(fn (WaitlistEntryRejected $event) => Waitlist::unsubscribeFromMailingList($event->entry));

Probando un flujo de lista de correo

use OffloadProject\Waitlist\Facades\MailingList;
use OffloadProject\Waitlist\Facades\Waitlist;

MailingList::fake();

Waitlist::for('beta')->add('Test', '[email protected]');

// Afirmar
MailingList::assertSubscribed('[email protected]');
MailingList::assertHasSubscriber('[email protected]');

offload-project/laravel-waitlist

¿Qué es laravel-waitlist?

Preguntar en tu IA favorita

Documentación