README

Laravel Magic Login

Easily add passwordless authentication into your application.

Installation

You can install the package via composer:

composer require maize-tech/laravel-magic-login

You can publish the config and migration files and run the migrations with:

php artisan magic-login:install

This is the contents of the published config file:

return [

    /*
    |--------------------------------------------------------------------------
    | Magic Login model
    |--------------------------------------------------------------------------
    |
    | Here you may specify the fully qualified class name of the magic login
    | model.
    | By default, the value is Maize\MagicLogin\Models\MagicLogin::class
    |
    */

    'model' => null,

    /*
    |--------------------------------------------------------------------------
    | Expiration time
    |--------------------------------------------------------------------------
    |
    | Here you may specify the amount of minutes before the magic login link
    | expires.
    | By default, the value is 120 minutes (2 hours).
    |
    */

    'expiration' => null,

    /*
    |--------------------------------------------------------------------------
    | Authentication guard
    |--------------------------------------------------------------------------
    |
    | Here you may specify the guard you want to use to authenticate the user.
    | The guard name must be defined in your application's auth.php config file.
    | By default, the value is 'web'.
    |
    */

    'guard' => null,

    /*
    |--------------------------------------------------------------------------
    | Default redirect url
    |--------------------------------------------------------------------------
    |
    | Here you may specify the redirect url used by default if none is specified
    | when creating the magic link.
    |
    */

    'redirect_url' => null,

    /*
    |--------------------------------------------------------------------------
    | Exception class
    |--------------------------------------------------------------------------
    |
    | Here you may specify the default exception class used for all package
    | related exceptions.
    | Useful if you need to customize the http status code in case an exception
    | is thrown during the magic login process.
    | By default, the value is Illuminate\Routing\Exceptions\InvalidSignatureException::class
    |
    */

    'exception' => null,

    /*
    |--------------------------------------------------------------------------
    | Force single link
    |--------------------------------------------------------------------------
    |
    | Here you can specify whether a user can only have one valid magic link
    | at a time or not.
    | If true, when you generate a new magic link for a specific user all
    | previously generated links will be revoked.
    | By default, the value is true.
    |
    */

    'force_single' => null,

    /*
    |--------------------------------------------------------------------------
    | Logins limit
    |--------------------------------------------------------------------------
    |
    | Here you can specify the amount of logins a user can perform with the
    | same magic link.
    | Can be either -1, which lets the user login indefinitely, or any number
    | greater than or equal to 1.
    | By default, the value is -1.
    |
    */

    'logins_limit' => null,

    /*
    |--------------------------------------------------------------------------
    | Send Notification Action
    |--------------------------------------------------------------------------
    |
    | Here you can specify the fully qualified class name of a custom action
    | used to send the magic login email notification.
    | By default, the value is Maize\MagicLogin\Actions\SendMagicLinkAction::class
    */

    'send_notification_action' => null,

    /*
    |--------------------------------------------------------------------------
    | Notification class
    |--------------------------------------------------------------------------
    |
    | Here you can specify the fully qualified class name of the magic link
    | email notification.
    | By default, the value is Maize\MagicLogin\Notifications\MagicLinkNotification::class
    */

    'notification' => null,

    'route' => [

        /*
        |--------------------------------------------------------------------------
        | Route method
        |--------------------------------------------------------------------------
        |
        | Here you may specify the route's allowed methods.
        | By default, the value is 'GET'.
        |
        */

        'methods' => null,

        /*
        |--------------------------------------------------------------------------
        | Route URI
        |--------------------------------------------------------------------------
        |
        | Here you may specify the route's uri.
        | By default, the value is 'magic-login'.
        |
        */

        'uri' => null,

        /*
        |--------------------------------------------------------------------------
        | Route name
        |--------------------------------------------------------------------------
        |
        | Here you may specify the route's name.
        | By default, the value is 'magic-login'.
        |
        */

        'name' => null,

        /*
        |--------------------------------------------------------------------------
        | Route controller
        |--------------------------------------------------------------------------
        |
        | Here you may specify the fully qualified class name of a custom controller
        | class used to handle the magic login request.
        | By default, the value is Maize\MagicLogin\Http\Controllers\MagicLoginController::class.
        |
        */

        'controller' => null,

        /*
        |--------------------------------------------------------------------------
        | Route middlewares
        |--------------------------------------------------------------------------
        |
        | Here you may specify the list of middlewares used by the magic login route.
        | By default, the value is Maize\MagicLogin\Http\Middleware\ValidateSignature::class.
        |
        */

        'middleware' => null,

    ],

];

Usage

Basic

To use the package, all you have to do is include the magic link route in your routes file. By default, you should include it under routes/web.php:

use Maize\MagicLogin\Facades\MagicLink;

MagicLink::route();

That's it! Once done, you can already generate an invitation link to any model extending the Authenticatable class using the make method:

use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::make(
    authenticatable: $user
);

Email notifications

Send an email notification

Optionally, you may also automatically send an email notification to the given user using the send method:

use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::send(
    authenticatable: $user
);

which is equals to using the make method with the notify parameter set to true:

use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::make(
    authenticatable: $user,
    notify: true
);

Customize the notification class

When needed, you can customize the email notification. All you have to do is create your own notification and override the default MagicLinkNotification class:

use Illuminate\Notifications\Messages\MailMessage;
use Maize\MagicLogin\Notifications\MagicLinkNotification as BaseMagicLinkNotification;

class MagicLinkNotification extends BaseMagicLinkNotification
{
    public function toMail($notifiable): MailMessage
    {
        return (new MailMessage)
            ->line(__('This is my custom magic link notification message'))
            ->action(__('Join now'), $this->uri);
    }
}

Finally, you can update the notification attribute under config/magic-login.php with the new class path.

Force single link

When enabled, users can only have one valid link at a time. This means that when a new link is created, all previously created links are invalidated.

To enable this option, you can set the force_single attribute under config/magic-login.php to true.

Magic link generator options

The package offers many useful parameters for the make method to allow you customizing every single magic link:

• Redirect url
• Expiration time
• Route name
• Authentication guard
• Logins limit
• Custom metadata

Redirect url

You can provide a redirect url used after authenticating the user:

use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::send(
    authenticatable: $user,
    redirectUrl: 'yourapplication.test/your-path'
);

When not provided, the default value defined in redirect_url attribute under config/magic-login.php will be used.

Expiration time

You can define the amount of time before a magic link expires by providing a carbon instance or an integer with the amount of minutes:

use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::send(
    authenticatable: $user,
    expiration: now()->addDays(10), // the link will expire in 10 days
);

$magicLink = MagicLink::send(
    authenticatable: $user,
    expiration: 60, // the link will expire in 1 hour (60 minutes)
);

When not provided, the default value defined in expiration attribute under config/magic-login.php will be used.

Route name

You can define the route name used to generate the magic link:

use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::send(
    authenticatable: $user,
    routeName: 'magic-link',
);

When not provided, the default value defined in route.name attribute under config/magic-login.php will be used.

Authentication guard

You can define the authentication guard used to authenticate the user:

use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::send(
    authenticatable: $user,
    guard: 'api' // the 'api' auth guard will be used
);

When not provided, the default value defined in guard attribute under config/magic-login.php will be used.

Logins limit

You can define the amount of times a single link can be used before expiring. The value can be either -1, which lets the user login indefinitely, or any number greater than or equal to 1:

use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::send(
    authenticatable: $user,
    loginsLimit: 5 // the link can be used 5 times at max
);

$magicLink = MagicLink::send(
    authenticatable: $user,
    loginsLimit: -1 // the link can be used an infinite amount of times
);

When not provided, the default value defined in logins_limit attribute under config/magic-login.php will be used.

Custom metadata

Optionally, you can store custom metadata in case you need to perform custom queries.

use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;
use Maize\MagicLogin\Models\MagicLogin;

$user = User::firstOrFail();

$magicLink = MagicLink::send(
    authenticatable: $user,
    metadata: ['test' => true]
);

MagicLogin::query()
    ->whereJsonContains('metadata->test', true)
    ->count(); // returns 1

MagicLogin::query()
    ->whereJsonContains('metadata->test', false)
    ->count(); // returns 0

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Enrico De Lazzari
• All Contributors

License

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