README

A Laravel package for generating URLs with UTM parameters. Features a fluent API, presets, helpers, Blade directives, and full Laravel integration.

Features

• 🔗 Fluent API - Chainable methods for building URLs
• 📦 Presets - Pre-defined UTM configurations for common use cases
• 🛠 Helper Functions - Quick URL generation anywhere in your code
• 🎨 Blade Directives - Easy use in your views
• 🏷 Model Trait - Add UTM link generation to your Eloquent models
• ⚙️ Configurable - Customize everything via config file
• ✅ Fully Tested - Comprehensive test coverage
• 📱 Laravel 10, 11 & 12 - Support for latest Laravel versions

Installation

Install the package via Composer:

composer require samer-alshaer/laravel-utm-builder

Publish the configuration file:

php artisan vendor:publish --tag="utm-builder-config"

Configuration

Add these optional environment variables to your .env file:

UTM_BASE_URL=https://your-app.com
UTM_CLIENT_URL=https://your-client-site.com

Usage

Using the Fluent Builder

use Samer\UtmBuilder\UtmBuilder;

// Basic usage
$url = UtmBuilder::make()
    ->path('landing-page')
    ->source('google')
    ->medium('cpc')
    ->campaign('summer_sale')
    ->build();
// https://your-app.com/landing-page?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale

// Using presets
$url = UtmBuilder::make()
    ->path('signup')
    ->preset('newsletter')
    ->content('header_button')
    ->build();

// With additional parameters
$url = UtmBuilder::make()
    ->path('product/123')
    ->preset('email')
    ->ref('user', 456)
    ->param('discount', '20OFF')
    ->build();

Using the Facade

use Samer\UtmBuilder\Facades\Utm;

$url = Utm::make()
    ->path('checkout')
    ->preset('email')
    ->campaign('abandoned_cart')
    ->build();

Using Helper Functions

// Quick link with preset
$url = utm_link('page/path', 'email');

// Link with custom parameters
$url = utm_link('signup', 'newsletter', ['ref_id' => 123]);

// Client website URL
$url = utm_client('landing-page', 'facebook');

// Custom UTM parameters
$url = utm_url('https://example.com/page', [
    'utm_source' => 'partner',
    'utm_medium' => 'referral',
]);

In Blade Templates

{{-- Using directive --}}
<a href="@utm('signup', 'newsletter')">Sign Up</a>

{{-- Using client directive --}}
<a href="@utmClient('landing', 'facebook')">Visit Site</a>

{{-- Using helper --}}
<a href="{{ utm_link('page', 'email') }}">Click Here</a>

In Eloquent Models

use Samer\UtmBuilder\Traits\HasUtmLinks;

class Product extends Model
{
    use HasUtmLinks;

    public function getShareLink(): string
    {
        return $this->utmBuilder()
            ->path("product/{$this->slug}")
            ->preset('whatsapp')
            ->ref('product', $this->id)
            ->build();
    }

    // Or use the built-in method
    public function getLink(): string
    {
        return $this->toUtmLink('email', ['discount' => '10OFF']);
    }

    // Customize the path
    protected function getUtmPath(): string
    {
        return "products/{$this->slug}";
    }
}

Available Methods

Presets

The package comes with several built-in presets:

// Email
'email', 'newsletter', 'transactional'

// SMS
'sms', 'sms_notification', 'sms_promotion'

// Social Media
'facebook', 'twitter', 'linkedin', 'instagram', 'whatsapp'

// Advertising
'google_ads', 'facebook_ads'

// Other
'referral', 'affiliate', 'internal', 'admin_panel'

Custom Presets

Add your own presets in config/utm-builder.php:

'presets' => [
    'booking_payment' => [
        'utm_source' => 'system',
        'utm_medium' => 'email',
        'utm_campaign' => 'booking_payment',
    ],

    'agent_registration' => [
        'utm_source' => 'admin_panel',
        'utm_medium' => 'referral',
        'utm_campaign' => 'agent_signup',
    ],
],

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email sameralshaer51@gmail.com instead of using the issue tracker.

Credits

• Samer
• All Contributors

License

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