Referral attribution cookie

Capture a ref code from the URL into a first-party cookie with a validated value and a 30 day window, then read it when the visitor signs up.

LaravelMiddlewarereferralcookieattributionaffiliate

Code

<?php

namespace App\Http\Middleware;

use App\Models\User;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Cookie;
use Symfony\Component\HttpFoundation\Response;

class CaptureReferral
{
    public function handle(Request $request, Closure $next): Response
    {
        $code = (string) $request->query('ref');

        // Strict shape first, then a database check, so junk never reaches the cookie.
        $valid = preg_match('/^[A-Za-z0-9]{6,12}$/', $code) === 1
            && User::where('referral_code', $code)->exists();

        $keepFirst = ! config('referrals.last_touch', false) && $request->cookie('ref');

        if ($valid && ! $keepFirst) {
            // 30 days, HttpOnly, Lax so it survives the click from another site.
            Cookie::queue(Cookie::make('ref', $code, 60 * 24 * 30, '/', null, $request->isSecure(), true, false, 'lax'));
        }

        return $next($request);
    }
}

<?php

namespace App\Support;

use App\Models\User;

final class ReferralAttribution
{
    /** The referring user's id for the current visitor, or null. $ownCode blocks self-referral. */
    public static function resolve(?string $ownCode = null): ?int
    {
        $code = (string) request()->cookie('ref');

        if ($code === '' || $code === $ownCode) {
            return null;
        }

        return User::where('referral_code', $code)->value('id');
    }
}

How it works

What it solves

A referral link is only useful if the code survives until the visitor signs up, often days later and on a different page. Reading ?ref= at registration time loses almost everyone. A first-party cookie bridges the gap, and a small helper makes the attribution rules explicit.

How it works

CaptureReferral runs on web requests. If the query string carries ref, it checks the shape with a strict pattern and confirms the code exists in the database, so junk values are never stored. Attribution policy is first touch by default: an existing valid cookie is kept, and a new code only replaces it when last_touch is switched on in config. The response gets a queued cookie that lasts 30 days, is HttpOnly, and uses SameSite=Lax.

Laravel encrypts cookies by default, which also stops visitors editing the code by hand.

ReferralAttribution::resolve is the read side. It returns the referrer's id from the cookie and refuses self-referral, which is the first abuse case you will meet. Call it in your registration action and store the result on the new user.

Adapting it

Rename the parameter, change the lifetime, or record a touch row for analytics before setting the cookie. For cross-domain programmes pass the code through the signup URL as well.

Pitfalls

Respect consent rules; a referral cookie may still need disclosure.
Register the middleware in the web group, not on API routes.

How to use it

Add referral_code (unique) to users and referred_by (nullable foreign key).
Append CaptureReferral::class to the web middleware group in bootstrap/app.php.
Optionally set config('referrals.last_touch') to true for last-touch attribution.
At registration: $user->referred_by = ReferralAttribution::resolve($user->referral_code);.
Test by visiting /?ref=ABC12345 and checking the ref cookie is set.

Licence: DEV3 Snippet Licence. Free to use, change and ship in personal and commercial projects. Attribution is appreciated, not required. Please do not redistribute snippets as a collection.

Related snippets

Laravel · MiddlewarePlan-limit gate middlewareRoute middleware that blocks a request when the team has used up its plan allowance for a named limit, with a clear upgrade response.planslimitsmiddleware

Laravel · MiddlewareHoneypot and time-trap middlewareBlock simple form bots with a hidden field and an encrypted render timestamp, rejecting submissions that are filled in too fast.spamhoneypotmiddleware

Laravel · MiddlewareEmbed loader with domain allowlistServe a widget script only to pages on approved domains, with wildcard subdomain matching and a frame-ancestors header to match.embedcorsallowlist

Laravel · DatabaseSplit an order per vendorGroup cart lines by vendor, create one sub-order each and share the order discount across them using integer largest-remainder allocation.marketplaceordersdiscount