PHPackages                             prelude-so/laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. prelude-so/laravel

ActiveLibrary[Utility & Helpers](/categories/utility)

prelude-so/laravel
==================

Laravel integration package for prelude-so/sdk

1.2.0(11mo ago)1224↓50%1[1 issues](https://github.com/AndreaAlhena/prelude-laravel/issues)[1 PRs](https://github.com/AndreaAlhena/prelude-laravel/pulls)MITPHPPHP ^8.1CI failing

Since Aug 3Pushed 11mo agoCompare

[ Source](https://github.com/AndreaAlhena/prelude-laravel)[ Packagist](https://packagist.org/packages/prelude-so/laravel)[ RSS](/packages/prelude-so-laravel/feed)WikiDiscussions main Synced 3mo ago

READMEChangelogDependencies (9)Versions (19)Used By (0)

Prelude Laravel Package
=======================

[](#prelude-laravel-package)

[![codecov](https://camo.githubusercontent.com/e6d2b171ea0d5f3c188e03e14a2e421731c55a174c163c423d3a1d9ec91e3cb2/68747470733a2f2f636f6465636f762e696f2f67682f416e64726561416c68656e612f7072656c7564652d6c61726176656c2f67726170682f62616467652e7376673f746f6b656e3d4e554d584e41484c5152)](https://codecov.io/gh/AndreaAlhena/prelude-laravel)[![Made with Trae](https://camo.githubusercontent.com/a744c283025bab322f80b1cefc34e9b85c643871d3ff32d16a2a2eb640b8c686/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d616465253230776974682d5472616525323041492d626c756576696f6c65743f7374796c653d666c617426636f6c6f723d333246303842)](https://trae.ai)

A Laravel integration package for the [prelude-so/sdk](https://github.com/prelude-so/sdk), providing seamless integration of Prelude services into your Laravel applications.

Requirements
------------

[](#requirements)

- **PHP**: 8.1 or higher
- **Laravel**: 9.0 or higher (supports Laravel 9, 10, and 11)
- **Composer**: 2.0 or higher

Installation
------------

[](#installation)

You can install the package via Composer:

```
composer require prelude-so/laravel
```

Configuration
-------------

[](#configuration)

### Automatic Setup

[](#automatic-setup)

Run the install command to automatically set up the package:

```
php artisan prelude:install
```

This command will:

- Publish the configuration file
- Add environment variables to your `.env` file
- Provide setup instructions

### Manual Setup

[](#manual-setup)

If you prefer manual setup:

1. Publish the configuration file:

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

2. Add your Prelude API credentials to your `.env` file:

```
PRELUDE_API_KEY=your-api-key-here
PRELUDE_BASE_URL=https://api.prelude.so
PRELUDE_TIMEOUT=30
```

3. Configure the package in `config/prelude.php` as needed.

Usage
-----

[](#usage)

### Using the Facade

[](#using-the-facade)

The package provides a convenient facade for accessing Prelude services:

```
use PreludeSo\Laravel\Facades\Prelude;

// Create a phone verification
$verification = Prelude::verification()->create('+1234567890');

// Check verification OTP
$result = Prelude::verification()->check($verificationId, '123456');

// Lookup phone number information
$lookup = Prelude::lookup()->phoneNumber('+1234567890');

// Send transactional message
$message = Prelude::transactional()->send('+1234567890', 'Your verification code is 123456');

// Process webhook data (requires SDK v1.2.1+)
$webhookData = json_decode(request()->getContent(), true);
$webhookResult = Prelude::webhook()->processWebhook($webhookData);
```

### Dependency Injection

[](#dependency-injection)

You can also inject the `PreludeClient` directly into your classes:

```
use PreludeSo\Sdk\PreludeClient;

class UserController extends Controller
{
    public function createVerification(Request $request, PreludeClient $prelude)
    {
        $phoneNumber = $request->input('phone_number');
        $verification = $prelude->verification()->create($phoneNumber);

        return response()->json([
            'verification_id' => $verification->getId(),
            'status' => $verification->getStatus()
        ]);
    }

    public function checkVerification(Request $request, PreludeClient $prelude)
    {
        $verificationId = $request->input('verification_id');
        $code = $request->input('code');

        $result = $prelude->verification()->check($verificationId, $code);

        return response()->json([
            'success' => $result->isSuccess(),
            'status' => $result->getStatus()->value
        ]);
    }
}
```

#### SendTransactionalRequest

[](#sendtransactionalrequest)

For sending transactional messages with comprehensive validation:

```
use PreludeSo\Laravel\Http\Requests\SendTransactionalRequest;

class MessageController extends Controller
{
    public function sendTransactional(SendTransactionalRequest $request)
    {
        // All validation is handled automatically
        $to = $request->validated('to');
        $templateId = $request->validated('template_id');
        $options = $request->validated('options');
        $metadata = $request->validated('metadata');

        // Create options object for SDK if provided
        $optionsObject = null;
        if ($options) {
            $optionsObject = new \PreludeSo\Sdk\Options($options);
        }

        // Send transactional message using the SDK
        $result = Prelude::transactional()->send($to, $templateId, $optionsObject);

        return response()->json([
            'message_id' => $result->getId(),
            'status' => $result->getStatus(),
            'sent_at' => $result->getSentAt(),
            'recipient' => $to,
            'template_id' => $templateId,
        ]);
    }
}
```

### Complete Examples

[](#complete-examples)

For complete working examples, see the [`examples/UserController.php`](examples/UserController.php) file which demonstrates:

- Phone verification creation and checking
- Phone number lookup
- Transactional messaging
- Error handling
- Both Facade and dependency injection patterns

### Using the Trait

[](#using-the-trait)

For models or other classes that frequently interact with Prelude, use the provided trait:

```
use PreludeSo\Laravel\Traits\InteractsWithPrelude;

class VerificationService
{
    use InteractsWithPrelude;

    public function createVerification(string $phoneNumber)
    {
        return $this->createVerification($phoneNumber);
    }

    public function checkVerification(string $verificationId, string $code)
    {
        return $this->checkVerification($verificationId, $code);
    }

    public function lookupPhone(string $phoneNumber)
    {
        return $this->lookupPhoneNumber($phoneNumber);
    }

    public function sendMessage(string $phoneNumber, string $message)
    {
        return $this->sendTransactionalMessage($phoneNumber, $message);
    }
}
```

### Form Requests with Prelude Integration

[](#form-requests-with-prelude-integration)

The package provides Form Request classes that extend Laravel's FormRequest with comprehensive validation rules for Prelude SDK parameters:

#### CreateVerificationRequest

[](#createverificationrequest)

For creating verifications with full parameter validation:

```
use PreludeSo\Laravel\Http\Requests\CreateVerificationRequest;

// Use the base class directly with all validation rules
$request = new CreateVerificationRequest();

// Or extend it for custom requirements
class CreateOtpRequest extends CreateVerificationRequest
{
    public function rules(): array
    {
        // Option 1: Use all parent rules
        return parent::rules();

        // Option 2: Override with custom rules
        return [
            'target.type' => 'required|string|in:phone_number',
            'target.value' => 'required|string|regex:/^\+?[1-9]\d{1,14}$/',
            'signals' => 'nullable|array',
            'options' => 'nullable|array',
            'metadata' => 'nullable|array',
            'dispatch_id' => 'nullable|string',
        ];
    }
}
```

#### CheckVerificationRequest

[](#checkverificationrequest)

For checking verification codes with target and code validation:

```
use PreludeSo\Laravel\Http\Requests\CheckVerificationRequest;

class VerificationController extends Controller
{
    public function checkVerification(CheckVerificationRequest $request)
    {
        // All validation is handled automatically
        $target = $request->validated('target');
        $code = $request->validated('code');

        // Create target object for SDK
        $targetObject = new \PreludeSo\Sdk\Target(
            $target['value'],
            $target['type']
        );

        // Check verification using the SDK
        $result = Prelude::verification()->check($targetObject, $code);

        return response()->json([
            'success' => $result->isSuccess(),
            'status' => $result->getStatus()->value
        ]);
    }
}
```

#### PredictOutcomeRequest

[](#predictoutcomerequest)

For predicting outcomes with comprehensive validation:

```
use PreludeSo\Laravel\Http\Requests\PredictOutcomeRequest;

class PredictionController extends Controller
{
    public function predictOutcome(PredictOutcomeRequest $request)
    {
        // All validation is handled automatically
        $target = $request->validated('target');
        $signals = $request->validated('signals');
        $metadata = $request->validated('metadata');
        $dispatchId = $request->validated('dispatch_id');

        // Create objects for SDK
        $targetObject = new \PreludeSo\Sdk\Target(
            $target['value'],
            $target['type']
        );

        $signalsObject = new \PreludeSo\Sdk\Signals($signals);

        $metadataObject = null;
        if ($metadata) {
            $metadataObject = new \PreludeSo\Sdk\Metadata($metadata);
        }

        // Predict outcome using the SDK
        $result = Prelude::predictOutcome($targetObject, $signalsObject, $dispatchId, $metadataObject);

        return response()->json([
            'prediction_id' => $result->getId(),
            'outcome' => $result->getOutcome(),
            'confidence' => $result->getConfidence()
        ]);
    }
}
```

#### LookupRequest

[](#lookuprequest)

For looking up phone number information with comprehensive validation:

```
use PreludeSo\Laravel\Http\Requests\LookupRequest;

class LookupController extends Controller
{
    public function lookupPhoneNumber(LookupRequest $request)
    {
        // All validation is handled automatically
        $phoneNumber = $request->validated('phone_number');
        $type = $request->validated('type', []);

        // Lookup phone number using the SDK
        $result = Prelude::lookup()->lookup($phoneNumber, $type);

        return response()->json([
            'phone_number' => $result->getPhoneNumber(),
            'country_code' => $result->getCountryCode(),
            'line_type' => $result->getLineType()?->value,
            'caller_name' => $result->getCallerName(),
            'flags' => array_map(fn($flag) => $flag->value, $result->getFlags()),
            'network_info' => [
                'carrier_name' => $result->getNetworkInfo()->getCarrierName(),
                'mcc' => $result->getNetworkInfo()->getMcc(),
                'mnc' => $result->getNetworkInfo()->getMnc(),
            ],
            'original_network_info' => [
                'carrier_name' => $result->getOriginalNetworkInfo()->getCarrierName(),
                'mcc' => $result->getOriginalNetworkInfo()->getMcc(),
                'mnc' => $result->getOriginalNetworkInfo()->getMnc(),
            ],
        ]);
    }
}
```

#### SendFeedbackRequest

[](#sendfeedbackrequest)

For sending feedback about verifications with comprehensive validation:

```
use PreludeSo\Laravel\Http\Requests\SendFeedbackRequest;

class FeedbackController extends Controller
{
    public function sendFeedback(SendFeedbackRequest $request)
    {
        // All validation is handled automatically
        $feedbacks = $request->validated('feedbacks');

        // Create feedback objects for SDK
        $feedbackObjects = [];
        foreach ($feedbacks as $feedback) {
            // Create target object
            $targetObject = new \PreludeSo\Sdk\ValueObjects\Shared\Target(
                $feedback['target']['value'],
                $feedback['target']['type']
            );

            // Create signals object if provided
            $signalsObject = null;
            if (!empty($feedback['signals'])) {
                $signalsObject = new \PreludeSo\Sdk\ValueObjects\Shared\Signals($feedback['signals']);
            }

            // Create metadata object if provided
            $metadataObject = null;
            if (!empty($feedback['metadata'])) {
                $metadataObject = new \PreludeSo\Sdk\ValueObjects\Shared\Metadata($feedback['metadata']);
            }

            $feedbackObjects[] = new \PreludeSo\Sdk\ValueObjects\Watch\Feedback(
                $targetObject,
                $feedback['type'],
                $signalsObject,
                $feedback['dispatch_id'] ?? '',
                $metadataObject
            );
        }

        // Send feedback using the SDK
        $result = Prelude::sendFeedback($feedbackObjects);

        return response()->json([
            'success' => $result->isSuccess(),
            'processed_count' => count($feedbackObjects)
        ]);
    }
}
```

#### Supported Validation Parameters

[](#supported-validation-parameters)

**CreateVerificationRequest** includes validation rules for all SDK parameters:

- **Target** (required): Phone number or email validation

    - `target.type`: Must be 'phone\_number' or 'email\_address'
    - `target.value`: Validated based on the target type
- **Signals** (optional): Browser/device information

    - `signals.ip_address`: Valid IP address
    - `signals.user_agent`: Browser user agent string
    - `signals.device_fingerprint`: Device identification
    - And more browser-related fields
- **Options** (optional): Verification configuration

    - `options.template`: Custom message template
    - `options.expiry_minutes`: OTP expiration time (1-60 minutes)
    - `options.code_length`: OTP length (4-10 digits)
    - `options.channel`: Delivery method (sms, voice, email, whatsapp)
    - And more configuration options
- **Metadata** (optional): Custom tracking data

    - `metadata.user_id`: Your internal user ID
    - `metadata.source`: Request source identifier
    - `metadata.campaign_id`: Marketing campaign tracking
    - `metadata.custom_fields`: Additional custom data
- **Dispatch ID** (optional): Frontend SDK integration

    - `dispatch_id`: ID from Prelude's JavaScript SDK for enhanced fraud detection

**CheckVerificationRequest** includes validation rules for verification checking:

- **Target** (required): Phone number or email validation

    - `target.type`: Must be 'phone\_number' or 'email\_address'
    - `target.value`: Validated based on the target type
- **Code** (required): Verification code validation

    - `code`: String with length between 4-10 characters

**PredictOutcomeRequest** includes validation rules for outcome prediction:

- **Target** (required): Phone number or email validation

    - `target.type`: Must be 'phone\_number' or 'email\_address'
    - `target.value`: Validated based on the target type
- **Signals** (required): Browser/device information for fraud detection

    - `signals.ip_address`: Valid IP address
    - `signals.user_agent`: Browser user agent string
    - `signals.device_fingerprint`: Device identification
    - `signals.browser_plugins`: Array of browser plugins
    - `signals.screen_resolution`: Screen resolution information
    - `signals.timezone`: User timezone
    - `signals.language`: User language preference
    - `signals.session_id`: Session identifier
    - `signals.timestamp`: Request timestamp
- **Metadata** (optional): Custom tracking data

    - `metadata.user_id`: Your internal user ID
    - `metadata.source`: Request source identifier
    - `metadata.campaign_id`: Marketing campaign tracking
    - `metadata.reference_id`: Reference identifier
    - `metadata.custom_fields`: Additional custom data
- **Dispatch ID** (optional): Frontend SDK integration

    - `dispatch_id`: ID from Prelude's JavaScript SDK for enhanced fraud detection

**LookupRequest** includes validation rules for phone number lookup:

- **Phone Number** (required): Phone number in E.164 format

    - `phone_number`: Must be in E.164 format (e.g., +1234567890)
    - Validates international format with country code
    - Length between 7-15 digits (including country code)
- **Type** (optional): Array of lookup features to retrieve
- `type`: Optional array of lookup feature strings
- `type.*`: Each type must be a valid LookupType enum value
- Available lookup types (defined in `LookupType` enum):

    - `cnam`: Caller Name (CNAM) information
    - `network_info`: Network and carrier information
    - `fraud`: Fraud detection and risk analysis

**SendFeedbackRequest** includes validation rules for feedback submission:

- **Feedbacks** (required): Array of feedback objects
    - `feedbacks`: Required array with minimum 1 item
    - `feedbacks.*.target`: Required target object with phone number or email validation
        - `feedbacks.*.target.type`: Must be 'phone\_number' or 'email\_address'
        - `feedbacks.*.target.value`: Validated based on the target type
    - `feedbacks.*.type`: Required string identifier for the feedback type (max 100 characters)
    - `feedbacks.*.signals`: Optional browser/device information for fraud detection
        - `feedbacks.*.signals.ip_address`: Valid IP address
        - `feedbacks.*.signals.user_agent`: Browser user agent string
        - `feedbacks.*.signals.device_fingerprint`: Device identification
        - And more browser-related fields
    - `feedbacks.*.metadata`: Optional custom tracking data
        - `feedbacks.*.metadata.user_id`: Your internal user ID
        - `feedbacks.*.metadata.source`: Request source identifier
        - `feedbacks.*.metadata.campaign_id`: Marketing campaign tracking
        - `feedbacks.*.metadata.reference_id`: Reference identifier
        - `feedbacks.*.metadata.custom_fields`: Additional custom data
    - `feedbacks.*.dispatch_id`: Optional ID from Prelude's JavaScript SDK for enhanced fraud detection

**SendTransactionalRequest** includes validation rules for transactional messaging:

- **To** (required): Recipient validation

    - `to`: Valid phone number (international format, 7-15 digits) or email address
- **Template ID** (required): Message template

    - `template_id`: String identifier for the message template (max 255 characters)
- **Options** (optional): Message configuration

    - `options.from`: Sender identifier
    - `options.channel`: Delivery method (sms, email, whatsapp, voice)
    - `options.priority`: Message priority (low, normal, high)
    - `options.scheduled_at`: Schedule message for future delivery
    - `options.callback_url`: URL for delivery status callbacks
    - `options.webhook_url`: URL for webhook notifications
    - `options.variables`: Template variables for personalization
    - `options.attachments`: File attachments (URLs)
    - `options.reply_to`: Reply-to email address
    - `options.subject`: Email subject line
    - `options.tags`: Message tags for categorization
- **Metadata** (optional): Custom tracking data

    - `metadata.user_id`: Your internal user ID
    - `metadata.source`: Request source identifier
    - `metadata.campaign_id`: Marketing campaign tracking
    - `metadata.reference_id`: External reference ID
    - `metadata.custom_fields`: Additional custom data

Configuration Options
---------------------

[](#configuration-options)

The configuration file (`config/prelude.php`) supports the following options:

- `api_key`: Your Prelude API key
- `base_url`: The base URL for the Prelude API
- `timeout`: Request timeout in seconds
- `defaults`: Default options for SDK operations

Development Environment
-----------------------

[](#development-environment)

### Docker Setup (Recommended)

[](#docker-setup-recommended)

For a consistent development environment, use Docker:

```
# Build and start the environment
make build
make up

# Install dependencies
make install

# Run tests
make test
```

See [DOCKER.md](DOCKER.md) for detailed Docker setup instructions.

### Local Setup

[](#local-setup)

Alternatively, set up locally with PHP 8.1+ and Composer:

```
composer install
```

Testing
-------

[](#testing)

This package uses [Pest](https://pestphp.com/) for testing.

### With Docker:

[](#with-docker)

```
make test                # Run tests
make test-coverage      # Run with coverage
make test-watch         # Run in watch mode
```

### Local Testing:

[](#local-testing)

```
composer test           # Run tests
composer test-coverage  # Run with coverage
```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

30

—

LowBetter than 62% of packages

Maintenance32

Infrequent updates — may be unmaintained

Popularity18

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

4

Last Release

330d ago

PHP version history (2 changes)1.0.0PHP ^8.2

1.1.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/6db9affa09a392b44d0d5a7c1839395c4caad414b28310ee638fdd7f4dffdb2e?d=identicon)[AndreaAlhena](/maintainers/AndreaAlhena)

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/prelude-so-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/prelude-so-laravel/health.svg)](https://phpackages.com/packages/prelude-so-laravel)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[api-platform/laravel

API Platform support for Laravel

58171.4k14](/packages/api-platform-laravel)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)