Laravel Referral Laravel Package

Getting Started

Install the package via Composer and publish its assets:

composer require jijunair/laravel-referral
php artisan vendor:publish --provider="Jijunair\LaravelReferral\LaravelReferralServiceProvider"
php artisan migrate

Look first at the published config/referral.php (or similarly named config file) and the migration files — these tell you which tables the package owns (referrals, possibly referral_codes/referral_rewards) and which knobs (code length, expiry, reward type) are configurable. Then read the package's src/Traits/ directory and its README.md; the public API is almost entirely expressed as model traits plus a small number of events.

The first use case to wire up is: add the package trait to your User model, generate a referral code on account creation, and record a referral when a new user signs up with someone else's code.

use Jijunair\LaravelReferral\Traits\HasReferrals;

class User extends Authenticatable
{
    use HasReferrals;
}

From there, a minimal flow is: user shares https://app.test/register?ref=ABC123 → controller resolves the code → service records the referral against the new user's ID.

Implementation Patterns

Trait-based user integration. The package's model traits are the primary surface. Expect methods in the vein of generateReferralCode(), referrals() (hasMany), referredBy(), and referralLink(). Do not reimplement code generation yourself — call the trait method inside a Registered observer or a model booted() event so every user has a code, including users created via seeders and imports.

Attribution capture middleware. The ?ref= param only exists at landing time but is needed at signup time. Persist it early:

// app/Http/Middleware/CaptureReferral.php
public function handle($request, Closure $next)
{
    if ($request->filled('ref')) {
        $request->session()->put('referral_code', $request->query('ref'));
        Cookie::queue('referral_code', $request->query('ref'), 60 * 24 * 30);
    }
    return $next($request);
}

Read the session/cookie value in your registration controller and pass it to the package.

Event-driven rewards. The package fires referral lifecycle events (signup vs. conversion). Hook your reward logic to those events in an EventServiceProvider listener rather than calling reward code inline in controllers — this keeps reward policy out of your auth flow and lets you replay/backfill rewards:

Event::listen(ReferralRegistered::class, function ($event) {
    // award points, issue coupon, notify referrer
});

Two-phase referrals. Most referral programs distinguish pending (code applied at signup) from completed (referee made a purchase / verified email). Configure a "qualifying action" — typically a job or listener that flips the referral status and triggers the reward. If the package exposes a status enum or completed_at column in the migration, model your reward around that, not around the signup event.

Morphable referee/referrer. If the package supports polymorphic relations (check the migration for referrer_id/referrer_type), you can support Team referrals later without schema changes. Plan your config and trait usage around this even if today only User refers.

Reporting. Build a small read-only admin resource over what the package writes. Referral dashboards are almost always needed (top referrers, conversion %, pending payouts), and there is no built-in UI in a package like this — expect to roll your own admin page over the referrals table.

Gotchas and Tips

Config caching. If you tweak config/referral.php (code length, expiry) and things don't change in production, run php artisan config:clear. This is the single most common "the package is broken" issue with small vendor packages.

Race conditions on code uniqueness. Referral codes are typically generated at registration. If the package uses a short/random code, add a unique index on the code column yourself and wrap generation in a retry loop — two simultaneous signups can collide on low-entropy generators.

Self-referral and duplicate attribution. Enforce in application code that referrer_id !== referee_id, that the code belongs to a verified account, and that a user can only be referred once. The package usually does not enforce business rules like these.

Case sensitivity. Codes are often compared with = in MySQL, which is case-insensitive by default but collation-dependent. Normalize (upper/lowercase) codes before lookup to avoid "REF123 works for Alice but not Bob" bugs.

Expiry and cookie lifetime. If you store the referral code in a session, it dies with the session; a cookie with a 30-day TTL is friendlier. But also enforce a config-driven attribution window on the referral record so late signups past the expiry don't credit.

Deleting users breaks referrer chains. If referrer_id is a foreign key with onDelete('cascade'), deleting a referrer nukes their referrals (and your reward audit trail). Prefer nullOnDelete or soft deletes on the user model.

Published migration vs. package migration. Once published and run, updating the package may ship new migrations that conflict. Read the package changelog before updating and diff published migrations against the vendor ones.

Event not firing on bulk operations. If you import users or use DB::table()->insert(), model events (and therefore referral code generation) are skipped. Always use the Eloquent model or explicitly call the trait's generation method during imports.

Check the trait list after each upgrade. Because the API is trait-based and undocumented in a formal way, methods can be renamed. If your User model suddenly errors on a missing method, composer dump-autoload and inspect vendor/jijunair/laravel-referral/src/Traits/ before assuming a bug.

Low-star package caveat. At ~97 stars this is a small, single-maintainer package. Pin the version in composer.json, and keep your reward/listener logic in your own app/ code so that swapping the package out later is a matter of replacing the trait and event wiring, not rewriting business logic.