UTM Link Builder — PHP source

<?php
/**
 * utm-link-builder - campaign URL builder with canonical utm_* ordering.
 *
 * Display snippet: ports the core build($baseUrl, $params) from the
 * TypeScript lib (src/lib/utm.ts). The lint/bulk/preset helpers live in
 * the TypeScript/Go sources.
 *
 * Semantics: strip any stale utm_* params from the base URL, keep every
 * unrelated query param in place, then append the given params in
 * canonical order. Empty-string params are omitted. Returns null for an
 * unparseable base. Standard library only.
 */

const CANONICAL = [
    'source'   => 'utm_source',
    'medium'   => 'utm_medium',
    'campaign' => 'utm_campaign',
    'term'     => 'utm_term',
    'content'  => 'utm_content',
];

function build(string $baseUrl, array $params = []): ?string
{
    if (strpos($baseUrl, '://') === false) {
        $baseUrl = 'https://' . $baseUrl; // coerce a scheme-less host
    }
    $parts = parse_url($baseUrl);
    if ($parts === false || !isset($parts['host'])) {
        return null;
    }

    // Keep every unrelated query param; drop stale utm_* ones.
    $kept = [];
    foreach (explode('&', $parts['query'] ?? '') as $pair) {
        if ($pair === '') {
            continue;
        }
        $key = explode('=', $pair, 2)[0];
        if (strpos($key, 'utm_') !== 0) {
            $kept[] = $pair;
        }
    }

    foreach (CANONICAL as $field => $queryKey) {
        $value = $params[$field] ?? '';
        if ($value !== '') {
            $kept[] = $queryKey . '=' . rawurlencode($value);
        }
    }

    $out = $parts['scheme'] . '://' . $parts['host'] . ($parts['path'] ?? '');
    if ($kept !== []) {
        $out .= '?' . implode('&', $kept);
    }
    if (isset($parts['fragment'])) {
        $out .= '#' . $parts['fragment'];
    }
    return $out;
}

// Example:
//   build('example.com/page?utm_source=stale&id=7', ['source' => 'twitter', 'medium' => 'social'])
//   -> 'https://example.com/page?id=7&utm_source=twitter&utm_medium=social'