MagicLink for Laravels App

Through the MagicLink class we can create a secure link that later being visited will perform certain actions, which will allow us offer secure content and even log in to the application.

Contents

• Installation
• Use case
• Create a MagicLink
• Actions
  • Login
  • Download file
  • View
  • Http Reponse
  • Custom Action
• Protect with an access code
• Lifetime
• Events
• Customization

Installation

You can install this package via composer using:

composer require cesargb/laravel-magiclink

You can then create the table by running the migrations:

php artisan migrate

Note: If you have the version 1 installed, read this.

Use case

With this example you can create a link to auto login on your application with the desired user:

use MagicLink\Actions\LoginAction;
use MagicLink\MagicLink;

$urlToAutoLogin =  MagicLink::create(new LoginAction($user))->url

Create a MagicLink

The MagicLink class has the create method to generate a class that through the url property we will obtain the link that we will send to our visitor.

This method requires the action to be performed.

Actions

Each MagicLink is associated with an action, which is what will be performed once the link is visited.

• Login Action
• Download file Action
• View Action
• Http Reponse Action

Login Action

Through the LoginAction action, you can log in to the application using the generated link by MagicLink.

Your constructor supports the user who will login. Optionally we can specify the HTTP response using the method response or specify other guard with method guard.

Examples:

use MagicLink\Actions\LoginAction;
use MagicLink\MagicLink;

// Sample 1; Login and redirect to dash board
$action = new LoginAction(User::first());
$action->response(redirect('/dashboard'));

$urlToDashBoard = MagicLink::create($action)->url;

// Sample 2; Login and view forms to password reset and use guard web
$action = new LoginAction(User::first());
$action->response(view('password.reset', ['email' => 'user@example.tld']));

$urlShowView = MagicLink::create($action)->url;

// Sample 3; Login in other guard and redirect default
$action = new LoginAction(User::first());
$action->guard('customguard')->response(redirect('/api/dashboard'));

$urlShowView = MagicLink::create($action)->url;

Download file Action

This action, DownloadFileAction, permit create a link to download a private file.

The constructor require the file path.

Example:

use MagicLink\Actions\DownloadFileAction;
use MagicLink\MagicLink;

// Url to download the file storage_app('private_document.pdf')
$url = MagicLink::create(new DownloadFileAction('private_document.pdf'))->url;

// Download file with other file_name
$action = new DownloadFileAction('private_document.pdf', 'your_document.pdf');
$url = MagicLink::create($action)->url;

// Download file from other disk
$action = new DownloadFileAction('private_document.pdf')->disk('ftp');
$url = MagicLink::create($action)->url;

View Action

With the action ViewAction, you can provide access to the view. You can use in his constructor the same arguments than method view of Laravel.

Example:

use MagicLink\Actions\ViewAction;
use MagicLink\MagicLink;

// Url to view a internal.blade.php
$url = MagicLink::create(new ViewAction('internal', [
    'data' => 'Your private custom content',
]))->url;

Http Response Action

Through the ResponseAction action we can access private content without need login. Its constructor accepts as argument the HTTP response which will be the response of the request.

Examples:

use MagicLink\Actions\ResponseAction;
use MagicLink\MagicLink;

$action = new ResponseAction(function () {
    Auth::login(User::first());

    return redirect('/change_password');
});

$urlToCustomFunction = MagicLink::create($action)->url;

Custom Action

You can create your own action class, for them you just need to extend with MagicLink\Actions\ActionAbstract

use MagicLink\Actions\ActionAbstract;

class MyCustomAction extends ActionAbstract
{
    public function __construct(public int $variable)
    {
    }

    public function run()
    {
        // Do something

        return response()->json([
            'success' => true,
            'data' => $this->variable,
        ]);
    }
}

You can now generate a Magiclink with the custom action

use MagicLink\MagicLink;

$action = new MyCustomAction('Hello world');

$urlToCustomAction = MagicLink::create($action)->url;

Protect with an access code

Optionally you can protect the resources with an access code. You can set the access code with method protectWithAccessCode which accepts an argument with the access code.

$magiclink = MagicLink::create(new DownloadFileAction('private_document.pdf'));

$magiclink->protectWithAccessCode('secret');

$urlToSend = $magiclink->url;

Lifetime

By default a link will be available for 72 hours after your creation. We can modify the life time in minutes of the link by the $lifetime option available in the create method. This argument accepts the value null so that it does not expire in time.

$lifetime = 60; // 60 minutes

$magiclink = MagicLink::create(new ResponseAction(), $lifetime);

$urlToSend = $magiclink->url;

We also have another option $numMaxVisits, with which we can define the number of times the link can be visited, null by default indicates that there are no visit limits.

$lifetime = null; // not expired in the time
$numMaxVisits = 1; // Only can visit one time

$magiclink = MagicLink::create(new ResponseAction(), $lifetime, $numMaxVisits);

$urlToSend = $magiclink->url;

Events

MagicLink fires two events:

• MagicLink\Events\MagicLinkWasCreated
• MagicLink\Events\MagicLinkWasVisited

Customization

To custom this package you can publish the config file:

php artisan vendor:publish --provider="MagicLink\MagicLinkServiceProvider" --tag="config"

And edit the file config/magiclink.php

Custom response when magiclink is invalid

When the magicLink is invalid by default the http request return a status 403. You can custom this response with config magiclink.invalid_response.

Response

To return a response, use class MagicLink\Responses\Response::class same response(), you can send the arguments with options

Example:

    'invalid_response' => [
        'class'   => MagicLink\Responses\Response::class,
        'options' => [
            'content' => 'forbidden',
            'status' => 403,
        ],
    ],

Redirect

Define class MagicLink\Responses\RedirectResponse::class to return a redirect()

    'invalid_response' => [
        'class'   => MagicLink\Responses\RedirectResponse::class,
        'options' => [
            'to' => '/not_valid_path',
            'status' => 301,
        ],
    ],

View

Define class MagicLink\Responses\ViewResponse::class to return a view()

    'invalid_response' => [
        'class'   => MagicLink\Responses\ViewResponse::class,
        'options' => [
            'view' => 'invalid',
            'data' => [],
        ],
    ],

Testing

Run the tests with:

composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email cesargb@gmail.com instead of using the issue tracker.

License

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