Laravel Invite Only : invitations polymorphiques, tokens et rappels

Laravel Invite Only (offload-project/laravel-invite-only) fournit un système d’invitations basé sur des tokens, avec suivi d’état (en attente, accepté, refusé, expiré, annulé), rappels automatiques et événements. Le design polymorphique permet d’inviter des utilisateurs vers n’importe quel modèle (équipe, projet, organisation, événement). Adapté aux SaaS, plateformes collaboratives et à la gestion d’événements.

Prérequis

• PHP 8.2+
• Laravel 11 ou 12
• Modèles User (ou équivalent) et un ou plusieurs modèles « invivables » (Event, Team, Project, etc.)

1. Installation

composer require offload-project/laravel-invite-only
php artisan vendor:publish --tag="invite-only-config"
php artisan vendor:publish --tag="invite-only-migrations"
php artisan migrate

2. Traits sur les modèles

• HasInvitations : sur le modèle invitable (Event, Team, Project…).
• CanBeInvited : sur le modèle invité (User).

use OffloadProject\InviteOnly\Traits\HasInvitations;

class Event extends Model
{
    use HasInvitations;
}

use OffloadProject\InviteOnly\Traits\CanBeInvited;

class User extends Authenticatable
{
    use CanBeInvited;
}

3. Envoyer des invitations

Une invitation :

$event->invite('user@example.com', [
    'role' => 'vip',
    'invited_by' => auth()->user(),
]);

Plusieurs invitations (avec gestion des échecs partiels) :

$result = $event->inviteMany(
    ['eric@example.com', 'paul@example.com', 'harris@example.com'],
    ['role' => 'vip', 'invited_by' => auth()->user()]
);

$result->successful; // invitations créées
$result->failed;     // emails en échec + raison

4. Accepter une invitation et réagir

L’acceptation se fait en général via un lien contenant le token. Écoutez InvitationAccepted pour attacher l’utilisateur au modèle (rôle, pivot, etc.) :

use OffloadProject\InviteOnly\Events\InvitationAccepted;

Event::listen(InvitationAccepted::class, function ($event) {
    $invitation = $event->invitation;
    $user = $event->user;
    $role = $invitation->role ?? null;

    $invitation->invitable->attendees()->attach($user->id, ['role' => $role]);
});

Autres événements : InvitationCreated, InvitationDeclined, InvitationCancelled, InvitationExpired.

5. Rappels automatiques

En config, définissez les jours auxquels envoyer un rappel et le nombre max de rappels :

'reminders' => [
    'after_days' => [3, 5],
    'max_reminders' => 2,
],

Puis planifiez la commande (par ex. dans routes/console.php) :

Schedule::command('invite-only:send-reminders --mark-expired')->daily();

--mark-expired marque les invitations dépassant la durée de validité (7 jours par défaut, configurable).

6. Métadonnées personnalisées

Le champ metadata (JSON) permet d’ajouter des infos sans changer le schéma :

$event->invite('speaker@example.com', [
    'metadata' => [
        'session_topic' => 'Laravel AI SDK',
        'time_slot' => '14:00',
    ],
]);

7. Gestion des erreurs

Le package lance des InvitationException avec des codes machine et des messages lisibles :

try {
    InviteOnly::accept($token);
} catch (InvitationException $e) {
    $e->getMessage();   // "Cette invitation a expiré."
    $e->resolution;     // "Créez une nouvelle invitation..."
    $e->errorCode;      // "INVITATION_EXPIRED"
}

Dépannage

Bonnes pratiques

• Protéger les routes d’acceptation/refus par token et limiter les tentatives (rate limiting).
• Utiliser metadata pour des données spécifiques au contexte (créneau, session) sans multiplier les colonnes.
• Logger les événements (création, acceptation, refus, expiration) pour l’audit.

Ressources

• Laravel News – Laravel Invite Only
• GitHub – offload-project/laravel-invite-only
• Documentation Laravel – Task Scheduling

Cet article s’inscrit dans notre série de guides technique et développement web. Pour un serveur ou une application sur-mesure, contact.