ozioma / otp
Framework-independent one-time password generation and verification for PHP, with optional Laravel integration.
Requires
- php: ^8.2
- ext-hash: *
Requires (Dev)
- orchestra/testbench: ^9.0 || ^10.0 || ^11.0
- phpunit/phpunit: ^10.5 || ^11.0 || ^12.0
Suggests
- ext-pdo: Required only when using the supplied PDO storage adapters.
- ext-pdo_mysql: Required when using the PDO adapter with MySQL.
- ext-pdo_pgsql: Required when using the PDO adapter with PostgreSQL.
- ext-pdo_sqlite: Required when using the PDO adapter with SQLite.
- laravel/framework: Required only when using the optional Laravel integration (Laravel 11, 12 or 13).
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 18:49:14 UTC
README
A reusable, framework-independent one-time password (OTP) engine for PHP applications, with an optional Laravel integration.
- Composer:
ozioma/otp - PHP namespace:
Ozioma\Otp - PHP: 8.2 or newer
- Laravel integration: designed for Laravel 11, 12 and 13
- License: MIT
The core handles token generation, secure hashing, expiry, purpose isolation, attempt tracking and rate limiting. It does not send email or SMS. Your application controls delivery and decides what a successfully verified OTP authorizes.
Release status: Initial release candidate. The framework-independent core was exercised with an in-memory test harness and PHP syntax checks. PDO integration tests require an installed PDO driver; Laravel integration tests require Composer dependencies and a Laravel/Testbench environment. These environments were not available during this build, so run the full test matrix against your target database and Laravel version before production use.
Features
- Numeric and alphanumeric OTPs generated using
random_int(). - Global defaults, purpose-specific settings and per-operation overrides.
- Purpose and identifier binding: a login code cannot be used for password reset or another identifier.
- Expiration and per-OTP failed-attempt limits.
- Resend cooldown and generation quota.
- Separate verification request rate limiting across OTP generations.
- HMAC-SHA256 token and identifier hashing; plaintext OTPs are never persisted.
- One active OTP per identifier and purpose.
- Explicit non-consuming
verify()and one-timeverifyAndConsume()operations. - Storage, clock, rate-limit and lock contracts for alternate adapters.
- PDO adapters for MySQL, PostgreSQL and SQLite.
- Filesystem lock adapter for single-host plain PHP deployments.
- Optional Laravel service provider, facade, validation rule, migration and Artisan cleanup command.
Installation
composer require ozioma/otp
Laravel's package discovery automatically registers the optional service provider when Laravel is present. Plain PHP applications use the core classes directly.
Until the package is published to Packagist, install it from a local path repository or VCS repository. See Installation.
Laravel
Setup
Publish the configuration and migration:
php artisan vendor:publish --tag=otp-config php artisan vendor:publish --tag=otp-migrations php artisan migrate
Generate two independent secrets:
php -r "echo bin2hex(random_bytes(32)), PHP_EOL;"
Add separate values to .env:
OTP_HASH_KEY=first_64_character_hex_secret OTP_IDENTIFIER_HASH_KEY=second_64_character_hex_secret
Do not commit these secrets. Keep them the same across all application servers. Rotating either key makes existing OTP records unverifiable; normally they should be allowed to expire before a planned key rotation.
The Laravel adapter uses the application's database connection and cache store. Use a shared cache backend that supports atomic locks (such as Redis or a correctly configured database cache) across all application instances. Set the lock lease (locks.lease_seconds) longer than the expected maximum duration of a generation operation. Set OTP_CACHE_STORE to choose a named store and OTP_DB_CONNECTION to choose a database connection.
Generate an OTP
use Ozioma\Otp\Laravel\Facades\Otp; $otp = Otp::for('person@example.com', 'email_verification') ->validFor(10) // minutes ->length(6) ->numeric() ->maxAttempts(5) ->resendAfter(60) // seconds ->maxGenerations(5, 60) // count, window in minutes ->generate(); // Deliver $otp->token using your application's email/SMS notification.
Alphanumeric tokens:
$otp = Otp::for('person@example.com', 'invite') ->length(8) ->alphanumeric('ABCDEFGHJKLMNPQRSTUVWXYZ23456789') ->generate();
Verify an OTP
$isValid = Otp::for('person@example.com', 'email_verification') ->verifyAndConsume($submittedToken);
verifyAndConsume() removes a valid OTP. verify() checks a valid OTP without consuming it. Both operations count against the configured verification rate limit; incorrect codes also increment the per-OTP attempt counter.
Laravel validation rule
use Ozioma\Otp\Laravel\Rules\OtpRule; $request->validate([ 'otp' => [ 'required', 'string', new OtpRule( identifier: $request->user()->email, purpose: 'email_verification', message: 'The code is invalid or has expired.', ), ], ]);
The rule consumes a valid OTP by default. Use consumeOnSuccess: false if validation should only check the code; after all other business checks pass, explicitly call verifyAndConsume(). Validation rules that consume tokens have a side effect, so place the OTP rule after other checks that may fail, or use non-consuming validation followed by explicit consumption.
Configuration
The Laravel integration publishes a conventional Laravel configuration file to config/otp.php. Like other Laravel configuration files, it is a PHP file that returns an array; it is not a PHP class. It uses Laravel's env() helper for environment-backed values and is the only configuration file published by the Laravel service provider.
Plain PHP applications should use the separate config/otp-plain.php file, which reads environment variables with getenv() and does not depend on Laravel helpers.
Both files support global defaults, purpose-specific overrides, and per-operation fluent overrides. Precedence is:
- Global defaults.
- Purpose-specific settings.
- Current operation's fluent settings.
Example purpose configuration:
'purposes' => [ 'transaction_authorization' => [ 'validity' => 3, 'length' => 8, 'type' => 'numeric', 'max_attempts' => 3, ], ],
Cleanup schedule
The package registers otp:prune-expired:
php artisan otp:prune-expired --chunk=1000
Schedule it in routes/console.php:
use Illuminate\Support\Facades\Schedule; Schedule::command('otp:prune-expired --chunk=1000') ->hourly() ->withoutOverlapping() ->onOneServer();
onOneServer() requires a shared cache store that supports locks. Expiration is checked during verification even if the cleanup command has not run.
Plain PHP
1. Create the database tables
Run the schema matching your PDO driver:
database/schema/mysql.sqldatabase/schema/postgresql.sqldatabase/schema/sqlite.sql
The schema creates otps and otp_rate_limits. The PDO adapters require ext-pdo and the matching PDO driver. Use InnoDB for MySQL.
2. Instantiate the core
<?php declare(strict_types=1); require __DIR__ . '/vendor/autoload.php'; use Ozioma\Otp\Adapters\Filesystem\FileLockManager; use Ozioma\Otp\Adapters\PDO\PdoOtpRepository; use Ozioma\Otp\Adapters\PDO\PdoRateLimiter; use Ozioma\Otp\Core\OtpGenerator; use Ozioma\Otp\Core\OtpHasher; use Ozioma\Otp\Core\OtpManager; use Ozioma\Otp\Core\OtpVerifier; use Ozioma\Otp\Core\SystemClock; $pdo = new PDO( 'mysql:host=127.0.0.1;dbname=app;charset=utf8mb4', 'db_user', 'db_password', [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION], ); $config = require __DIR__ . '/vendor/ozioma/otp/config/otp-plain.php'; $config['hash_keys']['token'] = getenv('OTP_HASH_KEY'); $config['hash_keys']['identifier'] = getenv('OTP_IDENTIFIER_HASH_KEY'); $clock = new SystemClock(); $hasher = new OtpHasher( (string) $config['hash_keys']['token'], (string) $config['hash_keys']['identifier'], ); $repository = new PdoOtpRepository($pdo, $config['table']); $rateLimiter = new PdoRateLimiter($pdo, $config['rate_limit_table']); $generator = new OtpGenerator($clock); $verifier = new OtpVerifier($repository, $hasher, $rateLimiter, $clock, $config); $locks = new FileLockManager(__DIR__ . '/var/otp-locks'); $otp = new OtpManager( $repository, $generator, $hasher, $verifier, $rateLimiter, $locks, $clock, $config, ); $generated = $otp->for('person@example.com', 'login')->generate(); // Deliver $generated->token using your mail or SMS implementation. if ($otp->for('person@example.com', 'login')->verifyAndConsume($submittedToken)) { // Continue the login flow. }
Keep the filesystem lock directory outside the public web root and writable only by the application user. FileLockManager coordinates processes on one host only. For multiple hosts, implement LockManagerInterface using a distributed lock service (for example Redis) and inject that implementation.
3. Cleanup from cron
Run this periodically from cron or your application's scheduler:
$now = $clock->now(); $deletedOtpRows = $repository->pruneExpired($now, 1000); $deletedRateLimitRows = $rateLimiter->pruneExpired($now, 1000);
API reference
Generate
$generated = $manager->for($identifier, 'login') ->validFor(10) ->length(6) ->numeric() ->maxAttempts(5) ->resendAfter(60) ->maxGenerations(5, 60) ->generate();
maxGenerations($count, $windowMinutes) sets the number of generations allowed in a fixed time window. A value of 0 disables that quota. resendAfter(0) disables the cooldown.
Generated object properties:
$generated->identifier; $generated->purpose; $generated->token; $generated->generatedAt; // DateTimeImmutable $generated->expiresAt; // DateTimeImmutable $generated->validityMinutes; $generated->expiresInSeconds;
The token is a secret. Do not log it, serialize it into an API response, or expose the generated object to an untrusted client. JSON serialization and debug output omit/redact the identifier and token, and PHP serialization is disabled. Direct access to $generated->identifier and $generated->token is intentionally available to trusted delivery code.
Verify
$manager->for($identifier, 'login')->verify($token); // does not consume success $manager->for($identifier, 'login')->verifyAndConsume($token); // consumes success
Both count each verification request against the global identifier + purpose verification limit. Incorrect tokens increment the OTP record's attempt counter. When the maximum per-OTP attempts is reached, a new OTP must be generated (subject to generation limits).
Configuration options
| Setting | Default | Meaning |
|---|---|---|
validity |
10 | Lifetime in minutes (1–10080) |
length |
6 | Token length (4–128) |
type |
numeric |
numeric or alphanumeric |
alphabet |
Confusable-safe alphabet | Allowed alphanumeric characters |
max_attempts |
5 | Incorrect attempts per generated OTP |
resend_cooldown |
60 | Minimum seconds between generations; 0 disables |
max_generations |
5 | Generations per window; 0 disables |
generation_window |
60 | Generation quota window in minutes |
verification_rate_limit.enabled |
true | Enables request limit across generations |
verification_rate_limit.max_attempts |
20 | Verification requests per identifier + purpose window |
verification_rate_limit.decay_seconds |
3600 | Verification limit window in seconds |
locks.generation_lock_wait_seconds |
5 | Maximum time to wait to acquire a generation lock |
locks.lease_seconds |
60 | Laravel cache-lock lease duration; must exceed expected operation duration |
There is intentionally no useSameToken option. The package stores only keyed hashes and cannot recover an old plaintext code. Resending generates a new code and replaces the previous record.
Database and concurrency notes
- PDO adapters support MySQL, PostgreSQL and SQLite. The matching PDO driver must be installed.
- Use InnoDB for MySQL. The PDO adapters use database transactions and row locks for verification.
PdoRateLimiterstores atomic rate-limit buckets inotp_rate_limits. Pass the same PDO connection to both PDO adapters.FileLockManageris single-host. A multi-host plain PHP deployment must inject a distributed lock manager. Its wait setting limits lock acquisition time;flockholds the lock until the callback returns.- Laravel uses the application's database connection and cache store. Ensure the cache store supports atomic locks and is shared across instances. Set
locks.lease_secondslonger than the expected maximum generation callback duration; a cache lease can expire while a callback is still running if configured too low. - Generation rate-limit allowance is reserved before the OTP record is stored. If persistence subsequently fails, the allowance remains consumed. This conservative behaviour avoids reopening a quota after an application/database failure.
- A successful
verifyAndConsume()is atomic with the OTP record transaction. A successful non-consumingverify()leaves the record active but still consumes a verification request from the rate-limit window. - Expiration is enforced during verification; scheduled cleanup is storage maintenance, not the security boundary.
Security
Read docs/SECURITY.md before using this package for authentication or transaction authorization. The consuming application must still implement endpoint/IP rate limiting, secure delivery, CSRF protection, account-state checks and authorization.
Testing
composer install
composer test
PDO integration tests use SQLite and are skipped when pdo_sqlite is unavailable. Laravel adapter tests should be run in each Laravel version and database/cache combination you support. A local syntax check can be run with:
find src config database tests -name '*.php' -print0 | xargs -0 -n1 php -l
License
MIT. See LICENSE.