README

轻量级处理 Laravel 应用程序中基于会话的 UTM 参数的方式。

@hasUtm('source', 'newsletter')
  <p>Special Content for Newsletter-Subscriber.</p>
@endhasUtm

安装

按照以下步骤安装 Laravel UTM-Parameters 包。 Laravel 10 及以下版本的安装指南。

打开您的终端并导航到您的 Laravel 项目目录。然后，使用 Composer 安装此包

$ composer require suarez/laravel-utm-parameter

可选地，您可以使用以下命令发布此包的配置文件

php artisan vendor:publish --tag="utm-parameter"

中间件配置

安装完成后，您可以将 UtmParameters 中间件添加到您的 Laravel 应用程序中。打开 bootstrap/app.php 文件，在 web-group 中添加 UtmParameters::class。

# 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 */
    ]);
  })
  ...

另外，请参阅如何设置中间件的别名。

作为 Facade 使用

如果您不想将其作为中间件使用，可以直接在控制器或其他应用程序部分使用 UtmParameter Facade。一旦调用 boot($request)-方法，您可以在任何地方访问它。例如

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');
  }
}

配置

配置文件 config/utm-parameter.php 允许您控制 UTM 参数处理的行为。

<?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'
    ],
];

用法

get_all_utm()

要获取所有 UTM 参数的数组，请使用此辅助函数： get_all_utm()。

$parameter = get_all_utm();

get_utm()

如果您需要检索某些 UTM 参数，请使用 get_utm('source|medium|campaign|term|content')。

 <p>You came from {{ get_utm('source') }}</p>

// 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()

有时您想在用户可能具有某些或特定的 utm 参数时显示或执行某些操作。

只需使用

has_utm('source|medium|campaign|term|content', 'optional-value')
has_not_utm('source|medium|campaign|term|content', 'optional-value')

@hasUtm('source', 'corporate-partner')
  <div>Some corporate partner related stuff</div>
@endhasUtm

@hasNotUtm('term')
  <p>You have any term.</p>
@endhasNotUtm

 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()

您可以使用 contains 根据存在或不存在 UTM 参数的一部分来有条件地显示或执行操作。

只需使用

contains_utm('source|medium|campaign|term|content', 'value')
contains_not_utm('source|medium|campaign|term|content', 'value')

@containsUtm('campaign', 'weekly')
  <div>Some Weekly related stuff</div>
@endhasUtm

@containsNotUtm('campaign', 'sales')
  <p>Some not Sales stuff</p>
@endhasNotUtm

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

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

扩展中间件

您可以通过扩展中间件来自定义接受 UTM 参数的行为。例如，您可以覆盖 shouldAcceptUtmParameter 方法。

首先，使用 Artisan 创建一个新的中间件

php artisan make:middleware CustomMiddleware

然后，更新新的中间件以扩展 UtmParameters 并覆盖 shouldAcceptUtmParameter 方法

<?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');
    }
}

最后，更新您的 bootstrap/app.php 以使用 CustomMiddleware

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

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        CustomMiddleware::class,
        // other middleware...
    ]);
})

suarez / laravel-utm-parameter

维护者

详细信息