README

通过 MagicLink 类，我们可以创建一个安全的链接，该链接在被访问后会执行某些操作，这将使我们能够提供安全的内容，甚至登录到应用程序。

内容

安装
用例
创建MagicLink
操作
使用访问码保护
有效期
事件
自定义

安装

您可以使用以下命令通过Composer安装此包：

composer require cesargb/laravel-magiclink

准备数据库

您需要发布迁移来创建 magic_links 表

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

之后，您需要运行迁移。

php artisan migrate

用例

通过此示例，您可以为应用程序创建一个自动登录的链接

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

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

创建MagicLink

MagicLink 类有一个 create 方法来生成一个类，通过该类的 url 属性，我们将获得要发送给访问者的链接。

此方法需要执行的操作。

操作

每个MagicLink都与一个操作相关联，这是在访问链接时将执行的操作。

登录操作
下载文件操作
查看操作
HTTP响应操作
HTTP响应
控制器
自定义操作
自定义基本URL

登录操作

通过 LoginAction 操作，您可以使用 MagicLink 生成的链接登录到应用程序。

您的构造函数支持将要登录的用户。您可以选择使用 response 方法或指定其他守卫使用 guard 方法来指定HTTP响应。

示例

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');

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

// Sample 4; Login and remember me
$action = new LoginAction(User::first());
$action->remember();

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

下载文件操作

此操作，DownloadFileAction，允许创建一个下载私有文件的链接。

构造函数需要文件路径。

示例

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;

查看操作

通过 ViewAction 操作，您可以使用与Laravel的 view 方法相同的参数提供访问权限。

示例

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响应操作

通过 ResponseAction 操作，我们可以在不登录的情况下访问私有内容。其构造函数接受作为参数的 HTTP响应，这将作为请求的响应。

示例

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

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

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

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

控制器操作

MagicLink 可以通过 ControllerAction 操作直接调用控制器。

构造函数需要一个参数，即控制器类的名称。第二个参数可以调用任何控制器方法，默认情况下将使用 __invoke 方法。

use MagicLink\Actions\ControllerAction;
use MagicLink\MagicLink;

// Call the method __invoke of the controller
$url = MagicLink::create(new ControllerAction(MyController::class))->url;

// Call the method show of the controller
$url = MagicLink::create(new ControllerAction(MyController::class, 'show'))->url;

自定义操作

您可以为它们创建自己的操作类，为此，您只需扩展 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,
        ]);
    }
}

您现在可以生成带有自定义操作的Magiclink

use MagicLink\MagicLink;

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

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

自定义基本URL

要设置魔法链接的基本URL，您可以使用 baseUrl 方法。此方法确保提供的基URL有尾随斜杠，使其适合URL生成。

$magiclink = MagicLink::create($action);

$magiclink->baseUrl("http://example.com");

$urlShowView = $magiclink->url; // http://example.com/magiclink/...

使用访问码保护

可选地，您可以使用访问码保护资源。您可以使用接受访问码作为参数的 protectWithAccessCode 方法来设置访问码。

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

$magiclink->protectWithAccessCode('secret');

$urlToSend = $magiclink->url;

自定义访问码视图

您可以使用配置文件 magiclink.php 来自定义访问码表单的视图。

'access_code' => [
    'view' => 'magiclink::access-code', // Change with your view
],

这是默认视图。

有效期

默认情况下，创建链接后，链接将有效72小时。我们可以通过create方法中的$lifetime选项来修改链接的生命周期（以分钟为单位）。此参数接受null值，这样链接就不会在指定时间内过期。

$lifetime = 60; // 60 minutes

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

$urlToSend = $magiclink->url;

我们还有另一个选项$numMaxVisits，我们可以用这个选项来定义链接可以被访问的次数，默认为null，表示没有访问次数限制。

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

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

$urlToSend = $magiclink->url;

事件

MagicLink会触发两个事件

MagicLink\Events\MagicLinkWasCreated
MagicLink\Events\MagicLinkWasVisited

自定义

配置

要自定义此包，可以发布配置文件

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

并编辑文件config/magiclink.php

迁移

要自定义此包的迁移文件，您需要发布迁移文件

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

您可以在database/migrations/*中找到已发布的文件

当magiclink无效时的自定义响应

当magicLink默认无效时，HTTP请求返回状态403。您可以使用配置magiclink.invalid_response来自定义此响应。

响应

要返回响应，使用类MagicLink\Responses\Response::class，与response()相同，您可以使用选项发送参数。

示例

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

中断

要返回异常并让框架处理响应，使用类MagicLink\Responses\AbortResponse::class。与abort()相同，您可以使用选项发送参数。

示例

    'invalid_response' => [
        'class'   => MagicLink\Responses\AbortResponse::class,
        'options' => [
            'message' => 'You Shall Not Pass!',
            'status' => 403,
        ],
    ],

重定向

定义类MagicLink\Responses\RedirectResponse::class以返回一个redirect()

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

查看

定义类MagicLink\Responses\ViewResponse::class以返回一个view()

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

测试

使用以下命令运行测试

composer test

贡献

有关详细信息，请参阅CONTRIBUTING

安全

如果您发现任何与安全相关的问题，请通过电子邮件cesargb@gmail.com报告，而不是使用问题跟踪器。

许可

MIT许可证（MIT）。请参阅许可文件获取更多信息。

cesargb / laravel-magiclink

维护者

详细信息