Laravel Magiclink Laravel Package

Getting Started

1. Install the package

   composer require cesargb/laravel-magiclink
   

2. Publish and run migrations

   php artisan vendor:publish --provider="CesarGB\MagicLink\MagicLinkServiceProvider"
   php artisan migrate
   

   This creates the magic_links table and publishes config/magiclink.php.

3. Add the trait to your authenticatable model (usually User):

   use CesarGB\MagicLink\Traits\MagicLinkable;
   
   class User extends Authenticatable
   {
       use MagicLinkable;
   }
   

4. Generate your first magic link:

   $link = $user->createMagicLink();
   // $link->url is the signed URL to send to the user
   

5. Protect a route with the middleware (required since v2.29.0):

   Route::get('/magic-login', function () {
       return 'You are logged in as '.auth()->user()->email;
   })->middleware(['web', 'magiclink']);
   

   The middleware validates the token, logs the user in, and redirects or continues.

Where to look first

• config/magiclink.php – expiration, max uses, redirect behaviour, guard selection.
• CesarGB\MagicLink\MagicLink facade – main API for creating and managing links.
• MagicLinkable trait – model-level helper methods.
• The magiclink middleware – enforces token validation and authentication.

First use case
Passwordless login: generate a link for a user and email it. When the user clicks it, the middleware authenticates them and redirects to your dashboard.

Implementation Patterns

Passwordless login flow

• Generate a link in a controller or listener:

  $link = $user->createMagicLink();
  Mail::to($user)->send(new MagicLoginMail($link->url));
  

• Point the link to a route protected by magiclink middleware. After authentication, use the configured redirect (on_success_redirect) or return a custom response.

Private content access

• Generate a link for a specific resource:

  $link = $user->createMagicLink([
      'redirect' => route('private.document', $document),
  ]);
  

• Protect the target route with magiclink. The middleware authenticates the user and then redirects to the intended URL.

Customising the link lifecycle

• Set expiration (minutes) and max uses in config or per-link:

  $link = $user->createMagicLink(['expires_in' => 60, 'max_uses' => 1]);
  

• Use MagicLink::create($user, $options) for a fluent alternative.
• Revoke links early with $link->delete() or by pruning the database.

Integration tips

• Send links via queued notifications to avoid blocking requests.
• Combine with rate limiting on the route that generates links to prevent abuse.
• Use Laravel’s signed URL validation alongside the package’s token check for defence in depth.
• Listen to package events (e.g. MagicLinkCreated, MagicLinkUsed) to log or audit access.
• For multiple guards, set the guard option in config or per link so the middleware logs the user into the correct guard.

Custom actions and extension points

• Override the default response after successful authentication via the on_success_redirect config or by adding your own middleware after magiclink.
• Swap the token generator or storage model by binding your own implementation if the package exposes contracts (check CesarGB\MagicLink\Contracts).
• Use the MagicLink model directly for advanced queries (e.g. listing active links for a user).

Gotchas and Tips

• Middleware is mandatory – since v2.29.0, running magic links without MagiclinkMiddleware is deprecated. Always attach magiclink to the route that consumes the link.
• APP_URL matters – signed URLs include the host. Ensure APP_URL is correct in every environment, otherwise links will point to the wrong domain.
• One-time use by default – links are typically single-use. If you need multiple uses, set max_uses explicitly, but remember to prune expired tokens.
• Token storage and pruning – tokens are stored in the database. Schedule php artisan magiclink:prune (or equivalent) to avoid table bloat, or write a model cleanup job.
• Expiration is in minutes – the config expires_in is minutes, not seconds. Double-check values when testing.
• Redirects after failure – configure on_failure_redirect to send users to a friendly error page instead of a 403.
• Debugging failed links – check the magic_links table for the token, confirm the link has not expired or been used, and verify the middleware is applied. Logs from the middleware usually indicate why validation failed.
• Custom user models – the trait requires the model to be authenticatable. If you use a non-standard guard, set the guard option so the middleware logs into the right guard.
• Extension points – publish the config to tweak behaviour; use events to hook into creation/usage; override the MagicLink model or action classes only if you need deep customisation.