• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

関数リファレンス/add query arg

提供: WordPress Codex 日本語版
移動先: 案内検索

説明

クエリ文字列を付けたURLを取得します。

URLを再構築して URLクエリに新しいクエリ変数を追加できます。またクエリデータ付きの完全なURLも取得できます。

単一のキーと値、または連想配列を追加できます。キー値にfalseを設定して、クエリから削除できます。古いクエリやURI(第2、第3パラメータ)を省略すると、$_SERVER値が使用されます。


使い方

<?php
// 個別の引数によるパラメータ
add_query_arg( $param1, $param2, $old_query_or_uri );

// キー => 値 ペアの配列によるパラメータ
add_query_arg( array('key1' => 'value1', ...), $old_query_or_uri );
?>

パラメータ

$param1
整数|文字列|配列) (必須) 新しいキー、または連想配列
初期値: なし
$param2
整数|文字列|ブーリアン) (オプション) 新しい値 (第1パラメータが連想配列であれば、古いクエリ、またはURI)
初期値: なし
$old_query_or_uri
文字列|ブーリアン) (オプション) 古いクエリ、またはURI
初期値: $_SERVER['REQUEST_URI']

戻り値

(文字列) 
新しいURLクエリ文字列

用例

// パラメーターを2つの引数として指定
add_query_arg( $param1, $param2, $old_query_or_uri );
 
// パラメーターを キー => バリュー ペアの配列として指定
add_query_arg( array('key1' => 'value1', ...), $old_query_or_uri );

現在 WordPress URL "http://blog.example.com/client/?s=word" にいると仮定して...リンクを出力する前にesc_url()を使用する必要があることに注意してください。この関数はURLをエスケープしませんので、クロスサイトスクリプティングの原因になります。

// '/client/?s=word&foo=bar' を出力します
echo esc_url( add_query_arg( 'foo', 'bar' ) );

// '/client/?s=word&foo=bar&baz=tiny' を出力します
$arr_params = array( 'foo' => 'bar', 'baz' => 'tiny' );
echo esc_url( add_query_arg( $arr_params ) );

ほとんどの場合、今いる場所から次の方法でURLを作成することになるでしょう。このとき対象とするURLを最後のパラメータとして使用できます。この場合、esc_url()は必須ではありません。指定したURLは安全であることが自明であるからです。

// 'http://blog.example.com/2009/04/16/?hello=world' を出力します。
echo esc_url( add_query_arg( 'hello', 'world', 'http://blog.example.com/2009/04/16/' ) );

get_permalink() は完全な URL を返すため、投稿のページに変数を追加する際に使用できます。

// 投稿ID 9 の URL に対して、必要な ? または & に続けて、'hello=there' を追加して出力します。
echo esc_url( add_query_arg( 'hello', 'there', get_permalink(9) ) );

連想配列を使用して、値を削除、設定します:

$query = 'http://example.com/link?foo=bar';
$new_query = add_query_arg( array('foo' => false, 'baz' => 'qux'), $query );
// 結果: http://example.com/link?baz=qux

変更履歴

  • 4.1.2: クロスサイトスクリプティングを引き起こす間違った用例を修正。関連情報
  • 3.5.0: 正規表現を止めることで add_query_arg() 内のプロトコル削除を簡素化
  • 1.5.0以降

ソースファイル

add_query_arg()wp-includes/functions.php で定義されています。

関連

remove_query_arg()[en]


関数リファレンステンプレートタグ目次もご覧ください。


最新英語版: WordPress Codex » Function Reference/add_query_arg最新版との差分