Skip to content

Commit

Permalink
update php docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@salehhashemi1992
salehhashemi1992 committed Sep 20, 2023
1 parent 9b82b4b commit 49d497f
Showing 1 changed file with 47 additions and 37 deletions.
84 changes: 47 additions & 37 deletions src/OtpManager.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@

namespace Salehhashemi\OtpManager;

use App\Events\OtpProcessed;
use Illuminate\Support\Carbon;
use Illuminate\Support\Str;
use Illuminate\Validation\ValidationException;
use Salehhashemi\ConfigurableCache\ConfigurableCache;
use Salehhashemi\OtpManager\Dto\OtpDto;
use Salehhashemi\OtpManager\Dto\SentOtpDto;
use Salehhashemi\OtpManager\Events\OtpPrepared;

/* A class that is responsible for sending and verifying one time passwords. */
class OtpManager
Expand All @@ -19,9 +19,6 @@ class OtpManager

private string $type;

/**
* @var int
*/
private int $waitingTime;

public function __construct()
Expand All @@ -32,11 +29,13 @@ public function __construct()
/**
* Send a new OTP.
*
* @param string $mobile Mobile number
* @param string $type
* @return \Salehhashemi\OtpManager\Dto\SentOtpDto
* Generates a new OTP code, triggers an event, and returns the sent OTP details.
*
* @throws \Exception
* @param string $mobile The mobile number to which the OTP should be sent.
* @param string $type The type or category of OTP being sent (e.g., 'login', 'reset_password').
* @return \Salehhashemi\OtpManager\Dto\SentOtpDto An object containing details of the sent OTP.
*
* @throws \Exception If the OTP generation fails or any other exception occurs.
*/
public function send(string $mobile, string $type): SentOtpDto
{
Expand All @@ -45,19 +44,23 @@ public function send(string $mobile, string $type): SentOtpDto

$otp = new SentOtpDto($this->getNewCode($mobile), $this->waitingTime, $this->trackingCode);

event(new OtpProcessed(mobile: $mobile, code: (string) $otp->code));
event(new OtpPrepared(mobile: $mobile, code: (string) $otp->code));

return $otp;
}

/**
* Resend OTP based on waiting time.
*
* @param string $mobile The mobile number to send the OTP to.
* @param string $type
* @return \Salehhashemi\OtpManager\Dto\SentOtpDto Sent Otp Dto object
* Checks if the waiting time has passed since the last OTP was sent.
* If so, resends the OTP to the given mobile number; otherwise, throws a ValidationException.
*
* @param string $mobile The mobile number to which the OTP should be resent.
* @param string $type The type or category of OTP being sent (e.g., 'login', 'reset_password').
* @return \Salehhashemi\OtpManager\Dto\SentOtpDto An object containing details of the sent OTP.
*
* @throws \Exception
* @throws \Illuminate\Validation\ValidationException If the OTP cannot be resent due to throttle restrictions.
* @throws \Exception If any other exception occurs.
*/
public function sendAndRetryCheck(string $mobile, string $type): SentOtpDto
{
Expand All @@ -83,13 +86,16 @@ public function sendAndRetryCheck(string $mobile, string $type): SentOtpDto
/**
* Verify the OTP code.
*
* @param string $mobile Mobile number
* @param string $type
* @param int $otp Otp
* @param string|null $trackingCode
* @return bool
* Compares the provided OTP code and tracking code with the stored ones
* for the given mobile number and OTP type. Returns true if they match.
*
* @param string $mobile The mobile number associated with the OTP.
* @param string $type The type or category of OTP (e.g., 'login', 'reset_password').
* @param int $otp The OTP code to verify.
* @param string $trackingCode The tracking code associated with the OTP.
* @return bool True if the provided OTP and tracking code match the stored ones, false otherwise.
*/
public function verify(string $mobile, string $type, int $otp, ?string $trackingCode): bool
public function verify(string $mobile, string $type, int $otp, string $trackingCode): bool
{
$this->type = $type;
$this->trackingCode = $trackingCode;
Expand All @@ -102,9 +108,12 @@ public function verify(string $mobile, string $type, int $otp, ?string $tracking
/**
* Fetch the OTP code for verification.
*
* @param string $mobile Mobile number
* @param string $type
* @return OtpDto|null
* Retrieves the OTP code associated with the given mobile number and OTP type from the cache.
* Returns null if the mobile number is empty or if no OTP code is found.
*
* @param string $mobile The mobile number associated with the OTP.
* @param string $type The type or category of OTP (e.g., 'login', 'reset_password').
* @return \Salehhashemi\OtpManager\Dto\OtpDto|null An OtpDto object containing the OTP code and tracking code, or null if not found.
*/
public function getVerifyCode(string $mobile, string $type): ?OtpDto
{
Expand All @@ -118,9 +127,7 @@ public function getVerifyCode(string $mobile, string $type): ?OtpDto
}

/**
* @param string $mobile Mobile number
* @param string $type
* @return bool
* Delete the verification code for a mobile number.
*/
public function deleteVerifyCode(string $mobile, string $type): bool
{
Expand All @@ -134,10 +141,9 @@ public function deleteVerifyCode(string $mobile, string $type): bool
}

/**
* It returns the time when the OTP was sent to the user
* Retrieve the time when the OTP was sent to the user.
*
* @param string $mobile The mobile number to send the OTP to.
* @return \Illuminate\Support\Carbon|null A Carbon instance of the time the OTP was sent.
* @return \Illuminate\Support\Carbon|null A Carbon instance representing the time the OTP was sent, or null if not available.
*/
public function getSentAt(string $mobile, string $type): ?Carbon
{
Expand All @@ -156,10 +162,9 @@ public function getSentAt(string $mobile, string $type): ?Carbon
}

/**
* > It checks if the cache key exists in the cache store
* Check if a verification code has been sent to a specified mobile number.
*
* @param string $mobile The mobile number to send the OTP to.
* @return bool The function isVerifyCodeHasBeenSent() is returning a boolean value.
* @return bool True if the verification code has been sent, false otherwise.
*/
public function isVerifyCodeHasBeenSent(string $mobile, string $type): bool
{
Expand All @@ -173,10 +178,9 @@ public function isVerifyCodeHasBeenSent(string $mobile, string $type): bool
}

/**
* @param string $mobile Mobile number
* @return int
* Generate a new OTP code within the configured range and store it in the cache.
*
* @throws \Exception
* @throws \Exception If random number generation fails.
*/
protected function getNewCode(string $mobile): int
{
Expand All @@ -194,9 +198,15 @@ protected function getNewCode(string $mobile): int
}

/**
* @param string $mobile Mobile number
* @param string $for Cache key for
* @return string
* Generate a cache key for storing or retrieving OTP-related information.
*
* This function constructs a cache key by combining the mobile number,
* the intended usage ('for'), and the OTP type. The generated key is
* used for caching OTP values and associated information.
*
* @param string $mobile The mobile number to which the OTP will be sent.
* @param string $for Indicates the intended usage of the cache key (e.g., 'value', 'created').
* @return string The generated cache key.
*/
protected function getCacheKey(string $mobile, string $for): string
{
Expand Down

0 comments on commit 49d497f

Please sign in to comment.