README

Laravel 安全通知

此包添加了一个开箱即用、完全可定制的解决方案，用于在用户的账户更新或从新设备访问时发送安全通知。

安装

composer require zaengle/laravel-security-notifications

测试

./vendor/bin/pest

设置

发布配置

php artisan vendor:publish --provider="Zaengle\LaravelSecurityNotifications\Providers\PackageServiceProvider" --tag="config"

使用特性

为了发送安全通知，您需要将 Securable 特性添加到您的用户模型中。此外，您还需要确保您正在使用 Laravel 的 Notifiable 特性。

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Zaengle\LaravelSecurityNotifications\Traits\Securable;

class User extends Authenticatable
{
    use Securable, Notifiable;
}

基本用法

保护字段

Securable 特性会监视您的用户模型中指定安全字段的更新。默认情况下，安全字段是 email、username 和 password。如果这些字段中的任何一个被更新，将会向用户发送安全通知。当 email 字段被更新时，原始电子邮件地址将会收到通知。

您可以通过在您的用户模型中重写 getSecureFields 方法来自定义安全字段。

public function getSecureFields(): array
{
    return [
        'first_name',
        'last_name',
        'email',
    ];
}

保护登录

Securable 特性还提供了一个 logins 关系，可用于跟踪用户登录。此关系跟踪所有已登录用户账户的 IP 地址。为了设置安全登录，您需要发布并运行包中包含的迁移来设置 logins 表。此表名可以在发布的 security-notifications.php 配置文件中进行配置。

php artisan vendor:publish --provider="Zaengle\LaravelSecurityNotifications\Providers\PackageServiceProvider" --tag="migrations"

php artisan migrate

您可以使用 IPAddress 门面在现有的登录控制器中跟踪用户登录。如果给定的 IP 地址已被使用，它将更新登录记录的登录时间。如果 IP 地址是新的，它将创建一个新的登录记录并向用户发送通知。

<?php

namespace App\Http\Controllers;

use Zaengle\LaravelSecurityNotifications\Facades\IPAddress;

class LoginController extends Controller
{
    public function login(Request $request)
    {
        // Your existing login logic
        
        IPAddress::process([
            'ipAddress' => $request->ip(),
            'userId' => auth()->id(),
            'userType' => auth()->user()->getMorphClass(),
        ]);
        
        // return
    }
}

禁用通知

如果您想禁用发送通知，可以设置以下配置值

'send_notifications' => false

自定义通知模板

自定义电子邮件模板

该包提供开箱即用的电子邮件通知模板。但是，如果您想自定义这些模板以匹配您的系统，您可以发布视图并覆盖它们。

php artisan vendor:publish --provider="Zaengle\LaravelSecurityNotifications\Providers\PackageServiceProvider" --tag="views"

它们将在 resources/views/vendor/security-notifications 下可用。

有两个视图可以自定义。每个都可以访问特定数据

security-alert.blade.php
- 可以访问包含已更新字段的 $fields 数组。它还可以访问 $updated_at 变量，这是一个表示字段更新时间的 Carbon 实例。
login-from-new-ip.blade.php
- 可以访问一个表示 Zaengle\LaravelSecurityNotifications\Models\Login 模型实例的 $login 变量。

自定义通知类

如果您想进一步自定义通知，可以在 security-notifications.php 配置文件中配置通知类。

'notifications' => [
    'secure_login' => \Zaengle\LaravelSecurityNotifications\Notifications\LoginFromNewIP::class,
    'secure_fields' => \Zaengle\LaravelSecurityNotifications\Notifications\SecureFieldsUpdated::class,
],

自定义电子邮件地址

默认情况下，此包假设用户模型有一个 email 属性。如果您想自定义发送通知的电子邮件地址，可以在使用 Securable 特性的模型上重写 sendSecurityEmailsTo 方法。

public function sendSecurityEmailsTo(): string
{
    return $this->getOriginal('alternate_email') ?? $this->alternate_email;
}

自定义 IP 地址驱动程序

如果您希望对IP地址和登录处理有完全的控制权，可以通过实现如下示例中的 Zaengle\LaravelSecurityNotifications\Services\DigestIPAddress 接口来创建自定义驱动。

<?php

use Zaengle\LaravelSecurityNotifications\Services\DigestIPAddress;

readonly class CustomIPAddressDriver implements DigestIPAddress
{
    public function __construct(
        private readonly string $ipAddress,
        private readonly string $customField,
    )
    {
    }

    public function handle(): void
    {
        // Custom logic to handle IP address
    }
}

请确保更新 ip_address_driver 配置值，使其指向您的自定义驱动。

'ip_address_driver' => \Path\To\CustomIPAddressDriver::class,

这将告诉 IPAddress 门面使用您的自定义驱动。只需将一个与您的 __construct 定义匹配的数据数组传递给 IPAddress::process() 即可。

IPAddress::process([
    'ipAddress' => $request->ip(),
    'customField' => 'customValue',
]);

许可证

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

鸣谢

页眉图像

zaengle / laravel-security-notifications

维护者

详细信息