build_query()

Q: 日本語などは自動でエンコードされる？

はい、内部で urlencode() 相当の処理が行われます。

Q: http_build_query() との違いは？

WordPressのフィルター (build_query) が使える点が異なります。

Q: 配列の中に配列があったら？

PHPの仕様通り、key[subkey]=value のような形式になります。

Function

2025/8/2 Saturday

build_query() は、配列で指定されたクエリパラメータを URL エンコードされたクエリ文字列に変換する関数です。

http_build_query() に似ていますが、WordPress 特有のフィルターを通すことで、より柔軟にカスタマイズされたクエリ文字列を生成できます。リダイレクトやリンク生成などの場面で便利に使えます。

機能の説明

どんな関数か？

build_query() は、配列を key=value の形式に変換してクエリ文字列（example=123&sort=asc のような文字列）を生成する関数です。

これは主に URL を動的に生成する際 や、wp_redirect() などのリダイレクト処理で GET パラメータを付与したいときに使用されます。

シンプルなコード例

$params = [
  'post_type' => 'post',
  'orderby'   => 'date',
  'order'     => 'desc',
];

$query_string = build_query( $params );

echo $query_string;
// 出力例: post_type=post&orderby=date&order=desc

使い方の説明

関数構文

string build_query( array $data )

引数

$data（配列）: クエリ文字列に変換したい連想配列。

戻り値

クエリ文字列（string）: key=value&key2=value2... の形式。

使用例：URLの自動生成

$url_base = home_url( '/custom-page/' );
$params = [
  'category' => 'wordpress',
  'page'     => 2,
];

$url = $url_base . '?' . build_query( $params );

echo esc_url( $url );
// https://example.com/custom-page/?category=wordpress&page=2

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

`add_query_arg()`

$url = add_query_arg( [ 'page' => 2 ], home_url( '/blog/' ) );

`http_build_query()`

PHP 標準の関数。build_query() の内部的な元になっている関数。

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

より細かく制御したい場合は、以下のようにカスタム処理を追加できます。

$params = [
  'search' => 'カスタム投稿',
  'lang'   => 'ja',
];

$query_string = build_query( $params );

日本語などの文字列は自動的にエンコードされます。
（例: %E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E6%8A%95%E7%A8%BF）

この関数を利用してのカスタマイズ

投稿タイプ切り替えリンクを作る例

$post_types = ['post', 'page', 'custom'];

foreach ( $post_types as $type ) {
  $url = add_query_arg( 'post_type', $type, home_url( '/' ) );
  echo '<a href="' . esc_url( $url ) . '">' . esc_html( ucfirst( $type ) ) . '</a><br>';
}