Search by

itmosoft / laravel-leads

adeelrao007

Lead capture, qualification, assignment, pipeline stages, and conversion tracking for Laravel applications.

Package info

github.com/ITMOSOFT/laravel-leads

pkg:composer/itmosoft/laravel-leads

Statistics

Installs: 7

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-17 07:06 UTC

This package is auto-updated.

Last update: 2026-11-17 07:07:12 UTC


README

Lead capture, qualification, assignment, pipeline stages, activity history, follow-up tracking, and conversion references for Laravel 12 and 13.

Requirements

  • PHP 8.3+
  • Laravel 12 or 13

Installation

composer require itmosoft/laravel-leads
php artisan vendor:publish --tag=itmosoft-leads-config
php artisan migrate

Create a lead

use ItmoSoft\Leads\Services\LeadManager;

$lead = app(LeadManager::class)->create([
    'first_name' => 'Sam',
    'last_name' => 'Taylor',
    'email' => 'sam@example.com',
    'company' => 'Example Ltd',
    'status' => 'new',
    'score' => 25,
    'estimated_value' => 5000,
    'currency' => 'USD',
    'follow_up_at' => now()->addDays(2),
], auth()->id());

Statuses are configurable; defaults: new, contacted, qualified, unqualified, converted, lost.

Sources and pipeline stages

use ItmoSoft\Leads\Models\LeadSource;
use ItmoSoft\Leads\Models\LeadStage;

$source = LeadSource::query()->create(['name'=>'Website','slug'=>'website']);
$stage = LeadStage::query()->create(['name'=>'Discovery','slug'=>'discovery','position'=>1]);
$lead->update(['lead_source_id'=>$source->id,'lead_stage_id'=>$stage->id]);

Stage order and won/lost markers are data only in this release; no enforced sales state machine is included.

Search

$leads = app(LeadManager::class)->search([
    'status'=>'qualified',
    'source_id'=>2,
    'stage_id'=>3,
    'assigned_to'=>auth()->id(),
    'search'=>'Taylor',
])->paginate(20);

Use 'assigned_to' => null to find unassigned leads. Lead::query()->dueForFollowUp()->get() finds open leads whose follow-up time has arrived.

Assignment, status and scoring

$lead->assignTo(auth()->id(), auth()->id());
$lead->setStatus('qualified', auth()->id(), 'Budget confirmed.');
$lead->setScore(82);

Assignment and status changes create activity records. Scores default to 0–100.

Activity timeline

app(LeadManager::class)->recordActivity(
    $lead, 'call', 'Discussed requirements.', auth()->id(),
    ['duration_minutes'=>15]
);
$activities = $lead->activities;

Activity type strings are extensible; validate your application's vocabulary at the boundary.

Conversion

The package does not create a customer. Create one through your customer/domain package, then store a reference:

$customer = /* create through your application integration */;
app(LeadManager::class)->convert($lead, 'customer', $customer->getKey(), auth()->id());

Allowed target labels: customer, account, contact, other. The target ID is a scalar string with no foreign key, avoiding coupling to a specific customer schema.

Boundaries and security

  • This package owns lead records, stages and lead activities. It does not own customer profiles, campaigns, email delivery, notifications, promotions, forms, HTTP routes, controllers, admin UI or authorization policies.
  • assigned_to and actor_id are scalar user identifiers; no user foreign key is imposed.
  • Add authorization checks before reading, assigning, exporting, converting or deleting leads.
  • Validate email, phone, custom fields and status transitions in your application.
  • Configure consent, retention and privacy workflows for your jurisdiction.
  • Search uses SQL LIKE, not a full-text search engine.
  • Tenant isolation is not automatic. Integrate with your tenancy layer and scope all lead queries appropriately.

Tests

composer validate --strict
composer install
composer test

License

MIT.