README

UTM Parameters

Framework agnostic (PSR-7 compatible) UTM parameters helper, this tool will simplify working with UTM parameters.

Installation

composer require devlop/utm-parameters

Usage

Capturing incoming UTM parameters

The basic idea is to capture incoming UTM parameters from the query and store them in cookies for later use until needed.

Create a middleware (or similar) following this logic:

use Devlop\UtmParameters\UtmParameters;

// Capture incoming UTM parameters from the query
$utmParameters = UtmParameters::capture($request);

if ($utmParameters !== null) {
    // Remember the UTM parameters in cookies for 30 days
    $utmParameters->remember($response, 30);
}

Retrieving stored UTM parameters

Later when you need the stored UTM parameters (example, after a registration or a placed order) you can easiliy retrieve them.

use Devlop\UtmParameters\UtmParameters;

// Retrieve stored UTM parameters from cookies
$utmParameters = UtmParameters::retrieve($request);

if ($utmParameters !== null) {
    // do something with the UTM parameters
    // optionally forget the cookies
    $utmParameters->forget($response);
}

Available methods

The Devlop\UtmParameters\UtmParameters have the following methods available:

public function getSource() : string

Get the utm_source parameter.

public function getMedium() : ?string

Get the utm_medium parameter.

public function getCampaign() : ?string

Get the utm_campaign parameter.

public function getTerm() : ?string

Get the utm_term parameter.

public function getContent() : ?string

Get the utm_content parameter.

public function toArray() : array

Get all parameters as an array:

[
    "utm_source" => "github",
    "utm_medium" => "email",
    "utm_campaign" => "hackathon_2021",
    "utm_term" => null,
    "utm_content" => null,
]

Iterating

UtmParameters is iterable:

foreach ($utmParameters as $parameter => $value) {
    // ...
}

Constants

All parameter keys are available as constants on UtmParameters to avoid the need to hardcode any parameter keys in your code.

$parameters = $utmParameters->toArray();

$parameters[UtmParameters::SOURCE];
$parameters[UtmParameters::MEDIUM];
$parameters[UtmParameters::CAMPAIGN];
$parameters[UtmParameters::TERM];
$parameters[UtmParameters::CONTENT];

Supported requests / responses

When capturing / retrieving UTM parameters these requests are supported.

When remembering / forgetting UTM parameters these responses are supported.

Laravel

Cookies Facade

The easiest way to remember or forget stored UTM parameters in Laravel is to use the global cookie() helper method to get an instance of QueueingFactory to attach the cookies to the response.

Middleware

utm-parameters ships with a middleware for Laravel for you to use.

Add the middleware in app/Http/Kernel.php, the middleware will automatically capture any incoming UTM parameters and store them in cookies for 30 days.

namespace App\Http;

use Illuminate\Foundation\Http\Kernel as HttpKernel;

class Kernel extends HttpKernel
{
    /**
     * The application's route middleware groups.
     *
     * @var array
     */
    protected $middlewareGroups = [
        'web' => [
            // other configured middleware
            \Devlop\UtmParameters\Laravel\StoreUtmParametersInCookies::class,
        ],
    ];
}

devlop / utm-parameters

Maintainers

Details