itmosoft / laravel-referrals
Referral codes, attribution, qualification, and reward integration 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.5 || ^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Referral codes, attribution, qualification, and reward integration for Laravel applications.
Requirements
- PHP 8.3+
- Laravel 12 or 13
Installation
composer require itmosoft/laravel-referrals php artisan vendor:publish --tag=itmosoft-referrals-config php artisan vendor:publish --tag=itmosoft-referrals-migrations php artisan migrate
Laravel package auto-discovery registers the service provider.
Basic usage
use ItmoSoft\Referrals\ReferralManager; // Create a referral code for any Eloquent model. $code = app(ReferralManager::class)->createCode($user); // Attribute a new user to the referral code. $referral = app(ReferralManager::class)->record($code->code, $newUser); // Call this after your own business rules determine that the referral qualifies. $referral = app(ReferralManager::class)->qualify($referral);
Reward integration
This package deliberately does not own points, wallet balances, gift-card balances, or payment instruments. Implement ReferralRewardIssuer and connect it to your reward system.
namespace App\Referrals; use ItmoSoft\Referrals\Contracts\ReferralRewardIssuer; use ItmoSoft\Referrals\Models\Referral; class AppReferralRewardIssuer implements ReferralRewardIssuer { public function issue(Referral $referral): void { // Integrate with laravel-loyalty, laravel-gift-cards, // or your application's own reward service. // Make this operation idempotent using the referral ID. } }
Bind the implementation in a service provider:
use App\Referrals\AppReferralRewardIssuer; use ItmoSoft\Referrals\Contracts\ReferralRewardIssuer; $this->app->bind(ReferralRewardIssuer::class, AppReferralRewardIssuer::class);
Then issue rewards after qualification:
$referral = app(ReferralManager::class)->issueRewards( $referral, app(ReferralRewardIssuer::class) );
issueRewards() marks a referral as rewarded only after the issuer returns successfully. The issuer should be idempotent because external side effects cannot be rolled back by a database transaction.
Lifecycle
pending: recorded and awaiting qualification.qualified: your application has confirmed the referral meets its rules.rewarded: the reward issuer completed successfully.rejected: the referral was rejected while pending.
Only pending referrals can be rejected. Only qualified referrals can be rewarded.
Models and tables
ReferralCode: polymorphic code owner, unique code, active flag, metadata.Referral: referral code, polymorphic referrer/referee, lifecycle timestamps, metadata.- Default tables:
itmosoft_referral_codesanditmosoft_referrals.
The table prefix is configurable through itmosoft-referrals.table_prefix.
Important implementation notes
- Self-referrals are rejected.
- A referee can only be attributed once, enforced by application validation and a database unique index.
- Referral code matching is case-insensitive at the manager boundary by normalizing input to uppercase.
- Qualification rules, fraud detection, reward amounts, expiration, and campaign-specific policies belong to the host application.
- For high-volume concurrent referral attribution, handle unique-index violations as duplicate attribution at the application boundary.
Tests
composer install
composer test
Versioning
This package follows semantic versioning. See CHANGELOG.md.
License
MIT. See LICENSE.