<?php
/**
 * UTM tags for links in messages.
 *
 * @package Rahkar\WP
 */

declare( strict_types = 1 );

namespace Rahkar\WP\Notifications;

use Rahkar\WP\Support\Settings;

defined( 'ABSPATH' ) || exit;

/**
 * Adds the same UTM tags to every link a module sends, so analytics and the sales
 * dashboard can tell which message brought a visit or an order.
 *
 * The values are fixed on purpose and the admin can only switch the tags off
 * (Notifications → "UTM tags on links"). Free-text values drift — one store writes
 * `sabad`, another `Abandoned-Cart` — and every report that groups by campaign
 * breaks without an error. WooCommerce stores these tags on the order (Order
 * Attribution), which is how the dashboard credits an order to a message.
 *
 *     utm_source=rahkar  utm_medium=sms  utm_campaign=abandoned_cart  utm_content=reminder2
 */
final class Utm {

	public const SOURCE = 'rahkar';

	/**
	 * Tag a link, unless the store switched tags off.
	 *
	 * @param string $url      Link on this site.
	 * @param string $campaign Module slug, e.g. `abandoned_cart`.
	 * @param string $content  Step within the module, e.g. `reminder2`; empty to omit.
	 * @param string $medium   `sms` or `email`.
	 */
	public static function tag( string $url, string $campaign, string $content = '', string $medium = 'sms' ): string {
		if ( '' === $url || ! Settings::get( 'notifications.utm_links', true ) ) {
			return $url;
		}

		$args = [
			'utm_source'   => self::SOURCE,
			'utm_medium'   => sanitize_key( $medium ),
			'utm_campaign' => sanitize_key( $campaign ),
		];

		if ( '' !== $content ) {
			$args['utm_content'] = sanitize_key( $content );
		}

		return add_query_arg( $args, $url );
	}
}