README

The Juzaweb Referral Module provides a flexible and polymorphic referral system for Juzaweb CMS. It allows any model (like User) to generate referral codes, act as a referrer, and track referred entities.

Features

• Polymorphic Referrals: Any model can refer or be referred by any other model.
• Unique Referral Codes: Generates unique, customizable referral codes automatically.
• Easy Integration: Simply add a trait to your models to enable referral functionality.

Installation

Install via Composer:

composer require juzaweb/referral

Then, you can publish and run the migrations if required (typically handled by the Juzaweb module manager):

php artisan module:migrate Referral

Usage

1. Enable Referrals on Your Model

Add the HasReferrals trait to any Eloquent model (e.g., your User model) that will participate in the referral system.

namespace App\Models;

use Juzaweb\Modules\Core\Models\User as BaseUser;
use Juzaweb\Modules\Referral\Traits\HasReferrals;

class User extends BaseUser
{
    use HasReferrals;
}

2. Generating Referral Codes

You can generate a unique referral code statically.

$code = User::generateReferralCode();

Note: The generator handles uniqueness automatically and increases length to prevent infinite loops.

3. Creating a Referral

When a new entity signs up using a referral link or code, you can link the new entity (the "referred") to the existing entity (the "referrer"):

$referrer = User::find(1);
$referred = User::find(2);

// Make the referral
$referral = $referrer->refer($referred);

4. Retrieving Referrals

You can easily retrieve all referrals sent or received by a model.

Get all users referred by this user:

$user = User::find(1);
$referralsSent = $user->referralsSent;

foreach ($referralsSent as $referral) {
    // Access the referred model instance
    $referredModel = $referral->referred;
}

Get the user who referred this user:

$user = User::find(2);
$referralsReceived = $user->referralsReceived;

foreach ($referralsReceived as $referral) {
    // Access the referrer model instance
    $referrerModel = $referral->referrer;
}

Models Overview

• Referral: Represents a referral record. It uses polymorphic relations (referrer_id, referrer_type, referred_id, referred_type) to link two models together.
• ReferralCode: Stores the unique referral codes generated by the referrers.

Testing

Run tests using PHPUnit.

vendor/bin/phpunit

License

This project is licensed under the MIT license.