Como utilizar add_query_arg() no WordPress

Com a função PHP add_query_arg() você adiciona parâmetros a uma URL. Abaixo mostro as duas maneiras de se utilizar esta função.

Para uma única chave e valor:

<?php
$url = add_query_arg( 'chave', 'valor', 'https://wwww.danielkossmann.com/' );

// $url retornará: https://wwww.danielkossmann.com/?chave=valorCode language: PHP (php)

Para um array associativo com múltiplas chaves e valores:

<?php
$parametros = array(
	"chave1"	=> "valor1",
	"chave2"	=> "valor2",
	"chave3"	=> "valor3"
);
$url = add_query_arg( $parametros, 'https://wwww.danielkossmann.com/' );

// $url retornará: https://wwww.danielkossmann.com/?chave1=valor1&chave2=valor2&chave3=valor3Code language: PHP (php)

Se você adicionar uma URL que já possua parâmetros, a função add_query_arg() irá adicionar os novos valores no final da URL:

<?php
$parametros = array(
	"chave1"	=> "valor1",
	"chave2"	=> "valor2",
);
$url = add_query_arg( $parametros, 'https://wwww.danielkossmann.com/?chave0=valor0' );

// $url retornará: https://wwww.danielkossmann.com/?chave0=valor0&chave1=valor1&chave2=valor2Code language: PHP (php)

Caso não seja informado uma URL no último parâmetro da função, ela irá utilizar a URL atual obtida através do valor da variável $_SERVER['REQUEST_URI'].

Aviso importante: A função add_query_arg() espera que todos os valores já estejam codificados com urlencode() ou rawurlencode(). Além disso, seu retorno deve ser tratado com esc_url(), ou similar, para evitar ataques de cross-site scripting (XSS).

Criando um link com parâmetros adicionais de UTM na URL

Um exemplo prático da função add_query_arg() é para adicionar parâmetros UTM em uma URL, de forma a permitir o rastreamento do usuário por ferramentas como o Google Analytics:

<?php
$parametros = array(
	"utm_source"	=> "painelwp",
	"utm_medium"	=> "email",
	"utm_campaign"	=> "dica_programacao",
);
$url = add_query_arg( $parametros, $url_dica );

echo "Veja <a href='" . esc_url( $url ) . "'>como utilizar add_query_arg()</a> no WordPress.";Code language: PHP (php)

Se você quiser uma maneira fácil de gerar URL para campanhas, recomendo a ferramenta Campaign URL Builder do próprio Google Analytics.