README

A Laravel integration for the official Prelude PHP SDK. Phone number verification (OTP), lookups, transactional messages, notifications and anti-fraud signals — wired into the Laravel container, configured the Laravel way and testable without ever hitting the API.

📖 Documentation: prelude-sdk-laravel.andreatantimonaco.me

Prelude documentation

Requirements

• PHP 8.2+
• Laravel 12 or 13

Compatibility

This package follows its own semantic versioning timeline, independent of the upstream SDK. The table below maps each package release to the versions it is tested against.

The Prelude PHP SDK is currently pre-1.0, so its minor releases may introduce breaking changes. The package therefore tracks a single SDK minor (^0.4.0, i.e. >=0.4.0 <0.5.0) and widens that constraint only once a new SDK minor has been tested. A breaking change in the SDK that forces a breaking change in this package's public API results in a new major release here.

Installation

composer require andreaalhena/prelude-sdk-laravel

The service provider and the Prelude facade are auto-discovered.

Configuration

Add your API token to .env (you can find it in the Prelude Dashboard):

PRELUDE_API_TOKEN=your-api-token

Optionally publish the configuration file:

php artisan vendor:publish --tag=prelude-config

Usage

Every Prelude service is available through the Prelude facade (or by injecting AndreaAlhena\PreludeSdkLaravel\PreludeManager).

Verification

Create an OTP verification and check the code submitted by the user:

use AndreaAlhena\PreludeSdkLaravel\Facades\Prelude;

$verification = Prelude::verification()->create(
    target: ['type' => 'phone_number', 'value' => '+39012345678'],
);

$check = Prelude::verification()->check(
    target: ['type' => 'phone_number', 'value' => '+39012345678'],
    code: '123456',
);

Lookup

Retrieve metadata for a phone number (carrier, line type, country, fraud flags):

$lookup = Prelude::lookup()->lookup('+39012345678');

Transactional

Send a transactional message from a template:

$message = Prelude::transactional()->send(
    templateID: 'template_01jc44vmmcf8t9z5rejkk30q41',
    to: '+39012345678',
);

Notify

Send notification messages, in single or batch mode, and manage subscriptions:

$notification = Prelude::notify()->send(/* ... */);
$batch = Prelude::notify()->sendBatch(/* ... */);
$configs = Prelude::notify()->listSubscriptionConfigs();

Watch

Anti-fraud signals — predict verification outcomes, report events and send feedback:

$prediction = Prelude::watch()->predict(
    target: ['type' => 'phone_number', 'value' => '+39012345678'],
    signals: [/* ... */],
);

Verification Management

Manage test/excluded phone numbers and sender IDs:

$numbers = Prelude::verificationManagement()->listPhoneNumbers();
$senderIDs = Prelude::verificationManagement()->listSenderIDs();

Raw responses

Every service exposes its raw variant through the SDK's raw property when you need the unwrapped API response:

$response = Prelude::verification()->raw->create(/* ... */);

Escape hatch

The underlying SDK client is bound as a singleton and always within reach:

$client = Prelude::client(); // \Prelude\Client

Testing your application

Prelude::fake() swaps the SDK client with one backed by a fake transporter, so your tests replay queued responses instead of calling the API:

use AndreaAlhena\PreludeSdkLaravel\Facades\Prelude;

it('verifies the phone number', function () {
    $fake = Prelude::fake();
    $fake->queueJson([
        'id' => 'vrf_01jc0t6fwwfgfsq1md24mhyztj',
        'method' => 'message',
        'status' => 'success',
    ]);

    // ... code under test calling Prelude::verification()->create(...) ...

    $fake->assertSentCount(1);
    $fake->assertSent(fn ($request) => str_ends_with($request->getUri()->getPath(), '/v2/verification'));
});

The fake transporter also offers queue() for full PSR-7 responses, recorded() to inspect every sent request, and assertNothingSent().

Testing the package

composer test

License

The MIT License (MIT). See LICENSE.md for details.