Download the PHP package vimatech/laravel-invitation without Composer

Email invitations to any Eloquent model

Generic email-based invitations for Laravel. Invite anyone to join, access, or accept an action related to any Eloquent model: Organization, Team, Project, Workspace, Document, and more.

Why Laravel Invitation?

• Invite users to any Eloquent model: not just teams
• Secure token-based workflow (HMAC by default)
• Framework-agnostic: no dependency on Jetstream, Breeze, or any starter kit
• Extensible acceptance handlers and custom notifications
• Production-ready with queued emails, i18n, and rate-limited routes

Quick Start

Subject: The model being invited to (Project, Team, Organization, Workspace, etc.). Set via ->for($model). An invitation without a subject is a "global" invitation.

Requirements

• PHP 8.3+
• Laravel 11, 12 or 13

Installation

The Packagist name is singular (vimatech/laravel-invitation) while the repository is plural. The published name cannot change without breaking existing installs, so it stays as it is: install the singular, read the plural.

Publish the configuration file (optional)

Publish and run migrations

Publish views (optional)

Usage

Basic invitation

Invitation to a User model

If you already have the user model, you can pass it directly, the email will be extracted automatically:

Invitation linked to a model

Using the HasInvitations trait

Accepting an invitation

Accepting after registration (new user)

Cancelling an invitation

Declining an invitation (by invitee)

The invitee can actively refuse an invitation:

Resending an invitation

Resend generates a new token and resets the expiration. Only pending or expired invitations can be resent. Accepted and cancelled invitations will throw an exception.

Querying invitations

Metadata

Store any custom data with an invitation:

Expiration

Invitations expire based on the expires_after_days config (default: 7 days). You can also set a custom expiration:

No expiration

For use cases like friend requests where invitations should stay active indefinitely:

Duplicate Policy

By default, sending a second invitation to the same email for the same subject throws an InvitationAlreadyExistsException:

To allow duplicate pending invitations, set this in your config:

Events

The following events are dispatched:

All events contain the $invitation property. InvitationAccepted also contains the $user.

Listening to events

Custom Acceptance Handler

Via callback

Via config

Create a class implementing the AcceptsInvitations contract:

Then set it in config:

Custom Notification

You can customize the invitation email in several ways:

Extend the default notification

Or create a fully custom notification

Your notification will receive the Invitation model and the plain token in its constructor.

Translations

All notification strings use Laravel's __() helper. Add translations via JSON files:

Public Routes

When routes.enabled is true (default), the package registers:

Configure in config/invitation.php:

Authentication and routes

The preview page (GET) is public: anyone with the link can view the invitation details.

The accept route (POST) does not enforce authentication by default. Two common patterns:

• Existing user: Add auth middleware, then call Invitations::accept($token, auth()->user())
• New user: Redirect to registration, then call Invitations::acceptForNewUser($token, $newUser) after signup, which verifies the registered email matches the invitation

To require authentication, add auth to the route middleware in config:

Database Schema

Token Security

• Tokens are generated using Str::random(64)
• Tokens are hashed before storage using HMAC (default) or bcrypt
• HMAC (default): deterministic, allows direct DB lookup (O(1))
• The HMAC key is invitation.token_hmac_key. Left unset it falls back to APP_KEY, which ties every pending invitation to it: rotating APP_KEY stops every outstanding token from matching and holders see "invitation not found". Set INVITATION_TOKEN_HMAC_KEY to decouple them. To adopt one without invalidating tokens already sent, set it to your current APP_KEY value first: the hashes are byte-identical. Rotate the two independently afterwards.
• Bcrypt: non-deterministic, requires iterating records (O(n)), resistant to DB leaks
• The plain token is only available at the moment of creation/sending
• Token verification uses constant-time comparison
• Route tokens are validated via regex constraint ([a-zA-Z0-9]{64})

Configuration

Full config options in config/invitation.php:

Exceptions

All exceptions extend InvitationException:

• InvitationNotFoundException: Token invalid or no matching invitation
• InvitationExpiredException: Invitation has expired
• InvitationAlreadyAcceptedException: Already accepted
• InvitationCancelledException: Invitation was cancelled
• InvitationDeclinedException: Invitation was declined by invitee
• InvitationAlreadyExistsException: Duplicate pending invitation

Testing

Contributing

See CONTRIBUTING.md.

Changelog

Please see CHANGELOG.md for recent changes.

Security

If you discover a security vulnerability, please review our security policy. Do not open a public GitHub issue.

Credits

Built and maintained by Vimatech. Created by Adel Zemzemi.

License

The MIT License (MIT). Please see License File for more information.