README

A laravel package to create, validate and manage OTPs.

Installation

You can install the package via composer:

composer require youngmayor/laravel-otp

The package uses auto discovery hence if you use Laravel 5.5 or above, installing the package automatically registers it in your application.

However, if you use Laravel 5.4 or below you will need to add the below snipet to your config/app.php to register the Service Provider and alias

'providers' => [
    // ...
    YoungMayor\LaravelOtp\LaravelOtpServiceProvider,
    // ...
],

Next step is to publish the configuration for the package. This can be done using the command below

php artisan vendor:publish --provider="YoungMayor\LaravelOtp\LaravelOtpServiceProvider"

This copies the package configuration into config/laravel-otp.php

Then you run migration to create the OTP tables

php artisan migrate

Usage

Models which intend to manage OTP codes should extend the YoungMayor\LaravelOtp\Traits\OTPActions trait

// ...
use YoungMayor\LaravelOtp\Traits\OTPActions;
// ...

class ExampleModel
{
    // ...
    use OTPActions;
    // ....
}

It is required that the model posses an email field. This field would store the recipient of the generate OTP code. It is assumed that this field is named email. If the field has a different name, then it should be configured using the below code
class ExampleModel
{
  use OTPActions; 

  public $otpEmailKey = 'user_email';
}

OTPs can now be managed using that model.

OTP Creation

// $exampleModel is an instance of ExampleModel
// $payload is additional data that you would like to attach to the OTP token. 
// The payload can be an array, a string or an integer
$exampleModel->generatOTP('action-name', $payload);

This generates an OTP using the configuration defined in config/laravel-otp.php and emails the generate OTP to the email attached to the model

OTP Validation

// $exampleModel is an instance of ExampleModel and has a pending OTP
// $pin is the OTP pin that is to be validated
$otp = $exampleModel->validateOTP($pin, 'action-name');

If the pin is correct an instance of YoungMayor\LaravelOtp\Models\OneTimePin would be returned, else null would be returned

if (!$otp) {
    // handle invalid OTP code
}

Managing OTP

The OTP can now be managed as below

$otp->is_expired; // check if the OTP is expired

$payload = $otp->payload; // retrieve the OTP's Payload

$otp->refreshOTP(); // re-generate a new OTP code and send to the recipient

$otp->delete(); // delete the OTP

Relationships

Every model which utilises the OTPActions trait have the otps relationship and can perform laravel one to many relationshp on it.

Likewise, from the YoungMayor\LaravelOtp\Models\OneTimePin instance. You can retrieve the source model using the source relationship method

$exampleModel = $otp->source;

Exceptions

The package renders two exceptions:

YoungMayor\LaravelOtp\Exceptions\InvalidAction exception: Thrown when an attempt to generateOTP() or validateOTP() is made with an action that is not registered in the config/laravel-otp.php file.
YoungMayor\LaravelOtp\Exceptions\InvalidSource exception: Thrown when the given source does not use the OTPActions trait

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

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

youngmayor / laravel-otp

Maintainers

Details