Skip to content

Commit

Permalink
- added facade
Browse files Browse the repository at this point in the history
- added more tests
- code rework
- added config
- added more helper-functions
  • Loading branch information
toni-suarez committed Jun 21, 2024
1 parent 3d30d73 commit 809ffee
Show file tree
Hide file tree
Showing 9 changed files with 732 additions and 98 deletions.
208 changes: 189 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
# Laravel UTM-Parameters

[![Latest Version on Packagist](https://img.shields.io/packagist/v/suarez/laravel-utm-parameter.svg?style=flat-square)](https://packagist.org/packages/suarez/laravel-utm-parameter)
[![StyleCI](https://github.styleci.io/repos/448347178/shield?branch=main)](https://github.styleci.io/repos/448347178?branch=main)
[![Test PHP 8.x](https://github.com/toni-suarez/laravel-utm-parameter/actions/workflows/tests-php8.yml/badge.svg?branch=main)](https://github.com/toni-suarez/laravel-utm-parameter/actions/workflows/tests-php8.yml)
[![Packagist Downloads](https://img.shields.io/packagist/dt/suarez/laravel-utm-parameter)](https://packagist.org/packages/suarez/laravel-utm-parameter)
![GitHub](https://img.shields.io/github/license/toni-suarez/laravel-utm-parameter)

[![Statamic Addon](https://img.shields.io/badge/https%3A%2F%2Fstatamic.com%2Faddons%2Ftoni-suarez%2Futm-parameter?style=flat-square&logo=statamic&logoColor=rgb(255%2C%2038%2C%20158)&label=Statamic&link=https%3A%2F%2Fstatamic.com%2Faddons%2Ftoni-suarez%2Futm-parameter)](https://statamic.com/addons/toni-suarez/utm-parameter)

A lightweight way to handle UTM parameters session-based in your Laravel Application.

Expand All @@ -18,34 +19,25 @@ A lightweight way to handle UTM parameters session-based in your Laravel Applica

## Table of Content

- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [License](#license)

## Introduction

What are these UTM parameters? UTM is an acronym standing for "Urchin Tracking Module" and where initially introduced in Google Analytics. It's a way, mostly marketers track effectiveness of online marketing campaigns.

There are five different UTM parameters:
- utm_source
- utm_medium
- utm_campaign
- utm_content
- utm_term

Not all parameters are used everytime.
Here would be a common example: https://www.example.com/?utm_source=newsletter&utm_medium=email&utm_campaign=holiday-sale


## Installation

Install the `utm-parameter` package with composer:
Follow these steps to install the Laravel UTM-Parameters package.

```
Open your terminal and navigate to your Laravel project directory. Then, use Composer to install the package:

```bash
$ composer require suarez/laravel-utm-parameter
```

Optionally, you can publish the config file of this package with this command:
```bash
php artisan vendor:publish --tag="utm-parameter"
```

### Middleware

Open the `app/Http/Kernel.php` file and add a new item to the `web` middleware group:
Expand Down Expand Up @@ -77,6 +69,87 @@ Route::middleware('utm-parameters')
->get('langing-page/{slug}', 'LandingPageController@show');
```

### Use as Facade

If you prefer not to use it as middleware, you can utilize the UtmParameter Facade directly in your controllers or other parts of your application. Once the `boot($request)`-method is called, you have access to it at any place. For example:

```php
use Suarez\UtmParameter\Facades\UtmParameter;

// Inside a controller method
class IndexController {
public function index(Request $request)
{
UtmParameter::boot($request);
}
}

class SomeDifferentController {
public function index(Request $request)
{
$source = UtmParameter::get('source');
}
}
```

## Configuration

The configuration file `config/utm-parameter.php` allows you to control the behavior of the UTM parameters handling.

```php
<?php

return [
/*
* Control Overwriting UTM Parameters (default: false)
*
* This setting determines how UTM parameters are handled within a user's session.
*
* - Enabled (true): New UTM parameters will overwrite existing ones during the session.
* - Disabled (false): The initial UTM parameters will persist throughout the session.
*/
'override_utm_parameters' => false,

/*
* Session Key for UTM Parameters (default: 'utm')
*
* This key specifies the name used to access and store UTM parameters within the session data.
*
* If you're already using 'utm' for another purpose in your application,
* you can customize this key to avoid conflicts.
* Simply provide your preferred key name as a string value.
*/
'session_key' => 'utm',

/*
* Allowed UTM Parameters (default: ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'utm_campaign_id'])
*
* This setting defines the UTM parameters that are allowed within your application.
*
* In this array, you can specify a list of allowed UTM parameter names. Each parameter should be listed as a string.
* Only parameters from this list will be stored and processed in the session.
* and any parameter without the 'utm_' prefix will be ignored regardless of its inclusion in this list.
*
* Example: To only allow the basic UTM parameters (source, medium, and campaign), you could update the array like this:
*
* 'allowed_utm_parameters' => [
* 'utm_source',
* 'utm_medium',
* 'utm_campaign',
* ],
*/
'allowed_utm_parameters' => [
'utm_source',
'utm_medium',
'utm_campaign',
'utm_term',
'utm_content',
'utm_campaign_id'
],
];
```


## Usage

### All UTM parameters
Expand Down Expand Up @@ -145,6 +218,103 @@ Simply use:
}
```

### contains_utm()

You can conditionally show or perform actions based on the presence or absence of a portion of an UTM parameters using contains.

Simply use:
- `contains_utm('source|medium|campaign|term|content', 'value')`
- `contains_not_utm('source|medium|campaign|term|content', 'value')`

```blade
@containsUtm('campaign', 'weekly')
<div>Some Weekly related stuff</div>
@endhasUtm
@containsNotUtm('campaign', 'sales')
<p>Some not Sales stuff</p>
@endhasNotUtm
```

```php
if (contains_utm('campaign', 'weekly')) {
redirect('to/special/page');
}

if (contains_not_utm('campaign', 'sale')) {
session()->flash('Did you know, we have a newsletter?');
}
```

## Extending the Middleware

You can extend the middleware to customize the behavior of accepting UTM parameters. For example, you can override the `shouldAcceptUtmParameter` method.

First, create a new middleware using Artisan:

```bash
php artisan make:middleware CustomMiddleware
```

Then, update the new middleware to extend UtmParameters and override the `shouldAcceptUtmParameter` method:

```php
<?php

namespace App\Http\Middleware;

use Illuminate\Http\Request;
use Suarez\UtmParameter\Middleware\UtmParameters;

class CustomMiddleware extends UtmParameters
{
/**
* Determines whether the given request/response pair should accept UTM-Parameters.
*
* @param \Illuminate\Http\Request $request
*
* @return bool
*/
protected function shouldAcceptUtmParameter(Request $request)
{
return $request->isMethod('GET') || $request->isMethod('POST');
}
}
```

Finally, update your `app/Http/Kernel.php` to **replace** the `UtmParameters` with `CustomMiddleware`:

```php
# app/Http/Kernel.php
use App\Http\Middleware\CustomMiddleware;

protected $middlewareGroups = [
'web' => [
/* ... keep the existing middleware here */
CustomMiddleware::class,
],
];
```

## Resources
Explore additional use cases and resources on the [wiki pages](https://github.com/toni-suarez/laravel-utm-parameter/wiki)

- [Installation Guide](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Installation-Guide)
- [Installation Guide (Laravel 8.x to 10.x)](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Installation-Guide-(Laravel-8.x-to-10.x))
- [How it works](https://github.com/toni-suarez/laravel-utm-parameter/wiki/How-it-works)
- [Limitations](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Limitations)
- [Advanced Usage](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Advanced-Usage)
- [Blade Usage](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Blade-Usage)
- [Usage via Facade or Helper Class](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Usage-via-Facade-or-Helper-Class)

### Inspirations
- [Use Case: A/B Testing](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Use-Case:-A-B-Testing)
- [Use Case: Different Styles for Social Media](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Use-Case:-Different-Styles-for-Social-Media)
- [Use Case: Lead Attribution](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Use-Case:-Lead-Attribution)
- [Use Case: Social Media Tracking](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Use-Case:-Social-Media-Tracking)
- [Use‐Case: Newsletter Redirect on Product Detail Page](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Use%E2%80%90Case:-Newsletter-Redirect-on-Product-Detail-Page)
- [Use‐Case: Offline Marketing Integration](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Use%E2%80%90Case:-Offline-Marketing-Integration)

---

## License
Expand Down
12 changes: 11 additions & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,13 @@
"description": "A little helper to store and handle utm-parameter",
"homepage": "https://github.com/toni-suarez/laravel-utm-parameter",
"license": "MIT",
"keywords": [
"php",
"laravel",
"utm-parameter",
"social-media",
"utm"
],
"authors": [
{
"name": "Toni Suarez",
Expand Down Expand Up @@ -44,7 +51,10 @@
"laravel": {
"providers": [
"Suarez\\UtmParameter\\Providers\\UtmParameterServiceProvider"
]
],
"aliases": {
"UtmParameter": "Suarez\\UtmParameter\\Facades\\UtmParameter"
}
}
},
"minimum-stability": "stable",
Expand Down
26 changes: 26 additions & 0 deletions src/Facades/UtmParameter.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<?php

namespace Suarez\UtmParameter\Facades;

use Illuminate\Support\Facades\Facade;

/**
* @method static \Suarez\UtmParameter\UtmParameter boot(\Illuminate\Http\Request $request)
* @method static array useRequestOrSession(\Illuminate\Http\Request $request)
* @method static array all()
* @method static string|null get(string $key)
* @method static bool has(string $key, $value = null)
* @method static bool contains(string $key, string $value)
* @method static bool clear()
* @method static array getParameter(\Illuminate\Http\Request $request)
* @method static string ensureUtmPrefix(string $key)
*
* @see \Suarez\UtmParameter\UtmParameter
*/
class UtmParameter extends Facade
{
protected static function getFacadeAccessor()
{
return \Suarez\UtmParameter\UtmParameter::class;
}
}
9 changes: 4 additions & 5 deletions src/Middleware/UtmParameters.php
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

use Closure;
use Illuminate\Http\Request;
use Suarez\UtmParameter\UtmParameter;
use Suarez\UtmParameter\Facades\UtmParameter;

class UtmParameters
{
Expand All @@ -14,12 +14,12 @@ class UtmParameters
* @param \Illuminate\Http\Request $request
* @param \Closure $next
*
* @return mixed
* @return \Closure
*/
public function handle(Request $request, Closure $next)
{
if ($this->shouldAcceptUtmParameter($request)) {
app(UtmParameter::class)->boot(session('utm'));
UtmParameter::boot($request);
}

return $next($request);
Expand All @@ -29,9 +29,8 @@ public function handle(Request $request, Closure $next)
* Determines whether the given request/response pair should accept UTM-Parameters.
*
* @param \Illuminate\Http\Request $request
* @param \Illuminate\Http\Response $response
*
* @return \Illuminate\Http\Request
* @return bool
*/
protected function shouldAcceptUtmParameter(Request $request)
{
Expand Down
17 changes: 14 additions & 3 deletions src/Providers/UtmParameterServiceProvider.php
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,8 @@ class UtmParameterServiceProvider extends ServiceProvider
*/
public function register()
{
$this->app->singleton(UtmParameter::class, function () {
return new UtmParameter();
});
$this->app->singleton(UtmParameter::class, fn () => new UtmParameter());
$this->mergeConfigFrom(__DIR__.'/../config/utm-parameter.php', 'utm-parameter');
}

/**
Expand All @@ -27,12 +26,24 @@ public function register()
*/
public function boot()
{
$this->publishes([__DIR__.'/../config/utm-parameter.php' => config_path('utm-parameter.php')], 'utm-parameter');

Blade::if('hasUtm', function (string $key, string|null $value = null) {
return has_utm($key, $value);
});

Blade::if('hasNotUtm', function (string $key, string|null $value = null) {
return has_not_utm($key, $value);
});

Blade::if('containsUtm', function (string $key, string|null $value = null) {
return contains_utm($key, $value);
});

Blade::if('containsNotUtm', function (string $key, string|null $value = null) {
return contains_not_utm($key, $value);
});

AliasLoader::getInstance()->alias('UtmParameter', \Suarez\UtmParameter\Facades\UtmParameter::class);
}
}
Loading

0 comments on commit 809ffee

Please sign in to comment.