add_query_arg()

add_query_arg() は、URL にクエリパラメータ（GETパラメータ）を追加・変更するための WordPress 関数です。

動的に URL を生成する際に便利で、例えば検索結果のページネーション、カスタムフィルター、非同期処理のリクエスト生成などに活用できます。この関数を使用すると、現在の URL にパラメータを追加したり、指定した URL に対して変更を加えたりできます。

機能の説明

add_query_arg() は、指定したクエリパラメータを URL に追加または変更するための関数です。
以下のような場面でよく使われます。

主な用途

• ページネーション（例: ?paged=2 の追加）
• カスタムフィルター（例: ?category=news の追加）
• Ajax リクエストの URL 作成
• リファラー URL にパラメータを付与してリダイレクト処理

この関数は、WordPress の home_url() や get_permalink() と組み合わせて使うことで、WordPress の環境に適した URL 生成ができます。

シンプルなコード例

$url = add_query_arg('paged', 2, home_url('/news/'));
echo $url;

• 'paged'：追加するクエリパラメータのキー
• 2：追加するクエリパラメータの値
• home_url('/news/')：ベースとなる URL（ここでは https://example.com/news/）
• 結果：https://example.com/news/?paged=2

使い方の説明

単一のクエリパラメータを追加する

$url = add_query_arg('category', 'sports', home_url('/blog/'));
echo $url; // https://example.com/blog/?category=sports

category=sports のパラメータを /blog/ の URL に追加

複数のクエリパラメータを追加する

$url = add_query_arg(array(
    'category' => 'news',
    'paged'    => 3
), home_url('/blog/'));
echo $url; 
// https://example.com/blog/?category=news&paged=3

category=news と paged=3 の 2 つのパラメータを /blog/ に追加

現在の URL にクエリパラメータを追加する

現在の URL に orderby=date を追加したい場合：

$url = add_query_arg('orderby', 'date');
echo esc_url($url);

add_query_arg() の第3引数を省略すると、現在の URL にパラメータが追加される

一緒に使うことが多い関連タグ

remove_query_arg()

URL から特定のクエリパラメータを削除する。

$url = add_query_arg(array('category' => 'news', 'paged' => 3), home_url('/blog/'));
$url = remove_query_arg('paged', $url);
echo $url; 
// https://example.com/blog/?category=news

esc_url()

add_query_arg() を使用すると、URL に & 記号が含まれるため、出力時に esc_url() でエスケープするのが推奨される。

echo esc_url(add_query_arg('category', 'news'));

wp_redirect()

add_query_arg() で作成した URL にリダイレクトする際に使用。

wp_redirect(esc_url_raw(add_query_arg('success', '1', home_url('/thank-you/'))));
exit;

追加情報で取得したい場合

現在のクエリパラメータを取得する

現在の URL に含まれる特定のクエリパラメータを取得する場合、get_query_var() を使用する。

$category = get_query_var('category');
echo '現在のカテゴリ: ' . esc_html($category);

想定されるトラブル

パラメータが正しく追加されない

解決方法

• URL に既にパラメータがある場合、add_query_arg() を使用すると & のエンコーディングの問題が発生することがある。その場合は esc_url() を使う。
• 例えば、?key1=value1?key2=value2 となってしまうことがある。

echo esc_url(add_query_arg('key2', 'value2', 'https://example.com/page?key1=value1'));

リダイレクト時の URL に & が正しく処理されない

解決方法

wp_redirect() の際には esc_url_raw() を使用する。

wp_redirect(esc_url_raw(add_query_arg('status', 'success', home_url('/result/'))));
exit;

Q＆A

まとめ

add_query_arg() は、URL に GET パラメータを追加・変更するための便利な関数です。

ページネーションやカスタム検索のフィルタリングなど、さまざまな用途で使用されます。remove_query_arg() や esc_url() と組み合わせることで、安全かつ適切に URL を生成・操作できます。