Download the PHP package pdazcom/laravel-referrals without Composer

Simple Referrals system for Laravel

A simple system of referrals with the ability to assign different programs for different users.

This package was created based on the lesson author is Damir Miladinov, with some minor changes, for which I express my gratitude to him.

• Installation
• Documentation Map
• Configuration Reference
• Quickstart
• How It Works
• Sharing and Entry Flows
• Reward Hooks
• Manual Integration Flow
• Bonus

Installation

These steps are verified against a fresh Laravel 11, Laravel 12, and Laravel 13 application.

1. Install the package

Laravel registers the service provider automatically through package discovery.

2. Publish the config file

This creates config/referrals.php, where you register your referral program classes.

If you prefer the package command, you can run:

3. Run the migrations

The package loads its migrations automatically for the default setup, so you do not need to publish them unless you want to customize the migration files before running them.

If you need to customize the migrations, publish them first:

Or use the package command:

4. Register the middleware

In Laravel 11 and 12, append the middleware to the web stack in bootstrap/app.php:

This middleware stores referral links in cookies so they can be attached when the user signs up.

It accepts both legacy UUID links and human-friendly referral codes in the same ?ref= query parameter. For the recommended sharing patterns, see Sharing and Entry Flows.

5. Add the trait to your user model

Add Pdazcom\Referrals\Traits\ReferralsMember to app/Models/User.php:

Upgrade notes for older docs

• If you are upgrading from older README instructions, do not edit app/Http/Kernel.php in Laravel 11 or 12. Middleware registration moved to bootstrap/app.php.
• You only need to publish the package migrations if you want to edit them before running php artisan migrate.

Note

Starting from v2.0, several referral programs can be applied to the same user. They are stored in cookies as a JSON object, and the request instance exposes them in the _referrals property:

ref_id_n is the referral link ID, and expires_timestamp is the cookie expiration timestamp. Expired links are deleted automatically.

Next: continue with the quickstart to create your first referral program and verify the reward flow.

Documentation Map

Use the shortest guide that matches the task you are working on:

Configuration Reference

The package configuration file is config/referrals.php:

Keys

programs

Use programs to register each referral program name with the class that should run when ReferralCase is dispatched.

• The array key must match the name value stored in referral_programs.
• The class should implement package program behavior (typically by extending Pdazcom\Referrals\Programs\AbstractProgram).
• If no mapping exists for a program name, no reward class is executed for that event.

Example (single program):

Example (multiple programs):

cookie_name

cookie_name defines the referral parameter your links use and the cookie key the middleware writes to.

• With the default value (ref), links look like: /register?ref=ABC123.
• If you set cookie_name to referral, links look like: /register?referral=ABC123.
• Existing links must use the same query parameter name as your configured cookie_name.

code_generator, code_length, and code_generation_max_attempts

Every new ReferralLink gets two codes:

• code: the legacy UUID used by $link->link
• referral_code: the human-friendly code used by $link->referral_link

The default generator is Pdazcom\Referrals\Generators\RandomStringCodeGenerator, which:

• generates uppercase alphanumeric codes
• avoids visually ambiguous characters such as 0, O, I, and 1
• uses code_length to determine the generated code size
• retries until the code is unique across both the legacy code column and the new referral_code column

If you want custom code generation rules, bind a class that implements Pdazcom\Referrals\Contracts\ReferralCodeGeneratorInterface:

Use code_generation_max_attempts to cap the retry loop if your code space is small or highly constrained.

prevent_duplicate_rewards

Enable this guard when a referred user should only produce one payout for a given referral relationship:

Behavior:

• RewardUser locks the matching referral_relationships row inside a transaction
• the first successful payout stamps rewarded_at
• later ReferralCase events for the same relationship are skipped

Run the package migrations before enabling this guard so the rewarded_at column exists.

prevent_self_referral

Enable this guard if users must not attribute themselves with their own referral links:

Behavior:

• ReferUser compares the referred user ID with the referral link owner ID
• when they match, the relationship is skipped and a log entry is written
• when disabled, self-referrals behave the same as any other referral

Quickstart

This quickstart gives you a verified path from install to the first successful referral relationship and reward dispatch in a fresh Laravel 11 or 12 app.

1. Install the package

You do not need to publish the package migrations for the default setup. The package loads them automatically.

Checkpoint: php artisan about should show a Laravel Referrals section.

2. Register the middleware and trait

In Laravel 11 and 12, append the middleware in bootstrap/app.php:

Then add the trait to your app/Models/User.php model:

3. Add a reward handler

Create app/ReferralPrograms/QuickstartProgram.php:

Register it in config/referrals.php:

4. Create a referrer, program, and referral link

Checkpoint: the output includes a link_id, code, and url.

5. Dispatch the referral event for a new user

Checkpoint: relationship_exists is true.

6. Dispatch the reward event

Checkpoint: the log contains Quickstart reward triggered.

At this point the package is installed, the referral relationship is stored, and the reward handler is running. To wire this into your real registration flow, dispatch UserReferred::dispatch($request->input(StoreReferralCode::REFERRALS), $user) after signup as shown below.

If you want to support code sharing in chat, SMS, or native mobile flows, continue with Sharing and Entry Flows.

How It Works

The package is event-driven. This is the shortest path through the main objects:

Core models:

• ReferralProgram: defines the program name, target URI, and attribution lifetime
• ReferralLink: belongs to a user and program, stores both the legacy UUID code and human-friendly referral_code
• ReferralRelationship: records that a user was referred by a specific referral link and whether they have already been rewarded

Integration choices:

• use hooks when your app already fires Registered and a purchase or subscription event
• dispatch UserReferred and ReferralCase manually when you need explicit control
• use registerWithCode() when referral attribution happens through a typed code instead of a clicked link

Sharing and Entry Flows

Use this section to choose the referral flow that matches your product surface. The package now supports both shareable links and code-only attribution without breaking existing link-based integrations.

For a deeper guide with examples and verification steps, see docs/sharing-and-entry-flows.md.

Choose the right flow

Share a human-friendly link

Use referral_link when you want a readable URL for public sharing:

This is the recommended default for web, email, SMS, and messaging apps because the same code can also be shown separately for manual entry.

Accept manual code entry

Use registerWithCode() when the referred user enters a code directly instead of visiting a link. The method accepts either the human-friendly referral_code or the legacy UUID code.

registerWithCode() returns true when the code resolves to a referral link and false when the code is unknown, so you can decide whether to show validation feedback or continue without attribution.

Keep legacy links if you already use them

The original link attribute still returns a URL with the UUID-based code:

This keeps older integrations working. New user-facing sharing surfaces should prefer referral_link and referral_code.

Verify attribution

1. Create a referral link and note both $link->referral_link and $link->referral_code.
2. Visit the share URL and confirm the middleware redirects to a clean URL and stores the referral cookie.
3. Complete signup and confirm a referral_relationships row exists for the new user.
4. Repeat the same attribution using $user->registerWithCode($link->referral_code) and confirm you get the same relationship result.

Reward Hooks

Reward hooks let you trigger referral events automatically in response to standard application events, without adding manual event dispatch to every controller or service. All hooks are opt-in and disabled by default.

Signup hook

The signup hook listens to Illuminate\Auth\Events\Registered and automatically dispatches UserReferred for any referral link stored in the current request by the StoreReferralCode middleware.

Requirements:

• StoreReferralCode must be active on your registration route.
• Your registration flow must fire Illuminate\Auth\Events\Registered (Laravel's built-in RegisteredController and Fortify/Breeze do this automatically).

Enable in config/referrals.php:

When enabled, you no longer need to manually dispatch UserReferred in your registration controller. The hook handles it automatically as long as the referral cookie is present on the request.

First-purchase hook

The first-purchase hook listens to a configurable application event and dispatches ReferralCase for the configured programs. This is useful when you want to reward the referrer when a referred user makes their first purchase.

Enable and configure in config/referrals.php:

Options:

Example event:

With the config above, ReferralCase::dispatch(['welcome-bonus', 'first-purchase'], $event->user, $event->order) is dispatched automatically whenever OrderCreated fires.

Note: The hook dispatches ReferralCase every time the configured event fires. If you want to reward only on the first purchase, add a guard inside your program's reward() method (for example, check whether a reward has already been recorded for this user).

Backward compatibility

Enabling hooks does not change any existing behavior. Existing manual dispatches of UserReferred and ReferralCase continue to work. You can keep manual dispatches alongside hooks without double-rewarding as long as you are not dispatching the same event twice for the same user action.

Manual Integration Flow

Use this section when you do not want to enable hooks and prefer to dispatch package events yourself.

1. Dispatch UserReferred after signup

This consumes the referral IDs that StoreReferralCode placed on the request and creates ReferralRelationship records through the ReferUser listener.

If you collect a typed referral code instead of relying on the middleware cookie, call:

2. Create the referral program record

Then map the program name to your reward handler in config/referrals.php:

3. Implement the reward class

4. Create a referral link for the recruiting user

The created model exposes:

• $link->referral_link for human-friendly share URLs
• $link->referral_code for manual entry surfaces
• $link->link for legacy UUID-based URLs

5. Dispatch ReferralCase when the conversion happens

RewardUser will:

• resolve the matching ReferralProgram
• find the ReferralLink that attributed the referred user
• load the configured reward class from config('referrals.programs.<name>')
• call reward($rewardObject) on that class

Bonus Content

If you want to list all the users for a given Referral Link, simply use

Contributing

See CONTRIBUTING.md for local setup, how to run tests, and the pull request workflow.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Konstantin A.
• All Contributors

License

The MIT License (MIT). Please see License File for more information.