https://github.com/toni-suarez/laravel-utm-parameter
A lightweight way to handle UTM parameters session-based in your Laravel Application.
https://github.com/toni-suarez/laravel-utm-parameter
laravel php social-media utm-parameters
Last synced: 5 months ago
JSON representation
A lightweight way to handle UTM parameters session-based in your Laravel Application.
- Host: GitHub
- URL: https://github.com/toni-suarez/laravel-utm-parameter
- Owner: toni-suarez
- License: mit
- Created: 2022-01-15T17:35:44.000Z (over 4 years ago)
- Default Branch: 12.x
- Last Pushed: 2025-02-25T17:00:16.000Z (over 1 year ago)
- Last Synced: 2025-12-13T03:58:48.436Z (7 months ago)
- Topics: laravel, php, social-media, utm-parameters
- Language: PHP
- Homepage:
- Size: 94.7 KB
- Stars: 15
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Laravel UTM-Parameters
[](https://packagist.org/packages/suarez/laravel-utm-parameter)
[](https://github.styleci.io/repos/448347178?branch=main)
[](https://github.com/toni-suarez/laravel-utm-parameter/actions/workflows/tests-php8.yml)
[](https://packagist.org/packages/suarez/laravel-utm-parameter)
[&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.
```blade
@hasUtm('source', 'newsletter')
Special Content for Newsletter-Subscriber.
@endhasUtm
```
---
## Installation
Follow these steps to install the Laravel UTM-Parameters package. [Guide for Laravel 10 and below.](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Installation-Guide-(Laravel-8.x-to-10.x))
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 Configuration
Once the package is installed, you can add the UtmParameters middleware to your Laravel application. Open the `bootstrap/app.php` file and append the `UtmParameters::class` inside the web-group.
```php
# Laravel 11+
return Application::configure(basePath: dirname(__DIR__))
...
->withMiddleware(function (Middleware $middleware) {
$middleware->web(append: [
Suarez\UtmParameter\Middleware\UtmParameters::class,
/* ... keep the existing middleware here */
]);
})
...
```
Also, take a look at how to set an [alias for the middleware](https://github.com/toni-suarez/laravel-utm-parameter/wiki/Installation-Guide#step-3-alias-configuration-optional).
### 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
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
### get_all_utm()
To get an array of all UTM parameters, use this helper: `get_all_utm()`.
```php
$parameter = get_all_utm();
```
### get_utm()
If you need to retrieve certain UTM parameters, use `get_utm('source|medium|campaign|term|content')`.
```blade
You came from {{ get_utm('source') }}
```
```php
// Some Task in your Class
public function someTask()
{
return match(get_utm('source')) {
'bing' => Bing::class,
'google' => Google::class,
'duckduckgo' => DuckDuckGo::class,
'newsletter' => Newsletter::class,
default => Default::class
};
}
// Render a view based on an utm_source
Route::get('/', function () {
return match(get_utm('source')) {
'newsletter' => view('newsletter'),
default => view('welcome')
};
});
```
### has_utm()
Sometimes you want to show or do something, if user might have some or specific utm-parameters.
Simply use:
- `has_utm('source|medium|campaign|term|content', 'optional-value')`
- `has_not_utm('source|medium|campaign|term|content', 'optional-value')`
```blade
@hasUtm('source', 'corporate-partner')
Some corporate partner related stuff
@endhasUtm
@hasNotUtm('term')
You have any term.
@endhasNotUtm
```
```php
if (has_utm('campaign', 'special-sale')) {
redirect('to/special-sale/page');
}
if (has_not_utm('campaign', 'newsletter')) {
session()->flash('Did you know, we have a newsletter?');
}
```
### 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')
Some Weekly related stuff
@endhasUtm
@containsNotUtm('campaign', 'sales')
Some not Sales stuff
@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
isMethod('GET') || $request->isMethod('POST');
}
}
```
Finally, update your `bootstrap/app.php` to use the CustomMiddleware:
```php
# bootstrap/app.php
use App\Http\Middleware\CustomMiddleware;
->withMiddleware(function (Middleware $middleware) {
$middleware->web(append: [
CustomMiddleware::class,
// other middleware...
]);
})
```
## 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
The Laravel UTM-Parameters package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).