Coverage index

src/Service/CampaignService.php

Lines: 82.84%

LineHitsSource
1
<?php
2
3
declare(strict_types=1);
4
5
namespace Drupal\visitors\Service;
6
7
use Drupal\visitors\VisitorsCampaignInterface;
8
9
/**
10
 * Campaign service for parsing marketing campaign parameters.
11
 *
12
 * Accepts a query string or a landing URL. Campaign name and keyword follow
13
 * Matomo's parameter order. The name is taken from the query before the
14
 * fragment.
15
 */
16
class CampaignService implements VisitorsCampaignInterface {
17
18
  /**
19
   * Campaign name parameters, in Matomo's order.
20
   *
21
   * Source and medium count as the name when no earlier name is present.
22
   */
23
  private const NAME_PARAMETERS = [
24
    'pk_cpn',
25
    'pk_campaign',
26
    'piwik_campaign',
27
    'mtm_campaign',
28
    'matomo_campaign',
29
    'utm_campaign',
30
    'utm_source',
31
    'utm_medium',
32
    '_rcn',
33
  ];
34
35
  /**
36
   * Campaign keyword parameters.
37
   *
38
   * The legacy mtm_keyword parameter stays ahead of mtm_kwd.
39
   */
40
  private const KEYWORD_PARAMETERS = [
41
    'pk_kwd',
42
    'pk_keyword',
43
    'piwik_kwd',
44
    'mtm_keyword',
45
    'mtm_kwd',
46
    'matomo_kwd',
47
    'utm_term',
48
    '_rck',
49
  ];
50
51
  /**
52
   * {@inheritdoc}
53
   */
54
  public function parse(?string $query): ?array {
5518
    if ($query === NULL || $query === '') {
562
      return NULL;
57
    }
58
5916
    $params = $this->parameters($query);
6016
    if ($params === []) {
619
      return NULL;
62
    }
63
6416
    $campaign_data = [];
650
    $dimensions = [
660
      'mtm_source'    => 'source',
670
      'pk_source'     => 'source',
680
      'utm_source'    => 'source',
690
      'mtm_medium'    => 'medium',
700
      'pk_medium'     => 'medium',
710
      'utm_medium'    => 'medium',
720
      'mtm_content'   => 'content',
730
      'pk_content'    => 'content',
740
      'utm_content'   => 'content',
750
      'mtm_cid'       => 'campaign_id',
760
      'pk_cid'        => 'campaign_id',
770
      'utm_id'        => 'campaign_id',
780
      'mtm_group'     => 'group',
790
      'pk_group'      => 'group',
800
      'mtm_placement' => 'placement',
810
      'pk_placement'  => 'placement',
820
    ];
8316
    foreach ($dimensions as $param => $key) {
8416
      $value = $this->scalarValue($params, $param);
8516
      if ($value !== NULL && !isset($campaign_data[$key])) {
8610
        $campaign_data[$key] = $value;
87
      }
88
    }
89
9016
    $name = $this->firstValue($params, self::NAME_PARAMETERS);
9116
    if ($name !== NULL) {
9213
      $campaign_data['campaign'] = $name;
93
    }
9416
    $keyword = $this->firstValue($params, self::KEYWORD_PARAMETERS);
9516
    if ($keyword !== NULL) {
967
      $campaign_data['keyword'] = $keyword;
97
    }
98
9916
    return $campaign_data === [] ? NULL : $campaign_data;
100
  }
101
102
  /**
103
   * {@inheritdoc}
104
   */
105
  public function build(string $url, array $parameters): string {
1066
    $url = trim($url);
1076
    if (!str_starts_with($url, 'http')) {
1081
      $url = 'https://' . $url;
109
    }
110
1116
    $fragment = '';
1126
    $hash_pos = strpos($url, '#');
1136
    if ($hash_pos !== FALSE) {
1141
      $fragment = substr($url, $hash_pos);
1151
      $url = substr($url, 0, $hash_pos);
116
    }
117
118
    // A host with no path gets a trailing slash, matching Matomo.
1196
    if (strpos($url, '/', 10) === FALSE && strpos($url, '?') === FALSE) {
1201
      $url .= '/';
121
    }
122
1236
    $campaign = trim((string) ($parameters['campaign'] ?? ''));
1246
    $query = 'mtm_campaign=' . rawurlencode($campaign);
125
1260
    $optional = [
1270
      'keyword' => 'mtm_kwd',
1280
      'source' => 'mtm_source',
1290
      'medium' => 'mtm_medium',
1300
      'content' => 'mtm_content',
1310
      'campaign_id' => 'mtm_cid',
1320
      'group' => 'mtm_group',
1330
      'placement' => 'mtm_placement',
1340
    ];
1356
    foreach ($optional as $key => $param) {
1366
      $value = trim((string) ($parameters[$key] ?? ''));
1376
      if ($value !== '') {
1382
        $query .= '&' . $param . '=' . rawurlencode($value);
139
      }
140
    }
141
1426
    $separator = strpos($url, '?') !== FALSE ? '&' : '?';
1436
    return $url . $separator . $query . $fragment;
144
  }
145
146
  /**
147
   * {@inheritdoc}
148
   */
149
  public function strip(string $url): string {
15011
    if ($url === '' || (!str_contains($url, '?') && !str_contains($url, '#'))) {
1519
      return $url;
152
    }
153
1544
    $parts = parse_url($url);
1554
    if (!is_array($parts)) {
1560
      return $url;
157
    }
158
1594
    $remove = array_fill_keys($this->urlParameterNames(), TRUE);
1604
    $changed = FALSE;
1614
    if (isset($parts['query'])) {
1624
      $params = [];
1634
      parse_str($parts['query'], $params);
1644
      if ($this->hasCampaignParameter($params, $remove)) {
1651
        $changed = TRUE;
1661
        $query = $this->withoutCampaignParameters($params, $remove);
1671
        if ($query === '') {
1680
          unset($parts['query']);
169
        }
170
        else {
1711
          $parts['query'] = $query;
172
        }
173
      }
174
    }
1754
    if (isset($parts['fragment']) && str_contains($parts['fragment'], '=')) {
1762
      $params = [];
1772
      parse_str($parts['fragment'], $params);
1782
      if ($this->hasCampaignParameter($params, $remove)) {
1792
        $changed = TRUE;
1802
        $fragment = $this->withoutCampaignParameters($params, $remove);
1812
        if ($fragment === '') {
1821
          unset($parts['fragment']);
183
        }
184
        else {
1851
          $parts['fragment'] = $fragment;
186
        }
187
      }
188
    }
1894
    if (!$changed) {
1904
      return $url;
191
    }
192
1932
    return $this->assembleUrl($parts);
194
  }
195
196
  /**
197
   * Reads query and fragment parameters from a query string or URL.
198
   *
199
   * @param string $value
200
   *   A query string or an absolute URL.
201
   *
202
   * @return array
203
   *   Decoded parameters. Query values win over the fragment.
204
   */
205
  protected function parameters(string $value): array {
20616
    $query = $value;
20716
    $fragment = '';
20816
    if (str_contains($value, '://') || str_starts_with($value, '?')) {
20911
      $parts = parse_url($value);
21011
      if (is_array($parts)) {
21111
        $query = $parts['query'] ?? '';
21211
        $fragment = $parts['fragment'] ?? '';
213
      }
214
    }
215
21616
    $params = [];
21716
    if ($query !== '') {
21815
      parse_str($query, $params);
219
    }
22016
    if ($fragment !== '' && str_contains($fragment, '=')) {
2211
      $fragment_params = [];
2221
      parse_str($fragment, $fragment_params);
2231
      foreach ($fragment_params as $key => $item) {
2241
        if (!isset($params[$key]) || $params[$key] === '') {
2251
          $params[$key] = $item;
226
        }
227
      }
228
    }
229
23016
    return $params;
231
  }
232
233
  /**
234
   * Returns the first non-empty parameter.
235
   *
236
   * @param array $params
237
   *   Decoded parameters.
238
   * @param string[] $keys
239
   *   Parameter names, highest priority first.
240
   *
241
   * @return string|null
242
   *   The trimmed value, or NULL when every key is empty.
243
   */
244
  protected function firstValue(array $params, array $keys): ?string {
24516
    foreach ($keys as $key) {
24616
      $value = $this->scalarValue($params, $key);
24716
      if ($value !== NULL) {
24813
        return $value;
249
      }
250
    }
2519
    return NULL;
252
  }
253
254
  /**
255
   * Returns a trimmed string parameter.
256
   *
257
   * @param array $params
258
   *   Decoded parameters.
259
   * @param string $key
260
   *   The parameter name.
261
   *
262
   * @return string|null
263
   *   The trimmed value, or NULL when it is missing or not a string.
264
   */
265
  protected function scalarValue(array $params, string $key): ?string {
26616
    $value = $params[$key] ?? NULL;
26716
    if (!is_string($value)) {
26816
      return NULL;
269
    }
27015
    $value = trim($value);
27115
    return $value === '' ? NULL : $value;
272
  }
273
274
  /**
275
   * Campaign parameters removed from a stored page URL.
276
   *
277
   * @return string[]
278
   *   Parameter names, including name, keyword, and dimension aliases.
279
   */
280
  protected function urlParameterNames(): array {
2814
    return [
2824
      'pk_cpn',
2834
      'pk_campaign',
2844
      'piwik_campaign',
2854
      'mtm_campaign',
2864
      'mtm_cpn',
2874
      'matomo_campaign',
2884
      'utm_campaign',
2894
      'utm_source',
2904
      'utm_medium',
2914
      'pk_kwd',
2924
      'pk_keyword',
2934
      'piwik_kwd',
2944
      'mtm_keyword',
2954
      'mtm_kwd',
2964
      'matomo_kwd',
2974
      'utm_term',
2984
      'mtm_source',
2994
      'pk_source',
3004
      'mtm_content',
3014
      'pk_content',
3024
      'utm_content',
3034
      'mtm_cid',
3044
      'pk_cid',
3054
      'utm_id',
3064
      'mtm_clid',
3074
      'mtm_group',
3084
      'pk_group',
3094
      'mtm_placement',
3104
      'pk_placement',
3114
      'pk_medium',
3124
    ];
313
  }
314
315
  /**
316
   * Whether the parameters include a campaign key.
317
   *
318
   * @param array $params
319
   *   Decoded parameters.
320
   * @param array<string, bool> $remove
321
   *   Parameter names that belong to a campaign.
322
   *
323
   * @return bool
324
   *   TRUE when one of those names is present.
325
   */
326
  protected function hasCampaignParameter(array $params, array $remove): bool {
3274
    foreach (array_keys($params) as $key) {
3284
      if (isset($remove[$key])) {
3292
        return TRUE;
330
      }
331
    }
3324
    return FALSE;
333
  }
334
335
  /**
336
   * Drops campaign parameters from a parsed query or fragment.
337
   *
338
   * @param array $params
339
   *   Decoded parameters.
340
   * @param array<string, bool> $remove
341
   *   Parameter names to drop.
342
   *
343
   * @return string
344
   *   The remaining parameters as a query string, or an empty string.
345
   */
346
  protected function withoutCampaignParameters(array $params, array $remove): string {
3472
    foreach (array_keys($params) as $key) {
3482
      if (isset($remove[$key])) {
3492
        unset($params[$key]);
350
      }
351
    }
3522
    return $params === [] ? '' : http_build_query($params);
353
  }
354
355
  /**
356
   * Rebuilds a URL from parse_url() parts.
357
   *
358
   * @param array $parts
359
   *   Parts returned by parse_url().
360
   *
361
   * @return string
362
   *   The assembled URL.
363
   */
364
  protected function assembleUrl(array $parts): string {
3652
    $scheme = isset($parts['scheme']) ? $parts['scheme'] . '://' : '';
3662
    $user = $parts['user'] ?? '';
3672
    $pass = isset($parts['pass']) ? ':' . $parts['pass'] : '';
3682
    $auth = $user !== '' ? $user . $pass . '@' : '';
3692
    $host = $parts['host'] ?? '';
3702
    $port = isset($parts['port']) ? ':' . $parts['port'] : '';
3712
    $path = $parts['path'] ?? '';
3722
    $query = isset($parts['query']) && $parts['query'] !== ''
3731
      ? '?' . $parts['query']
3741
      : '';
3752
    $fragment = isset($parts['fragment']) ? '#' . $parts['fragment'] : '';
376
3772
    return $scheme . $auth . $host . $port . $path . $query . $fragment;
378
  }
379
380
}