<?php
declare( strict_types=1 );
namespace Automattic\WooCommerce\Internal\StockNotifications\Utilities;
/**
* Helper for appending UTM campaign parameters to outgoing stock-notification email links.
*
* Centralizes the `utm_source` / `utm_medium` values so order attribution stays consistent
* across all three email types (verify, verified, back-in-stock).
*
* @internal
*/
class UtmHelper {
/**
* UTM source value used for all stock notification emails.
*/
public const UTM_SOURCE = 'back-in-stock-notifications';
/**
* Default UTM medium for stock notification emails.
*/
public const UTM_MEDIUM_EMAIL = 'email';
/**
* Append the standard email UTM parameters to a URL.
*
* @param string $url The URL to annotate.
* @param string $medium The UTM medium (defaults to `email`).
* @return string
*/
public static function add_email_utm_params( string $url, string $medium = self::UTM_MEDIUM_EMAIL ): string {
if ( empty( $url ) ) {
return $url;
}
// Defensive: lock down the medium to a safe URL-friendly slug, falling back to the default
// if sanitization strips everything. Prevents any future caller from piping user-controlled
// input into the outbound tracking URL.
$sanitized_medium = sanitize_key( $medium );
if ( '' === $sanitized_medium ) {
$sanitized_medium = self::UTM_MEDIUM_EMAIL;
}
return add_query_arg(
array(
'utm_source' => self::UTM_SOURCE,
'utm_medium' => $sanitized_medium,
),
$url
);
}
}