roomies/phonable

Gather insights and verify phone numbers from multiple third-party providers.

0.5.0 2024-06-26 23:22 UTC

Requires

• php: ^8.3
• guzzlehttp/guzzle: ^7.8
• illuminate/contracts: ^10.0|^11.0
• illuminate/support: ^10.0|^11.0

Requires (Dev)

• laravel/pint: ^1.0
• laravel/vonage-notification-channel: ^3.2
• orchestra/testbench: ^8.21.1
• phpunit/phpunit: ^10.0
• vonage/client-core: ^4.1.0

Suggests

• laravel/vonage-notification-channel: Required to use the Vonage driver (^3.0).

MIT

• Dwight Watson

• laravel
• roomies
• phonable

README

Roomies Phonable provides an abstraction layer to identify and verify phone numbers in your Laravel app. Phone verification can be used to help identify legitmate users of your app and also serve as a way to handle 2-factor authentication. Phonable provides implementations for a number of phone services including Prelude (previously Ding), Twilio, and Vonage.

Installation

You can install the package via Composer:

composer require roomies/phonable

You can publish the config file with:

php artisan vendor:publish --tag="phonable-config"

Read through the config file to understand the supported services and provide the correct configuration for your preferred services.

Identification

Identification is a way to gather more information about a phone number including the country of origin, phone number type and more. This feature is supported by Prelude and Vonage.

// Return an instance of \Roomies\Phonable\Identification\IdentificationResult
$result = Identification::get('[phone]');

Alternatively you can pass an object that implements Roomies\Phonable\Contracts\PhoneIdentifiable - getIdentifiablePhoneNumber() should return the phone number in E.164 format.

use Roomies\Phonable\Facades\Identification;
use Roomies\Phonable\Contracts\PhoneIdentifiable;

class User implements PhoneIdentifiable
{
    /**
     * The identifiable phone number in E.164 format.
     */
    public function getIdentifiablePhoneNumber(): ?string
    {
        return '[phone]';
    }
}

// Return an instance of \Roomies\Phonable\Identification\IdentificationResult
$result = Identification::get($user);

You can swap the driver out on the fly as necessary.

use Roomies\Phonable\Facades\Identification;

Identification::driver('prelude')->get($user);

Verification

Verification is a two-step process in sending a generated code to a phone number that then needs to be entered back into your app to complete the process. This ensures your user has timely access to the phone number provided. This feature is supported by Prelude, Twilio, and Vonage.

// Return an instance of \Roomies\Phonable\Verification\VerificationRequest
$request = Verification::send('[phone]');

// Return an instance of \Roomies\Phonable\Verification\VerificationResult
$result = Verification::verify($request->id, 'code');

Alternatively you can pass an object that implements Roomies\Phonable\Contracts\PhoneVerifiable - getVerifiablePhoneNumber() should return the phone number in E.164 format and getVerifiableSession() should return the previously stored verification request ID.

use Roomies\Phonable\Facades\Verification;
use Roomies\Phonable\Contracts\PhoneIdentifiable;

class User implements PhoneVerifiable
{
    /**
     * The verifiable phone number in E.164 format.
     */
    public function getVerifiablePhoneNumber(): ?string
    {
        return '[phone]';
    }

    /**
     * The current verification session identifier.
     */
    public function getVerifiableSession(): ?string
    {
        return $this->phone_verification_session;
    }
}

// Return an instance of \Roomies\Phonable\Verification\VerificationRequest
$request = Verification::send($user);

$user->update([
    'phone_verification_session' => $request->id,
]);

You will need to store the verification session ID as it will be used to complete the process.

When you receive the code from the user you can then call the verify method with the provided code. Roomies\Phonable\Verification\VerificationResult is a simple enum of the result.

use Roomies\Phonable\Verification\VerificationResult;

// Return an instance of \Roomies\Phonable\Verification\VerificationResult
$result = Verification::verify($user, 1234);

if ($result === VerificationResult::Successful) {
    $user->update([
        'phone_verified_at' => now(),
        'phone_verification_session' => null,
    ]);
}

You can swap the driver out on the fly as necessary.

use Roomies\Phonable\Facades\Verification;

Verification::driver('prelude')->send($user);

License

The MIT License (MIT). Please see License File for more information.