http_build_query

関数の概要

http_build_query は、配列やオブジェクトからURLのクエリ文字列を生成するPHPの組み込み関数です。WebアプリケーションでGETリクエストのパラメータを作成するときや、ツール同士でデータをやり取りするときに便利に使えます。配列のキーと値を自動的にエンコードして、正しい形式のクエリ文字列を簡単に作成可能です。

パラメータの説明

  • query_data (array|object) : クエリに変換したい配列やオブジェクト。キーと値のペアを指定。
  • numeric_prefix (string) : 配列のキーが数値のときに付加する文字列。省略可能。
  • arg_separator (string) : クエリの区切り文字。デフォルトは ‘&’。
  • enc_type (int) : エンコードのタイプを指定。PHP_QUERY_RFC1738（デフォルト）はスペースを「+」に、PHP_QUERY_RFC3986は「%20」にエンコード。

戻り値

指定した配列やオブジェクトの内容をURLクエリ形式の文字列として返します。失敗すると空文字列を返します。

使用例

基本的な使い方

<?php
$params = [
  'name' => '山田太郎',
  'age' => 28,
  'city' => '東京'
];
$query = http_build_query($params);
echo $query;
?>

このコードは、name=山田太郎&age=28&city=東京 のようなクエリ文字列を生成します。日本語はURLエンコードされて表示されます。

ネストした配列の変換例

<?php
$params = [
  'user' => [
    'name' => '佐藤花子',
    'email' => 'sato@example.com'
  ],
  'page' => 2
];
$query = http_build_query($params);
echo $query;
?>

この場合、クエリ文字列は user%5Bname%5D=佐藤花子&user%5Bemail%5D=sato%40example.com&page=2 のようにネストした配列も階層を角括弧表記で表現します。

区切り文字の変更

<?php
$params = [
  'key1' => 'value1',
  'key2' => 'value2'
];
$query = http_build_query($params, '', ';');
echo $query;
?>

デフォルトは & ですが、3番目の引数を使ってセミコロン(;)を区切りに変更できます。結果は key1=value1;key2=value2 のようになります。

エンコードタイプの指定

<?php
$params = ['q' => 'PHP 関数'];
// PHP_QUERY_RFC1738（デフォルト）
echo http_build_query($params) . "n";
// PHP_QUERY_RFC3986（スペースは%20になる）
echo http_build_query($params, '', '&', PHP_QUERY_RFC3986);
?>

エンコードタイプを変更することで、スペースが「+」か「%20」かの違いを選択可能です。互換性の問題がある場合に使い分けます。

関連する関数

  • parse_str : URLクエリ文字列を配列に変換する逆の操作で使います。
  • urlencode : 単一の文字列をURLエンコードするときに使用します。
  • rawurlencode : RFC3986準拠のエンコードをしたい場合に使います。

まとめ

http_build_query はPHPで配列やオブジェクトから安全かつ正確にURLクエリ文字列を作成できる非常に便利な関数です。GETリクエストのパラメータ作成や外部APIとの通信でのURL構築に重宝します。引数でカスタマイズもでき、初心者からプロの現場まで幅広く活用可能です。

スポンサーリンク