Generic OTP Guide
=================
Generic OTP is useful when you want one-time codes without managing a dedicated OTP database table, while still keeping server-side verification state.
It is a strong fit for delivery channels such as SMS, email, and instant messaging platforms, because your application generates the code and decides how to deliver it.
When to use it
--------------
This mode is application-oriented rather than RFC-specific. That does not limit it to any one transport. It is useful for cases like:
- signup verification
- SMS OTP
- email OTP
- OTP over chat or IM platforms
- password reset codes
- short-lived step-up verification codes
PSR-6 cache requirement
-----------------------
The generic OTP class requires a PSR-6 cache pool implementation:
.. code-block:: php
<?php
use Infocyph\OTP\OTP;
$otp = new OTP(
digitCount: 6,
validUpto: 60,
retry: 3,
hashAlgorithm: 'xxh128',
cacheAdapter: $cachePool,
);
Codes are strings
-----------------
- Generated codes are strings.
- Verification expects a string.
- Leading zeroes are preserved.
Basic flow
----------
.. code-block:: php
<?php
$code = $otp->generate('signup:alice@example.com');
$otp->verify('signup:alice@example.com', $code);
$otp->delete('signup:alice@example.com');
Another example for a password reset flow:
.. code-block:: php
<?php
$signature = 'password-reset:user-42';
$code = $otp->generate($signature);
// deliver $code to the user
if ($otp->verify($signature, $submittedCode)) {
// continue reset flow
}
Example for SMS or IM delivery:
.. code-block:: php
<?php
$signature = 'login-otp:user-42:phone:+15551234567';
$code = $otp->generate($signature);
// send $code by SMS, WhatsApp, Telegram, or another messaging channel
if ($otp->verify($signature, $submittedCode)) {
// mark the login challenge as verified
}
Retry semantics
---------------
The third argument of ``verify()`` controls whether a found record should be removed immediately:
.. code-block:: php
<?php
$otp->verify('signup:alice@example.com', $code, deleteIfFound: false);
When ``deleteIfFound`` is ``false``, the record remains until it is verified, runs out of retries, or expires.
Data model
----------
The generic OTP cache payload keeps:
- a hashed representation of the generated OTP
- retry state
- the expiration moment
Because codes are strings, leading zeroes are preserved correctly.
|
Download
