README

This small package allows you to detect and store the visitor referrer so that you can access it later.

A typical use case would be saving the referrer in a database when a visitor registers in your app.

The package is designed to be flexible regarding:

How you want to detect the referrer
How you want to store the referrer value

Installation

You can install the package via Composer:

composer require elegantly/laravel-referrer

Usage

Capturing the Visitor Referrer

First, publish the config file with:

php artisan vendor:publish --tag="referrer-config"

This is the content of the published config file:

return [
    /*
    |--------------------------------------------------------------------------
    | Referrer Sources
    |--------------------------------------------------------------------------
    |
    | These are the classes containing the logic to detect the visitor's referrer.
    | You can disable some of them or add as many as you want.
    | No matter how many sources you define, they will all be stored.
    |
    */
    'sources' => [
        \Elegantly\Referrer\Sources\UtmReferrerSource::class,
        \Elegantly\Referrer\Sources\RequestHeaderSource::class,
        \Elegantly\Referrer\Sources\GoogleClickIdSource::class,
        \Elegantly\Referrer\Sources\MetaClickIdSource::class,
        \Elegantly\Referrer\Sources\TikTokClickIdSource::class,
    ],

    /*
    |--------------------------------------------------------------------------
    | Referrer Drivers
    |--------------------------------------------------------------------------
    |
    | These are the classes containing the logic to store the visitor's referrer.
    | By default, they are all disabled. To enable a driver, add a "key" value.
    | You can also add your own driver if needed.
    | No matter how many drivers you define, they will all store the referrer sources.
    |
    */
    'drivers' => [
        // \Elegantly\Referrer\Drivers\ContextDriver::class => [
        //     'key' => 'referrer',
        // ],
        // \Elegantly\Referrer\Drivers\SessionDriver::class => [
        //     'key' => 'referrer',
        // ],
        // \Elegantly\Referrer\Drivers\CookieDriver::class => [
        //     'key' => Str::slug(env('APP_NAME', 'laravel'), '_').'referrer',
        //     /**
        //      * Lifetime in seconds
        //      */
        //     'lifetime' => 60 * 60 * 24 * 365,
        // ],
    ],
];

In the file, enable one or more drivers by setting a value for the key.

Next, add the CaptureReferrerMiddleware to your route:

Using Laravel v11:

use Elegantly\Referrer\CaptureReferrerMiddleware;

->withMiddleware(function (Middleware $middleware) {
     $middleware->append(CaptureReferrerMiddleware::class);
})

Using Laravel v10:

use Elegantly\Referrer\CaptureReferrerMiddleware;

namespace App\Http;

use Illuminate\Foundation\Http\Kernel as HttpKernel;

class Kernel extends HttpKernel
{
    protected $middlewareGroups = [
        'web' => [
            // ...
            \Elegantly\Referrer\CaptureReferrerMiddleware::class,
        ],
    ];
}

Retrieving the Visitor Referrer

You can retrieve the referrer sources using the facade:

\Elegantly\Referrer\Facades\Referrer::get(); // Merges all drivers together, with the first one having priority over the next ones
\Elegantly\Referrer\Facades\Referrer::getSourcesByDriver(); // Retrieves all driver values

Here is a full example inside a controller:

namespace App\Http\Controllers\Auth;

use App\Http\Controllers\Controller;
use App\Http\Requests\Auth\RegisterRequest;
use App\Models\User;
use Illuminate\Support\Facades\Auth;
use Elegantly\Referrer\Facades\Referrer;
use Elegantly\Referrer\Sources\UtmReferrerSource;

class RegisteredUserController extends Controller
{
    public function store(RegisterRequest $request)
    {
        $validated = $request->validated();

        $user = new User($validated);

        $user->referrer = Referrer::get()->get(UtmReferrerSource::class)->utm_source;

        $user->save();

        Auth::login($user);

        return redirect("/");
    }
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy for information on how to report security vulnerabilities.

Credits

License

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

elegantly / laravel-referrer

Maintainers

Details