Download the PHP package prelude-so/laravel without Composer

Prelude Laravel Package

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:

Configuration

Automatic Setup

Run the install command to automatically set up the package:

This command will:

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

Manual Setup

If you prefer manual setup:

1. Publish the configuration file:

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

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

Usage

Using the Facade

The package provides a convenient facade for accessing Prelude services:

Dependency Injection

You can also inject the PreludeClient directly into your classes:

SendTransactionalRequest

For sending transactional messages with comprehensive validation:

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:

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

For creating verifications with full parameter validation:

CheckVerificationRequest

For checking verification codes with target and code validation:

PredictOutcomeRequest

For predicting outcomes with comprehensive validation:

LookupRequest

For looking up phone number information with comprehensive validation:

SendFeedbackRequest

For sending feedback about verifications with comprehensive validation:

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

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:

See DOCKER.md for detailed Docker setup instructions.

Local Setup

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

Testing

This package uses Pest for testing.

With Docker:

Local Testing:

License

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