- added facade

- added more tests - code rework - added config - added more helper-functions
toni-suarez · Jun 21, 2024 · 809ffee · 809ffee
1 parent 3d30d73
commit 809ffee
Show file tree

Hide file tree

Showing 9 changed files with 732 additions and 98 deletions.
diff --git a/README.md b/README.md
@@ -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.
 
@@ -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:
@@ -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
@@ -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

diff --git a/composer.json b/composer.json
@@ -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",
@@ -44,7 +51,10 @@
         "laravel": {
             "providers": [
                 "Suarez\\UtmParameter\\Providers\\UtmParameterServiceProvider"
-            ]
+            ],
+            "aliases": {
+                "UtmParameter": "Suarez\\UtmParameter\\Facades\\UtmParameter"
+            }
         }
     },
     "minimum-stability": "stable",

diff --git a/src/Facades/UtmParameter.php b/src/Facades/UtmParameter.php
@@ -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;
+    }
+}
diff --git a/src/Middleware/UtmParameters.php b/src/Middleware/UtmParameters.php
@@ -4,7 +4,7 @@
 
 use Closure;
 use Illuminate\Http\Request;
-use Suarez\UtmParameter\UtmParameter;
+use Suarez\UtmParameter\Facades\UtmParameter;
 
 class UtmParameters
 {
@@ -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);
@@ -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)
     {

diff --git a/src/Providers/UtmParameterServiceProvider.php b/src/Providers/UtmParameterServiceProvider.php
@@ -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');
     }
 
     /**
@@ -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);
     }
 }