- added facade

- added more tests - code rework - added config - added more helper-functions
toni-suarez · Jun 21, 2024 · 6f5d795 · 6f5d795
1 parent 73bbe90
commit 6f5d795
Show file tree

Hide file tree

Showing 10 changed files with 743 additions and 115 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.
 
@@ -16,39 +17,23 @@ 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
 ```
 
-### Middleware
+Optionally, you can publish the config file of this package with this command:
+```bash
+php artisan vendor:publish --tag="utm-parameter"
+```
 
-#### Laravel 8
+
+### Middleware
 
 Open the `app/Http/Kernel.php` file and add a new item to the `web` middleware group:
 
@@ -79,17 +64,98 @@ 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
+### 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')`.
 
@@ -119,7 +185,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.
 
@@ -147,6 +213,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
@@ -2,6 +2,13 @@
     "name": "suarez/laravel-utm-parameter",
     "description": "A little helper to store and handle utm-parameter",
     "homepage": "https://github.com/toni-suarez/laravel-utm-parameter",
+    "keywords": [
+        "php",
+        "laravel",
+        "utm-parameter",
+        "social-media",
+        "utm"
+    ],
     "license": "MIT",
     "authors": [
         {
@@ -44,7 +51,10 @@
         "laravel": {
             "providers": [
                 "Suarez\\UtmParameter\\Providers\\UtmParameterServiceProvider"
-            ]
+            ],
+            "aliases": {
+                "UtmParameter": "Suarez\\UtmParameter\\Facades\\UtmParameter"
+            }
         }
     },
     "minimum-stability": "stable",

diff --git a/phpunit.xml b/phpunit.xml
@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" backupGlobals="false" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd" bootstrap="vendor/autoload.php" colors="true" processIsolation="false" stopOnFailure="false">
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" backupGlobals="false" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.0/phpunit.xsd" bootstrap="vendor/autoload.php" colors="true" processIsolation="false" stopOnFailure="false">
+  <coverage>
+    <include>
+      <directory suffix=".php">./src</directory>
+    </include>
+  </coverage>
   <testsuites>
     <testsuite name="Unit">
       <directory suffix="Test.php">./tests</directory>
     </testsuite>
   </testsuites>
-  <source>
-    <include>
-      <directory suffix=".php">./src</directory>
-    </include>
-  </source>
 </phpunit>
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)
     {