URL エンコードされたクエリ文字列を生成する

# http_build_query

(PHP 5, PHP 7)

http_build_query — URL エンコードされたクエリ文字列を生成する

### 説明

http_build_query ( mixed `$query_data` [, string `$numeric_prefix` [, string `$arg_separator` [, int `$enc_type` = `PHP_QUERY_RFC1738` ]]] ) : string

与えられた連想配列 (もしくは添字配列) から URL エンコードされたクエリ文字列を生成します。

### パラメータ

`query_data`

  プロパティを含む配列もしくはオブジェクト。

  `query_data` が配列の場合の形式は、 単純な一次元構造か あるいは配列の配列 (言い換えると、他の配列を含む配列) となります。

  `query_data` がオブジェクトの場合、 public プロパティだけが結果に含められます。

`numeric_prefix`

  情報源となる配列 (`query_data` で指定した配列) に数値インデックスが使われていて、しかも `numeric_prefix` が指定された場合、数値のインデックスを持つ要素に関してのみインデックスの前に `numeric_prefix` で指定した値が付加されます。

  これは、後で PHP や他の CGI アプリケーションによってデータがデコードされる際、 正当な変数名になるよう考慮したものです。

`arg_separator`

  arg_separator.output が区分のためのセパレータとして使用されます。ただし、 このパラメータが指定されていた場合は それが使用されます。

`enc_type`

  デフォルトは `PHP_QUERY_RFC1738` です。

  `enc_type` が `PHP_QUERY_RFC1738` の場合は » RFC 1738 に従ってエンコードされ、メディアタイプは application/x-www-form-urlencoded となります。 つまり、スペースはプラス記号 (+) にエンコードされるということです。

  `enc_type` が `PHP_QUERY_RFC3986` の場合は » RFC 3986 に従ってエンコードされ、 スペースはパーセント形式 (%20) となります。

### 返り値

URL エンコードされた文字列を返します。

### 変更履歴

バージョン | 説明
--- | ---
5.4.0 | `enc_type` パラメータが追加されました。
5.1.3 | 角括弧がエスケープされるようになりました。
5.1.2 | パラメータ `arg_separator` が追加されました。

### 例

例1 http_build_query() の簡単な使用法

`<?php
$data = array(
'foo' => 'bar',
'baz' => 'boom',
'cow' => 'milk',
'php' => 'hypertext processor'
);
echo http_build_query($data) . "\n";
echo http_build_query($data, '', '&amp;');
?>`

上の例の出力は以下となります。

    foo=bar&baz=boom&cow=milk&php=hypertext+processor
    foo=bar&amp;baz=boom&amp;cow=milk&amp;php=hypertext+processor

例2 数値インデックス要素の場合での http_build_query()

`<?php
$data = array('foo', 'bar', 'baz', 'boom', 'cow' => 'milk', 'php' => 'hypertext processor');
echo http_build_query($data) . "\n";
echo http_build_query($data, 'myvar_');
?>`

上の例の出力は以下となります。

    0=foo&1=bar&2=baz&3=boom&cow=milk&php=hypertext+processor
    myvar_0=foo&myvar_1=bar&myvar_2=baz&myvar_3=boom&cow=milk&php=hypertext+processor

例3 複雑な配列の場合での http_build_query()

`<?php
$data = array(
'user' => array(
'name' => 'Bob Smith',
'age' => 47,
'sex' => 'M',
'dob' => '5/12/1956'
),
'pastimes' => array('golf', 'opera', 'poker', 'rap'),
'children' => array(
'bobby' => array('age'=>12, 'sex'=>'M'),
'sally' => array('age'=>8, 'sex'=>'F')
),
'CEO'
);
echo http_build_query($data, 'flags_');
?>`

この例は以下を出力します: (可読性のため適宜折り返しています)

    user%5Bname%5D=Bob+Smith&user%5Bage%5D=47&user%5Bsex%5D=M&
    user%5Bdob%5D=5%2F12%2F1956&pastimes%5B0%5D=golf&pastimes%5B1%5D=opera&
    pastimes%5B2%5D=poker&pastimes%5B3%5D=rap&children%5Bbobby%5D%5Bage%5D=12&
    children%5Bbobby%5D%5Bsex%5D=M&children%5Bsally%5D%5Bage%5D=8&
    children%5Bsally%5D%5Bsex%5D=F&flags_0=CEO

> 注意:

> 基底の配列内の数値インデックス要素 "CEO" のみ、 接頭辞を受け取ります。pastimes 以下にある他の数値インデックスは、 正当な変数名にするための文字列の接頭辞を要求しません。

例4 オブジェクトの場合の http_build_query() の使用

`<?php
class parentClass {
public $pub = 'publicParent';
protected $prot = 'protectedParent';
private $priv = 'privateParent';
public $pub_bar = Null;
protected $prot_bar = Null;
private $priv_bar = Null;
public function __construct(){
$this->pub_bar = new childClass();
$this->prot_bar = new childClass();
$this->priv_bar = new childClass();
}
}
class childClass {
public $pub = 'publicChild';
protected $prot = 'protectedChild';
private $priv = 'privateChild';
}
$parent = new parentClass();
echo http_build_query($parent);
?>`

上の例の出力は以下となります。

    pub=publicParent&pub_bar%5Bpub%5D=publicChild

### 参考

- parse_str() - 文字列を処理し、変数に代入する
- parse_url() - URL を解釈し、その構成要素を返す
- urlencode() - 文字列を URL エンコードする
- array_walk() - 配列の全ての要素にユーザー定義の関数を適用する