README

A simple and flexible Laravel package that allows you to generate, manage, and validate temporary tokens, One-Time Passwords (OTPs), or PINs for tasks like authentication, email verification, password resets, and more.

Features

• Generate numeric tokens of any length.
• Set expiration dates for tokens.
• Limit the number of times a token can be used.
• Attach arbitrary data (metadata) to any token.
• Associate tokens with any Eloquent model (e.g., User).
• Includes an Artisan command to automatically prune expired tokens.
• Fully configurable with no external dependencies.

Installation

You can install the package via Composer:

composer require mydaniel/laravel-temporary-tokens

Next, you should publish the configuration and migration files using the vendor:publish command:

php artisan vendor:publish --provider="MyDaniel\TemporaryTokens\TemporaryTokensServiceProvider"

Finally, run the migration to create the temporary_tokens table:

php artisan migrate

Usage

1. Preparing Your Model

First, add the HasTemporaryTokens trait to the model you wish to generate tokens for (e.g., your User model).

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use MyDaniel\TemporaryTokens\Traits\HasTemporaryTokens;

class User extends Authenticatable
{
    use HasTemporaryTokens;

    // ...
}

2. Creating a Token

You can easily create new tokens using the fluent TokenBuilder.

Create a simple 6-digit token for a user:

$user = User::find(1);

// The `temporaryTokenBuilder` method comes from the HasTemporaryTokens trait
$temporaryToken = $user->temporaryTokenBuilder()->create();

echo $temporaryToken->token; // e.g., "123456"

Create a token with custom settings:

$user = User::find(1);

$temporaryToken = $user->temporaryTokenBuilder()
    ->setType('email-verification')       // Set a token type
    ->setTokenLength(5)                   // Generate a 5-digit token
    ->setUsageLimit(1)                    // Allow the token to be used only once
    ->setExpireDate(now()->addMinutes(15)) // Set a 15-minute expiration
    ->setMetadata(['source' => 'registration']) // Attach custom data
    ->create();

3. Finding and Validating a Token

To find and check the validity of a token, you can use the methods on the TemporaryToken model.

use MyDaniel\TemporaryTokens\Models\TemporaryToken;

$userToken = '123456';
$tokenType = 'email-verification';

// Find a token that is not expired and has not exceeded its usage limit
$token = TemporaryToken::findValid($userToken, $tokenType);

if ($token) {
    // The token is valid
    echo "Token is valid!";

    // You can also check if the token belongs to the correct user
    if ($token->tokenable_id === $user->id) {
        // ...
    }
}

The isValid() method is also available on a TemporaryToken instance to perform the same check:

if ($token && $token->isValid()) {
    // ...
}

4. Using a Token

After a token has been successfully used, you can increment its usage counter.

// Mark the token as "used"
$token->use();

// If the token reaches its usage limit, `hasExceededMaxUsage()` will return true
if ($token->hasExceededMaxUsage()) {
    echo "This token cannot be used anymore.";
}

Pruning Expired Tokens

You can remove expired tokens from your database by running the provided Artisan command.

php artisan temporary-tokens:prune-expired

By default, this command will prune tokens that expired more than 24 hours ago. To customize this, you can either use the --hours option or change the prune_expired_after_hours value in the config/temporary-tokens.php file.

# Prune tokens that expired more than 48 hours ago
php artisan temporary-tokens:prune-expired --hours=48

It is recommended to schedule this command to run daily in your app/Console/Kernel.php file.

// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command('temporary-tokens:prune-expired')->daily();
}

Changelog

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

Contributing

Contributions are welcome! Please feel free to fork the repository and submit a pull request.

Security Vulnerabilities

If you discover a security vulnerability within this package, please send an e-mail to Daniel Yousefi Far at daniyousefifar@gmail.com. All security vulnerabilities will be promptly addressed.

License

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