概念と使用方法

PHPバージョン
5+

http_build_query()関数は、
配列やオブジェクトをURLで使用可能な文字列形式にエンコードし、クエリ文字列を生成する関数です。

この関数は、配列やオブジェクトを基にHTTPリクエストを生成したりURLを作成する際に非常に便利に利用されます。

基本の例

以下は配列を基にURLを作成する基本的な例です。

PHP 
$data = array(
    'name' => 'John Doe',
    'age' => 30,
    'city' => 'New York'
);

$queryString = http_build_query($data);
echo $queryString;

// 出力: 'name=John+Doe&age=30&city=New+York'

構文

PHP 
http_build_query(
    array|object $data,
    string $numeric_prefix = "",
    ?string $arg_separator = null,
    int $encoding_type = PHP_QUERY_RFC1738
): string

引数

$data

URLで使用可能な形式にエンコードしてクエリ文字列を生成するための配列またはオブジェクトです。

  • $dataが配列の場合、単純な一次元構造であることもあれば、他の配列を含む配列の配列であることもあります。
  • $dataがオブジェクトの場合、publicプロパティのみが結果に統合されます。

$numeric_prefix

もし基礎となる配列に数値インデックスが使用され、このパラメータが指定された場合、その値は基礎配列の要素に対してのみ数値インデックスの前に付加されます。デフォルト値は空文字列（''）です。

これは、PHPやその他のCGIアプリケーションでデータを後にデコードする際に、有効な変数名を許可するためのものです。

例えば、次のような配列があると仮定します。

PHP 
$data = array(
    1 => 'foo',
    2 => 'bar',
    3 => 'baz',
);

$queryString = http_build_query($data, 'my_');
echo $queryString;
// 出力: 'my_1=foo&my_2=bar&my_3=baz'

この配列をhttp_build_query()関数に渡し、第二引数に'my_'を設定すると、次のようなクエリ文字列が生成されます。

数値インデックス名の前にmy_という接頭辞が追加され、PHPやその他のCGIアプリケーションで変数名として使用可能になります。第二引数を設定しない場合、数値インデックス名はそのまま保持されます。

$arg_separator

キーと値のペアを区切るための引数区切り文字です。PHPのarg_separator.output設定値が使用されます。arg_separator.outputの値は、PHPのphp.iniファイルに設定された値です。デフォルトの値はアンパサンド（&）です。引数をnullに設定すると、キーと値のペアを区切らず、区切り文字は生成されません。

例えば、次のような配列があると仮定します。

PHP 
$data = array(
    'foo' => 'bar',
    'baz' => 'boom',
    'cow' => 'milk',
);

この配列をhttp_build_query()関数に渡し、第三引数を設定しない場合、次のようなクエリ文字列が生成されます。デフォルトの区切り文字であるアンパサンド（&）が使用されます。

PHP 
$data = array(
    'foo' => 'bar',
    'baz' => 'boom',
    'cow' => 'milk',
);

$queryString = http_build_query($data);
echo $queryString;
// 出力: 'foo=bar&baz=boom&cow=milk'

第三引数を空文字列（''）に設定すると、次のようなクエリ文字列が生成されます。区切り文字は生成されません。

PHP 
$data = array(
    'foo' => 'bar',
    'baz' => 'boom',
    'cow' => 'milk',
);

$queryString = http_build_query($data, '', '');
echo $queryString;
// 出力: 'foo=barbaz=boomcow=milk'

第三引数にコンマ（','）を設定すると、次のようなクエリ文字列が生成されます。

PHP 
$data = array(
    'foo' => 'bar',
    'baz' => 'boom',
    'cow' => 'milk',
);

$queryString = http_build_query($data, '', ',');
echo $queryString;
// 出力: 'foo=bar,baz=boom,cow=milk'

第三引数にセミコロン（';'）を設定すると、次のようなクエリ文字列が生成されます。

PHP 
$data = array(
    'foo' => 'bar',
    'baz' => 'boom',
    'cow' => 'milk',
);

$queryString = http_build_query($data, '', ';');
echo $queryString;
// 出力: 'foo=bar;baz=boom;cow=milk'

$encoding_type

エンコード方式を設定します。デフォルト値はPHP_QUERY_RFC1738です。

  • PHP_QUERY_RFC1738はPHPで提供される定数で、この定数を指定するとRFC 1738およびapplication/x-www-form-urlencodedメディアタイプに従ってエンコードが行われます。urlencode()関数と同様に、英字の大文字・小文字、数字、-、_、.以外の文字は%記号と16進コードでエンコードされます。空白は+でエンコードされます。
  • PHP_QUERY_RFC3986はPHPで提供される定数で、この定数を指定するとRFC 3986に従ってエンコードが行われます。rawurlencode()関数と同様に、英字の大文字・小文字、数字、-、.、_、~以外の文字は%記号と16進コードでエンコードされます。空白は%20でエンコードされます。

例えば、次のような配列があると仮定します。

PHP 
$data = array(
    'name' => 'John Doe',
    'age' => 30,
    'city' => 'New York'
);

この配列をhttp_build_query()関数に渡し、第四引数にデフォルト値であるPHP_QUERY_RFC1738を設定すると、次のようなクエリ文字列が生成されます。

PHP 
$data = array(
    'name' => 'John Doe',
    'age' => 30,
    'city' => 'New York'
);

$queryString = http_build_query($data, '', null, PHP_QUERY_RFC1738);
echo $queryString;

// 出力: 'name=John+Doe&age=30&city=New+York'

空白は+記号でエンコードされました。

第四引数をPHP_QUERY_RFC3986に設定すると、次のようなクエリ文字列が生成されます。

PHP 
$data = array(
    'name' => 'John Doe',
    'age' => 30,
    'city' => 'New York'
);

$queryString = http_build_query($data, '', null, PHP_QUERY_RFC3986);
echo $queryString;

// 出力: 'name=John%20Doe&age=30&city=New%20York'

空白は%20でエンコードされました。

使用例

次の活用例を通して、http_build_query()関数の使い方を確認していきます。

HTTP GETリクエストを生成する場合

Webアプリケーションでサーバーにデータを送信するためにHTTP GETリクエストを生成する必要がある場合、http_build_query()関数が便利です。例えば、検索ワードやフィルタ条件をURLに含めてサーバーに送信する際に使用できます。

PHP 
$params = array(
    'search_query' => 'keyword',
    'category' => 'books',
    'sort' => 'relevance'
);

$query_string = http_build_query($params);
$url = 'https://example.com/search?' . $query_string;

// これで $url は "https://example.com/search?search_query=keyword&category=books&sort=relevance" のような形式になります。

APIリクエストを生成する場合

リモートAPIにリクエストを送信する際、APIエンドポイントとリクエストパラメータを含むURLを生成できます。

PHP 
$api_endpoint = 'https://api.example.com/data';
$api_key = 'your_api_key';
$params = array(
    'api_key' => $api_key,
    'action' => 'get_data',
    'format' => 'json'
);

$api_url = $api_endpoint . '?' . http_build_query($params);

// $api_url は "https://api.example.com/data?api_key=your_api_key&action=get_data&format=json" のような形式になります。

HTMLフォーム要素のaction属性を生成する場合

Webフォームを作成する際、action属性にURLを設定する必要がありますが、http_build_query()関数を使用してフォームデータをURLに含めることができます。

PHP 
$form_data = array(
    'username' => 'user123',
    'password' => 'secret',
    'remember' => 1
);

$action_url = 'https://example.com/login?' . http_build_query($form_data);

// 出力: 'https://example.com/login?username=user123&password=secret&remember=1'
// これで HTML フォームの <form> 要素の action 属性に $action_url を設定できます。

オブジェクトを使用してクエリ文字列を生成する場合

http_build_query()関数は配列だけでなく、オブジェクトのpublicプロパティもクエリ文字列に変換できます。この場合、publicプロパティのみがクエリ文字列に変換されます。protectedやprivateなどのアクセス制限付きプロパティは含まれません。

PHP 
class UserProfile {
    public $id = 101;
    public $username = 'happy_coder';
    public $status = 'online';
    protected $password = 'secret'; // protected/private プロパティは除外されます
}

$user_profile_object = new UserProfile();

$query_string_object = http_build_query($user_profile_object);
echo 'https://api.example.com/profile?' . $query_string_object;

// 出力: 'https://api.example.com/profile?id=101&username=happy_coder&status=online'

参考資料

関連項目