kwidoo / sms-verification
A flexible SMS verification package supporting multiple providers
Requires
- php: ^8.2
- plivo/plivo-php: ^4.66.5
- seven.io/api: 6.0.0
- telnyx/telnyx-php: ^3.0
- twilio/sdk: ^8.3
- vonage/client: ^4.1
Requires (Dev)
- mockery/mockery: ^1.6
- orchestra/testbench: ^10.0
- phpunit/phpunit: ^11.0.1
README
Laravel SMS Verification
A Laravel package for sending and validating SMS-based verification codes through multiple providers (e.g., Twilio, Vonage, or any custom provider**).
Overview
- Round Robin Support: Optionally cycle through multiple providers.
- Pluggable Architecture: Implement your own custom verifier(s).
- Abstracted Interface: A single interface for
create()
(sending code) andvalidate()
(checking code).
Table of Contents
Installation
-
Require via Composer:
composer require kwidoo/sms-verification
-
Publish Config (Optional):
This will publish
sms-verification.php
into your Laravelconfig
directory.php artisan vendor:publish --provider="Kwidoo\SmsVerification\SmsVerificationProvider" --tag="sms-verification-config"
-
Configure Environment Variables:
In your
.env
file, make sure to set the appropriate credentials for your desired providers. For example:# Twilio TWILIO_SID=xxxxxxxxxx TWILIO_AUTH_TOKEN=xxxxxxxxxx TWILIO_VERIFY_SID=xxxxxxxxxx # Vonage VONAGE_API_KEY=xxxxxxxxxx VONAGE_API_SECRET=xxxxxxxxxx VONAGE_BRAND="My Awesome App"
Configuration
The default configuration file sms-verification.php
looks like this:
return [ 'verifiers' => [ 'twilio' => \Kwidoo\SmsVerification\Verifiers\TwilioVerifier::class, 'vonage' => \Kwidoo\SmsVerification\Verifiers\VonageVerifier::class, ], 'default' => 'twilio', 'round_robin' => [ 'verifiers' => ['twilio', 'vonage'], 'current_verifier_cache_key' => 'round_robin_verifiers_', 'verifier_for_number_cache_key' => 'round_robin_verifier_for_', ], 'vonage' => [ 'api_key' => env('VONAGE_API_KEY'), 'api_secret' => env('VONAGE_API_SECRET'), 'brand' => env('VONAGE_BRAND', 'MyApp'), ], 'twilio' => [ 'sid' => env('TWILIO_SID'), 'auth_token' => env('TWILIO_AUTH_TOKEN'), 'verify_sid' => env('TWILIO_VERIFY_SID'), ], ];
default
: Indicates the default SMS provider if one is not explicitly specified.round_robin
: An array of provider keys to use in a rotating fashion whenRoundRobinVerifier
is requested.round_robin_cache_key
: Cache key used to persist the index in the round-robin cycle.twilio
,vonage
: Provider-specific credentials and settings.
Usage
Basic Usage
If you only want to use one provider (e.g., Twilio) for all verifications:
-
Set
'default' => 'twilio'
insms-verification.php
. -
In your code, you can do something like:
use Kwidoo\SmsVerification\VerifierFactory; class SomeController extends Controller { public function sendCode(Request $request, VerifierFactory $factory) { $phoneNumber = $request->input('phone_number'); $verifier = $factory->make(); // uses default (twilio) $verifier->create($phoneNumber); return response()->json(['status' => 'Verification code sent.']); } public function checkCode(Request $request, VerifierFactory $factory) { $phoneNumber = $request->input('phone_number'); $code = $request->input('code'); $verifier = $factory->make(); // uses default (twilio) if ($verifier->validate([$phoneNumber, $code])) { return response()->json(['status' => 'Code is valid!']); } // If invalid, handle appropriately return response()->json(['error' => 'Invalid code'], 422); } }
Round Robin Usage
If you want to rotate between providers (e.g., Twilio → Vonage → Twilio → Vonage…), you can request the round-robin verifier:
-
round_robin
is an array of strings referencing your verifiers:['twilio', 'vonage']
. -
In your code, you might do:
use Kwidoo\SmsVerification\VerifierFactory; class SomeController extends Controller { public function sendCode(Request $request, VerifierFactory $factory) { $phoneNumber = $request->input('phone_number'); $verifier = $factory->make('roundRobin'); $verifier->create($phoneNumber); return response()->json(['status' => 'Verification code sent.']); } public function checkCode(Request $request, VerifierFactory $factory) { $phoneNumber = $request->input('phone_number'); $code = $request->input('code'); $verifier = $factory->make('roundRobin'); if ($verifier->validate([$phoneNumber, $code])) { return response()->json(['status' => 'Code is valid!']); } // If invalid, handle appropriately return response()->json(['error' => 'Invalid code'], 422); } }
The round-robin verifier will:
- On
create()
, pick the next provider in a cycle, send the verification code, and remember which provider was used for that phone number. - On
validate()
, retrieve that same provider to check the code.
Custom Verifiers
You can create your own SMS verifier by:
- Creating a class that implements
VerifierInterface
(or extend the baseVerifier
class). - Register it in the container or simply reference its FQN in
sms-verification.verifiers
.
Example:
namespace App\Verifiers; use Kwidoo\SmsVerification\Verifiers\Verifier; class MyCustomVerifier extends Verifier { public function create(string $phoneNumber): void { // Implementation to send code } public function validate(array $credentials): bool { // Implementation to check code return true; } }
Then, in sms-verification.php
:
'verifiers' => [ 'twilio' => \Kwidoo\SmsVerification\Verifiers\TwilioVerifier::class, 'vonage' => \Kwidoo\SmsVerification\Verifiers\VonageVerifier::class, 'my_custom' => \App\Verifiers\MyCustomVerifier::class, ],
And in code:
$verifier = $factory->make('my_custom');
Console Command
This package includes a console command to generate new custom verifiers from a stub:
php artisan verifier:create-sms-verifier {name?}
If you omit {name}
, the command will prompt you to enter the verifier’s class name. It also asks for the client class (namespace) that the verifier should inject.
The newly generated file will be placed in app/Verifiers/{Name}.php
. You can customize paths or logic within the command class CreateSmsVerifier
.
Example Code
Here’s a quick example to tie it all together:
// routes/api.php use Illuminate\Support\Facades\Route; use Kwidoo\SmsVerification\VerifierFactory; Route::post('/send-code', function(\Illuminate\Http\Request $request, VerifierFactory $factory) { $phoneNumber = $request->input('phone_number'); // If you want round robin, pass 'roundRobin' or whichever config key you want: // $verifier = $factory->make('roundRobin'); $verifier = $factory->make(); // default is 'twilio' $verifier->create($phoneNumber); return response()->json(['message' => 'Code sent']); }); Route::post('/verify-code', function(\Illuminate\Http\Request $request, VerifierFactory $factory) { $phoneNumber = $request->input('phone_number'); $code = $request->input('code'); $verifier = $factory->make(); // or 'roundRobin' $isValid = $verifier->validate([$phoneNumber, $code]); return response()->json(['valid' => $isValid]); });
Credits
- Twilio for their robust Verify service.
- Vonage (formerly Nexmo) for their Verify APIs.
- Sinch for their SMS verification service.
- Telnyx for their Verify API.
- Plivo for their SMS verification service.
- seven.io for their SMS verification service.
- Telesign for their SMS verification service.
- Laravel community for a great framework to extend.
License
This package is open-sourced software licensed under the MIT license.
TODO
- Make more round-robin strategies (e.g., Weighted Round Robin, Random, etc.).
- Implement a “fallback” approach (try one provider; if it fails, try another).
- Add tests.
- Add webhook support to better handle fails
- Add support for other SMS providers:
- Plivo
- Sinch
- seven.io
- Telesign
- ClickSend
- Textmagic
- SlickText
- Infobip
- Routee
- Telnyx