add_query_arg() の使い方｜説明・引数・注意点

説明

基本構文

add_query_arg( string|array $key, string|int|null $value_or_uri, string $uri = '' ): string

引数

• $key：キー（または連想配列）
• $value_or_uri：値（またはURI）
• $uri：対象のURL

戻り値

クエリ付きのURL。

使い方（サンプル）

$url = add_query_arg( 'tab', 'settings', admin_url( 'admin.php?page=my-page' ) );

注意点

• 出力時は esc_url() を通します。XSS（スクリプト混入）の原因になりやすい関数です。
• 既存のキーは上書きされます。

実務での使いどころ

• URLに、クエリのパラメータ（並び替え、絞り込みなど）を、追加・更新するとき。
• 現在のURLを、基準に、リンクを作るとき。

よくあるミスと対処

• $url を省略すると、現在のURLが、基準になる。URLに含まれる、入力値が、そのまま出力され、クロスサイトスクリプティング（XSS）の原因になる。出力するときは、必ず esc_url() を通す。
• 出力時に、エスケープしていない。
• パラメータを、削除したいのに、これを使っている。削除は、remove_query_arg()。

NG例

echo '<a href="' . add_query_arg( 'sort', 'date' ) . '">日付順</a>'; // 現在のURLが基準で、エスケープもない

OK例

echo '<a href="' . esc_url( add_query_arg( 'sort', 'date', get_permalink() ) ) . '">日付順</a>';

使い分け早見表

関連項目

remove_query_arg()、esc_url()

公式リファレンス：add_query_arg() | Function | WordPress Developer Resources