Installation Guide

Before you begin

To integrate the Laravel UTM-Parameters package into your project, you'll need:

• A Laravel project (version 11.x or later is assumed for bootstrap/app.php structure).
• Composer installed globally on your system.

Install and configure

Get the package up and running in your Laravel project with these steps:

1. Add the package with Composer

Open your terminal, navigate to your Laravel project's root directory, and run the following Composer command:

composer require suarez/laravel-utm-parameter

This command downloads the package and adds it to your project's dependencies.

2. Register the middleware (for all web routes)

To automatically capture UTM parameters for all incoming web requests, register the UtmParameters middleware within the web middleware group.

Open your bootstrap/app.php file and modify the withMiddleware section:

// bootstrap/app.php

use Suarez\UtmParameter\Middleware\UtmParameters; // Make sure this import is present at the top of the file

return Application::configure(basePath: dirname(__DIR__))
    // ... other configurations ...
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->web(append: [
            UtmParameters::class, // Add this line to process UTMs on all web routes
            // ... any other existing web middleware ...
        ]);

        // ... other middleware configurations (aliases, global, etc.) ...
    })
    // ... other configurations ...
    ->create();

3. (Optional) Configure for specific routes using an alias

If you prefer to apply UTM parameter processing only to certain routes or route groups (instead of globally as in Step 2), or if you want a convenient alias even if it's registered globally, you can define a route middleware alias.

First, add the alias in bootstrap/app.php. If you're only using it for specific routes, you would skip adding UtmParameters::class to the web group in Step 2.

// bootstrap/app.php

use Suarez\UtmParameter\Middleware\UtmParameters; // Ensure this import is present

return Application::configure(basePath: dirname(__DIR__))
    // ... other configurations ...
    ->withMiddleware(function (Middleware $middleware) {
        // If you registered it globally in Step 2, that's fine.
        // $middleware->web(append: [UtmParameters::class, ...]);

        $middleware->alias([
            'utm.capture' => UtmParameters::class, // Define your alias
            // ... any other existing aliases ...
        ]);
    })
    // ... other configurations ...
    ->create();

Once the alias is defined, you can apply it to specific routes or route groups in your routes/web.php file:

// routes/web.php

use App\Http\Controllers\LandingPageController;

// Example: Apply to a single route
Route::get('my-special-landing-page/{slug}', [LandingPageController::class, 'show'])
    ->middleware('utm.capture');

// Example: Apply to a route group
Route::middleware(['utm.capture'])->group(function () {
    Route::get('another-page', [AnotherController::class, 'index']);
    // ... other routes in this group ...
});

Using the captured UTM parameters

After installation and middleware setup, the package automatically captures standard UTM parameters (like utm_source, utm_medium, utm_campaign, utm_term, and utm_content) from the request URL and stores them in the session.

You can typically access these parameters in your controllers, services, or even Blade views using Laravel's session() helper:

// Example in a Controller
public function show(Request $request)
{
    $utmSource = session('utm_source');
    $allUtmParameters = session('utm_parameters'); // Gets all captured UTMs as an array

    if ($utmSource) {
        // Your logic here, e.g., log it, store it with user data, etc.
    }

    // ...
}

For more detailed examples on retrieving specific parameters, handling edge cases, or understanding the session keys used, refer to the official package documentation.

Summary

You've now successfully installed and configured the Laravel UTM-Parameters package. Your application is equipped to capture UTM parameters from incoming URLs, making this valuable tracking data accessible for your analytics, reporting, or custom application logic. Always consult the package's documentation for the most current and advanced usage patterns.