<?php
/**
 * Documentation URLs with UTM tracking for analytics.
 *
 * @package SHC4WC
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

class SHC4WC_Docs {
	const DEFAULT_BASE_URL = 'https://payments-connect-square.pages.dev';

	/**
	 * Public docs site base URL (no trailing slash).
	 *
	 * @return string
	 */
	public static function base_url() {
		if ( defined( 'SHC4WC_DOCS_BASE_URL' ) && filter_var( SHC4WC_DOCS_BASE_URL, FILTER_VALIDATE_URL ) ) {
			return untrailingslashit( SHC4WC_DOCS_BASE_URL );
		}
		return self::DEFAULT_BASE_URL;
	}

	/**
	 * Build a documentation URL with UTM parameters.
	 *
	 * @param string $path     Optional path after base (e.g. getting-started/).
	 * @param string $medium   utm_medium value.
	 * @param string $campaign utm_campaign value.
	 * @param string $source   utm_source value.
	 * @return string
	 */
	public static function url( $path = '', $medium = 'plugin_page', $campaign = 'documentation', $source = 'wordpress_org' ) {
		$base = self::base_url();
		if ( '' !== $path ) {
			$base = trailingslashit( $base ) . ltrim( $path, '/' );
		}

		return add_query_arg(
			array(
				'utm_source'   => $source,
				'utm_medium'   => $medium,
				'utm_campaign' => $campaign,
			),
			$base
		);
	}

	/**
	 * Docs link from wp-admin (distinct utm_medium for GA4).
	 *
	 * @param string $path     Optional doc path.
	 * @param string $campaign Optional campaign slug.
	 * @return string
	 */
	public static function admin_url( $path = '', $campaign = 'documentation' ) {
		return self::url( $path, 'wp_admin', $campaign );
	}

	/**
	 * Docs link for WordPress.org readme / plugin directory.
	 *
	 * @param string $path Optional doc path.
	 * @return string
	 */
	public static function readme_url( $path = '', $campaign = 'documentation' ) {
		return self::url( $path, 'readme', $campaign );
	}
}
