README

A comprehensive Laravel package for multi-layer lead persistence, webhook integrations, and progressive lead creation. This package provides sophisticated tools for managing leads in your Laravel application with advanced features like encrypted storage, automatic fallbacks, and real-time synchronization.

Features

🔄 Multi-layer Lead Persistence: Automatic fallback chain (Redis → Session → Cookies → localStorage)
🪝 Webhook Integration: Configurable webhooks with custom field mapping and retry logic
📱 Phone Formatting: International phone number formatting with country-specific rules
💾 Progressive Lead Creation: Create leads from query parameters before form submission
🔐 Encrypted Storage: Secure lead ID encryption across all storage layers
🌐 JavaScript Integration: Client-side lead storage with automatic synchronization
🔀 Lead Merging: Intelligent merging of lead data from multiple sources
📊 UTM Tracking: Automatic capture and storage of marketing parameters

Installation

Install the package via Composer:

composer require skaisser/laravel-lead

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=lead-persistence-config

This will create a config/lead-persistence.php file where you can customize the package settings.

Key Configuration Options

return [
    // The model class that represents leads
    'lead_model' => App\Models\Lead::class,
    
    // Storage layers configuration
    'use_session' => true,
    'use_cookies' => true,
    'cookie_name' => 'lead_id',
    'cookie_duration' => 525600, // 365 days
    
    // Encryption settings
    'encryption_enabled' => true,
    
    // Cache configuration
    'cache_prefix' => 'lead_',
    'cache_ttl' => 1800, // 30 minutes
];

Usage

Basic Lead Persistence

use Skaisser\LaravelLead\Facades\LeadPersistence;

// Store a lead
$lead = Lead::create(['name' => 'John Doe', 'email' => 'john@example.com']);
LeadPersistence::storeLead($lead);

// Retrieve current lead (with automatic fallback)
$currentLead = LeadPersistence::getCurrentLead();

// Check if a lead exists
if (LeadPersistence::hasStoredLead()) {
    // Lead exists in storage
}

// Clear stored lead
LeadPersistence::clearStoredLead();

Progressive Lead Creation

// Save lead data progressively (creates or updates)
$leadData = [
    'name' => request('name'),
    'email' => request('email'),
    'phone' => request('phone'),
    'country_code' => request('country_code'),
    'query_data' => request()->query(), // UTM parameters, etc.
];

$lead = LeadPersistence::saveLead($leadData);

// Update existing lead
$existingLead = LeadPersistence::getCurrentLead();
$updatedLead = LeadPersistence::saveLead($newData, $existingLead);

Webhook Integration

First, publish and run the migrations:

php artisan vendor:publish --tag=lead-persistence-migrations
php artisan migrate

Then use webhooks in your application:

use Skaisser\LaravelLead\Jobs\ProcessWebhookSubmission;
use Skaisser\LaravelLead\Models\Webhook;

// Create a webhook configuration
$webhook = Webhook::create([
    'name' => 'CRM Integration',
    'url' => 'https://api.crm.com/leads',
    'method' => 'POST',
    'headers' => ['Authorization' => 'Bearer token123'],
    'selected_fields' => ['name', 'email', 'phone', 'company'],
    'field_mapping' => [
        ['original_field' => 'name', 'custom_name' => 'full_name'],
        ['original_field' => 'email', 'custom_name' => 'contact_email'],
    ],
    'timeout' => 30,
    'retry_attempts' => 3,
    'retry_delay' => 60,
]);

// Dispatch webhook for a lead
ProcessWebhookSubmission::dispatch($lead);

Phone Number Formatting

use Skaisser\LaravelLead\Services\PhoneFormatter;

$formatter = app(PhoneFormatter::class);

// Format a phone number
$formatted = $formatter->format('11999999999', '+55'); // (11) 99999-9999

// Validate a phone number
$isValid = $formatter->isValid('1234567890', '+1');

// Get international format
$international = $formatter->toInternational('11999999999', '+55'); // +55 11 999999999

// Add custom format for a country
$formatter->addCustomFormat('33', function($numbers) {
    // Custom French formatting
    return preg_replace('/(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})/', '$1 $2 $3 $4 $5', $numbers);
});

JavaScript Integration

Publish the JavaScript assets:

php artisan vendor:publish --tag=lead-persistence-assets

Include the script in your layout:

<script src="{{ asset('js/vendor/lead-persistence/lead-storage.js') }}"></script>

<!-- Configure (optional) -->
<script>
window.LEAD_PERSISTENCE_COOKIE_NAME = 'my_lead_id';
window.LEAD_PERSISTENCE_COOKIE_DAYS = 365;
window.LEAD_PERSISTENCE_SECURE = true;
</script>

JavaScript API

// Store lead ID
window.leadStorage.storeLead('encrypted_lead_id_here');

// Get stored lead ID
const leadId = window.leadStorage.getStoredLeadId();

// Clear stored lead
window.leadStorage.clearStoredLead();

// Sync storage across layers
window.leadStorage.syncStorage();

Livewire Integration

The package automatically integrates with Livewire if available:

// In your Livewire component
$this->dispatch('store-lead', ['leadId' => $encryptedLeadId]);
$this->dispatch('check-local-storage');
$this->dispatch('clear-lead');

Advanced Usage

Custom Lead Model

Create your lead model and configure it:

// app/Models/Lead.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Lead extends Model
{
    protected $fillable = [
        'name', 'email', 'phone', 'company',
        'country_code', 'query_data', 'accepted_terms'
    ];
    
    protected $casts = [
        'query_data' => 'array',
        'accepted_terms' => 'boolean',
    ];
}

Update the configuration:

// config/lead-persistence.php
'lead_model' => App\Models\Lead::class,

Custom Webhook Model

Extend the base webhook model for custom functionality:

namespace App\Models;

use Skaisser\LaravelLead\Models\Webhook as BaseWebhook;

class CustomWebhook extends BaseWebhook
{
    public function getAvailableFields(): array
    {
        return array_merge(parent::getAvailableFields(), [
            'custom_field' => 'Custom Field',
            'another_field' => 'Another Field',
        ]);
    }
}

Webhook Transformations

Add custom transformations for webhook data:

// config/lead-persistence.php
'webhook_transformations' => [
    'phone' => function($value) {
        return '+1' . preg_replace('/[^0-9]/', '', $value);
    },
    'created_at' => function($value) {
        return Carbon::parse($value)->toIso8601String();
    },
],

Testing

Run the package tests:

composer test

Security

All lead IDs are encrypted by default using Laravel's encryption
Visitor-isolated caching prevents data leakage between users
Cookie security follows Laravel's session configuration
Webhook URLs are validated before requests

License

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

skaisser / laravel-lead

Maintainers

Details