Merge branch 'main' into develop

# Conflicts: # .github/workflows/tests-php8.yml # README.md # composer.json
toni-suarez · Jun 20, 2024 · 4079cc7 · 4079cc7
2 parents 0c357d1 + e195132
commit 4079cc7
Show file tree

Hide file tree

Showing 9 changed files with 166 additions and 127 deletions.
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -0,0 +1 @@
+github: [toni-suarez]
diff --git a/.github/workflows/tests-php8.yml b/.github/workflows/tests-php8.yml
@@ -17,8 +17,8 @@ jobs:
 
     strategy:
       matrix:
-        laravel: ['10.*', '11.*']
-        php: [8.1, 8.2]
+        laravel: ['11.*']
+        php: [8.1, 8.2, 8.3]
         exclude:
           - laravel: '11.*'
             php: 8.1

diff --git a/README.md b/README.md
@@ -1,9 +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.
@@ -16,41 +18,19 @@ 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. [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
 ```
 
-### Middleware
-
-#### Laravel 11
+### Middleware Configuration
 
-Open the `bootstrap/app.php` file and append the `UtmParameters::class` inside the web-group
+Once the package is installed, you need to 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
@@ -65,7 +45,10 @@ return Application::configure(basePath: dirname(__DIR__))
   ...
 ```
 
-To enable UTM-Parameters only for certain requests to your site, add a new alias.
+### Middleware Alias (Optional)
+
+To enable UTM-Parameters only for certain requests or routes in your application, you can add an alias for the UtmParameters middleware. Open the bootstrap/app.php file and append the `UtmParameters::class` inside the web-group.
+
 
 ```php
 # Laravel 11
@@ -88,51 +71,20 @@ To apply UTM-Parameters to specific routes, use the following middleware: `utm-p
 
 ```php
 Route::middleware('utm-parameters')
-  ->get('langing-page/{slug}', 'LandingPageController@show');
-```
-
-#### Laravel 10
-
-Open the `app/Http/Kernel.php` file and add a new item to the `web` middleware group:
-
-```php
-# Laravel 10 and below
-protected $middlewareGroups = [
-    'web' => [
-        /* ... keep the existing middleware here */
-        \Suarez\UtmParameter\Middleware\UtmParameters::class,
-    ],
-];
-```
-
-To enable UTM-Parameters only for certain requests to your site, add a new mapping to the `middlewareAliases` Array.
-
-```php
-# Laravel 10 and below
-protected $middlewareAliases = [
-    /* ... keep the existing mappings here */
-    'utm-parameters' => \Suarez\UtmParameter\Middleware\UtmParameters::class,
-];
-```
-
-To apply UTM-Parameters to specific routes, use the following middleware: `utm-parameters`
-
-```php
-Route::middleware('utm-parameters')
-  ->get('langing-page/{slug}', 'LandingPageController@show');
+  ->get('landing-page/{slug}', 'LandingPageController@show');
 ```
 
 ## Usage
 
-### All UTM parameters
+### get_all_utm()
 
 To get an array of all UTM parameters, use this helper:  `get_all_utm()`.
 
 ```php
 $parameter = get_all_utm();
 ```
 
-###  Get UTM parameter
+###  get_utm()
 
 If you need to retrieve certain UTM parameters, use `get_utm('source|medium|campaign|term|content')`.
 
@@ -162,7 +114,7 @@ Route::get('/', function () {
 });
 ```
 
-### Has UTM parameter
+### has_utm()
 
 Sometimes you want to show or do something, if user might have some or specific utm-parameters.
 
@@ -190,6 +142,26 @@ Simply use:
  }
 ```
 
+
+## 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

diff --git a/composer.json b/composer.json
@@ -11,13 +11,13 @@
         }
     ],
     "require": {
-        "php": "^8.1|^8.2",
-        "illuminate/support": "^10.0|^11.0",
-        "illuminate/contracts": "^10.0|^11.0"
+        "php": "^8.2",
+        "illuminate/support": "^11.0",
+        "illuminate/contracts": "^11.0"
     },
     "require-dev": {
-        "nunomaduro/collision": "^7.0|^8.1",
-        "orchestra/testbench": "^7.0|^8.0|^9.0",
+        "nunomaduro/collision": "^8.1",
+        "orchestra/testbench": "^9.0",
         "phpunit/phpunit": "^9.5|^10.0",
         "friendsofphp/php-cs-fixer": "^3.0"
     },

diff --git a/src/Middleware/UtmParameters.php b/src/Middleware/UtmParameters.php
@@ -14,7 +14,7 @@ class UtmParameters
      * @param \Illuminate\Http\Request $request
      * @param \Closure                 $next
      *
-     * @return mixed
+     * @return \Closure
      */
     public function handle(Request $request, Closure $next)
     {
@@ -29,7 +29,6 @@ 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
      */

diff --git a/src/Providers/UtmParameterServiceProvider.php b/src/Providers/UtmParameterServiceProvider.php
@@ -15,9 +15,7 @@ class UtmParameterServiceProvider extends ServiceProvider
      */
     public function register()
     {
-        $this->app->singleton(UtmParameter::class, function () {
-            return new UtmParameter();
-        });
+        $this->app->singleton(UtmParameter::class, fn () => new UtmParameter());
     }
 
     /**

diff --git a/src/UtmParameter.php b/src/UtmParameter.php
@@ -11,11 +11,9 @@ class UtmParameter
      */
     public $parameters;
 
-    public function __construct($parameters = [])
+    public function __construct(array $parameters = [])
     {
-        $this->parameters = is_string($parameters)
-            ? json_decode($parameters, true)
-            : $parameters;
+        $this->parameters = $parameters;
     }
 
     /**
@@ -32,9 +30,7 @@ public function boot($parameters = null)
             session(['utm' => $parameters]);
         }
 
-        $this->parameters = is_string($parameters)
-            ? json_decode($parameters, true)
-            : $parameters;
+        $this->parameters = $parameters;
 
         return app(UtmParameter::class, $parameters);
     }
@@ -59,10 +55,7 @@ public static function all()
     public static function get($key)
     {
         $parameters = self::all();
-
-        if (strpos($key, 'utm_') === false) {
-            $key = 'utm_'.$key;
-        }
+        $key = self::ensureUtmPrefix($key);
 
         if (!array_key_exists($key, $parameters)) {
             return null;
@@ -82,10 +75,7 @@ public static function get($key)
     public static function has($key, $value = null)
     {
         $parameters = self::all();
-
-        if (strpos($key, 'utm_') === false) {
-            $key = 'utm_'.$key;
-        }
+        $key = self::ensureUtmPrefix($key);
 
         if (!array_key_exists($key, $parameters)) {
             return false;
@@ -98,6 +88,37 @@ public static function has($key, $value = null)
         return true;
     }
 
+    /**
+     * Determine if a value contains inside the key.
+     *
+     * @param string $key
+     * @param string $value
+     * @return bool
+     */
+    public static function contains($key, $value)
+    {
+        $parameters = self::all();
+        $key = self::ensureUtmPrefix($key);
+
+        if (!array_key_exists($key, $parameters) || !is_string($value)) {
+            return false;
+        }
+
+        return str_contains(self::get($key), $value);
+    }
+
+    /**
+     * Clear and remove utm session.
+     *
+     * @return bool
+     */
+    public static function clear()
+    {
+        app(UtmParameter::class)->parameters = null;
+        session()->forget('utm');
+        return true;
+    }
+
     /**
      * Retrieve all UTM-Parameter from the URI.
      *
@@ -110,4 +131,15 @@ protected static function getParameter()
             ->map(fn ($value) => htmlspecialchars($value, ENT_QUOTES, 'UTF-8'))
             ->toArray();
     }
+
+    /**
+     * Ensure the key to start with 'utm_'.
+     *
+     * @param string $key
+     * @return string
+     */
+    protected static function ensureUtmPrefix(string $key): string
+    {
+        return str_starts_with($key, 'utm_') ? $key : 'utm_' . $key;
+    }
 }
diff --git a/src/config/utm-parameter.php b/src/config/utm-parameter.php
@@ -0,0 +1,5 @@
+<?php
+
+return [
+  'override_utm_parameters' => false
+];