itmosoft / laravel-leads
Lead capture, qualification, assignment, pipeline stages, and conversion tracking for Laravel applications.
Requires
- php: ^8.3
- illuminate/contracts: ^12.0 || ^13.0
- illuminate/database: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
Requires (Dev)
- orchestra/testbench: ^10.0 || ^11.0
- phpunit/phpunit: ^11.0 || ^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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_toandactor_idare 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.