README

A Laravel integration package for the prelude-so/sdk, providing seamless integration of Prelude services into your Laravel applications.

Requirements

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

Installation

You can install the package via Composer:

composer require prelude-so/laravel

Configuration

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

If you prefer manual setup:

Publish the configuration file:

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

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

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

Usage

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');

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
        ]);
    }
}

Complete Examples

For complete working examples, see the 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

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);
    }
}

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

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 for detailed Docker setup instructions.

Local Setup

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

composer install

Testing

This package uses Pest for testing.

With Docker:

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

Local Testing:

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

License

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

prelude-so / laravel

Maintainers

Details