README

Laravel Token Builder

此包可以生成 随机令牌，这些令牌 可以过期。

生成的令牌可用于创建 一次性链接，或用于 短信验证码认证 等。

我们有 2 种方法可以使生成的令牌 过期

• 时间限制：例如，令牌可以在 2022/05/12 之后过期
• 使用限制：例如，令牌可以在使用超过 3 次之后过期。

赞助我 如果您喜欢这个包 😎

内容列表

• 可用的驱动器
• 安装
• 配置
• 如何使用
  • 生成令牌
  • 添加过期日期
  • 添加使用限制
  • 验证
  • 添加关系
  • 附加自定义数据
  • 检索令牌
  • TokenBuilder 参考
    • setUniqueId
    • getUniqueId
    • setData
    • getData
    • setExpireDate
    • getExpireDate
    • setUsageLimit
    • getUsageLimit
    • setType
    • getType
    • setRelatedItem
    • getRelatedItem
    • build
    • findToken
    • findValidToken
  • Token (Eloquent) 参考
    • use
    • hasUsed
    • hasMaxUsageLimit
    • hasExpired
    • markAsExpired
    • isValid
    • tokenable
• 变更日志
• 贡献
• 安全
• 鸣谢
• 许可证

安装

通过 Composer

$ composer require shetabit/token-builder

配置

如果您使用 Laravel 5.5 或更高版本，则无需添加提供者和别名。

在您的 config/app.php 文件中添加以下两行。

# In your providers array.
'providers' => [
    ...
    Shetabit\TokenBuilder\Provider\TokenBuilderServiceProvider::class,
],

# In your aliases array.
'aliases' => [
    ...
    'TokenBuilder' => Shetabit\TokenBuilder\Facade\TokenBuilder::class,
],

然后，运行以下命令以 发布迁移 和 创建表

php artisan vendor:publish

php artisan migrate

如何使用

您可以使用 TokenBuilder 外观或 Builder 类来构建令牌。

生成令牌

在您的代码中，使用以下 外观

use Shetabit\TokenBuilder\Facade\TokenBuilder;

// ...

$tokenObject = $token = TokenBuilder::build();

您也可以使用 Builder

use Shetabit\TokenBuilder\Builder;

// ...

$builder = new Builder;

$tokenObject = $builder->build();

每个 令牌对象 都有一个 唯一的值，可以用来识别它，我们称之为 token。您可以通过 token 访问令牌对象的唯一令牌，如下所示

use Shetabit\TokenBuilder\Facade\TokenBuilder;

// ...

// generate and store token in database
$tokenObject = $token = TokenBuilder::build();

// show token unique value
echo $tokenObject->token;

您可以通过电子邮件或短信或将其用于 URL 来检索令牌并将其发送给用户。它可以用于 短信验证 或 一次性登录令牌 等。

添加过期日期

您可以为令牌添加自动过期日期。这种类型的令牌将在指定日期之后过期。

    use Shetabit\TokenBuilder\Facade\TokenBuilder;

    // ...

    // will be expired after 5 minutes
    $date = Carbon::now()->addMinutes(5);
    $tokenObject = TokenBuilder::setExpireDate($date)->build();

    echo $tokenObject->token; // show unique token
    echo $tokenObject->expired_at; // show expiration datetime

    if ($tokenObject->hasExpired()) {
        echo 'token has expired';
    }

添加使用限制

您可以在令牌中添加使用限制。当使用次数超过限制时，令牌将无效。

    use Shetabit\TokenBuilder\Facade\TokenBuilder;

    // ...

    // will be expired after 1 usage.
    $tokenObject = TokenBuilder::setUsageLimit(1)->build();

    // use token --> increment the usage counter
    $tokenObject->use();

    echo $tokenObject->token; // show unique token
    echo $tokenObject->usage_count; // show total usages count
    echo $tokenObject->max_usage_limit; // show max usage limit

    // determine if user has used
    if ($tokenObject->hasUsed()) {
        echo 'token has used';
    }

    // determin if token has exceed max usage
    if ($tokenObject->hasExceedMaxUsage()) {
        echo 'token used has exceeded the specified limit';
    }

验证

您可以使用 isValid 方法来验证令牌。如果令牌尚未超过指定限制且尚未过期，则令牌是有效的。

use Shetabit\TokenBuilder\Facade\TokenBuilder;

// ...

$date = Carbon::now()->addMinutes(5); // will be expired after 5 minutes
$usageLimit = 1; // max usages
$token = TokenBuilder::setExpireDate($date)->setUsageLimit($usageLimit)->build();

if ($token->isValid()) {
    echo 'token is valid';

    $token->use(); // use token (increament usage counter)
} else {
    echo 'token is not valid any more!';
}

您可以通过运行 use 方法来使用令牌。您可以通过运行 markAsExpired 方法来使令牌过期。 _{（此方法将更新过期日期为当前日期）}。

添加关系

您可以将关系添加到令牌中。这可以以两种不同的方式完成

use Shetabit\TokenBuilder\Facade\TokenBuilder;
use App\User;

$user = User::first();

/**
 * first example: using TokenBuilder
 **/

$tokenObject = TokenBuilder::setRelatedItem($user)->build();

/**
 * second example: using a main model
 **/

$tokenObject = $user->temporaryTokenBuilder()->build();

// you can access to token's relation using the tokenable
dd($tokenObject->tokenable);

if ($tokenObject->tokenable) {
    echo $tokenObject->tokenable->email;
}

附加自定义数据

您可以将自定义数据附加到您的令牌中。此数据将以 json 格式存储。

use Shetabit\TokenBuilder\Facade\TokenBuilder;

/**
 * first example: using TokenBuilder
 **/

$data = [
    'mobile' => '9373620353',
    'name' => 'John Doe',
];

$tokenObject = TokenBuilder::setData($data)->build();

echo $tokenObject->data['mobile'];

检索令牌

您可以使用令牌的唯一字符串检索 tokenObject

$token = 22325651; // your unique token

// retrieve token object
$tokenObject = TokenBuilder::setUniqueId($token)->findToken();

// retrieve token object if it is valid
$tokenObject = TokenBuilder::setUniqueId($token)->findValidToken();

// retrieve token object using its relation
$tokenObject = $user->temporaryTokenBuilder()->setUniqueId($token)->findToken();

// retrieve token object if it is valid using its relation
$tokenObject = $user->temporaryTokenBuilder()->setUniqueId($token)->findValidToken();

TokenBuilder 参考

这是TokenBuilder方法参考。当您运行build方法时，TokenBuilder会创建一个tokenObject（eloquent Token模型的实例），并使用findToken和findValidToken在数据中搜索。

• setUniqueId

• 您可以使用自定义算法构建令牌并将其用作唯一ID。

    $token = 'jgaZ1z9';
    $tokenObject = TokenBuilder::setUniqueId($token)->build();
    echo $tokenObject->token; // jgaZ1z9

• getUniqueId

• 返回您的自定义唯一ID（如果不存在，则返回null）。

• setData

• 您可以将一些数据附加到令牌中并在以后检索它们。

• getData

  返回附加的数据。

• setExpireDate

  设置过期日期。

• getExpireDate

  检索过期日期。

• setUsageLimit

  设置使用限制。

• getUsageLimit

  检索使用限制。

• setType

  设置令牌类型。您可以为您的令牌设置类型，这就像为您的令牌设置作用域。

• getType

  检索令牌类型。

• setRelatedItem

  向令牌添加一个关联。

• getRelatedItem

  检索当前关联。

• build

  生成一个令牌。

• findToken

  查找令牌（有效或无效不重要）如果不存在则返回null。

• findValidToken

  如果令牌有效则查找令牌，如果不存在则返回null。

令牌参考

• use

  将1加到使用计数器上。（使用计数器 = 使用计数器 + 1）

• hasUsed

  确定当前令牌是否已被使用，并返回布尔结果。

• hasMaxUsageLimit

  确定当前令牌的最大使用量是否有限制，并返回布尔结果。

• hasExpired

  确定当前令牌是否已过期。

• markAsExpired

  将当前令牌标记为已过期。

  注意：此方法将expired_at字段更新为当前时间（现在）。

• isValid

  确定当前令牌是否有效（不得过期且不得超过最大使用限制）。

• tokenable

  如果有任何关联，则返回令牌关联，如果没有关联则返回null。

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南和行为准则。

安全

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

鸣谢

• 马希迪·卡恩扎迪
• 所有贡献者

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。