PHP 8.3.4 Released!

http_build_query

(PHP 5, PHP 7, PHP 8)

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

説明

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

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

パラメータ

data

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

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

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

numeric_prefix

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

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

arg_separator

引数のセパレータ。指定されていなかったり、null だった場合は、 arg_separator.output が区分のためのセパレータとして使用されます。

encoding_type

デフォルトは PHP_QUERY_RFC1738 です。

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

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

戻り値

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

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

<?php
$data
= array(
'foo' => 'bar',
'baz' => 'boom',
'cow' => 'milk',
'null' => null,
'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', null, 'boom', 'cow' => 'milk', 'php' => 'hypertext processor');

echo
http_build_query($data) . "\n";
echo
http_build_query($data, 'myvar_');
?>

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

0=foo&1=bar&2=baz&4=boom&cow=milk&php=hypertext+processor
myvar_0=foo&myvar_1=bar&myvar_2=baz&myvar_4=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() - 配列の全ての要素にユーザー定義の関数を適用する

add a note

User Contributed Notes 24 notes

up
138
Ilya Rudenko
18 years ago
Params with null value do not present in result string.

<?php
$arr
= array('test' => null, 'test2' => 1);
echo
http_build_query($arr);
?>

will produce:

test2=1
up
40
itsadok at gmail dot com
8 years ago
Passing null to $arg_separator is the same as passing an empty string, which is probably not what you want.

If you need to change the enc_type, use this:

http_build_query($query, null, '&', PHP_QUERY_RFC3986);

Or possibly this:

http_build_query($query, null, ini_get('arg_separator.output'), PHP_QUERY_RFC3986);

But not this:

// BAD CODE!
http_build_query($query, null, null, PHP_QUERY_RFC3986);
up
15
Sergei S.
4 years ago
Number to string conversion occured in <?php http_build_query() ?> is affected by locale settings, which might not be obvious.

<?php
$params
= ["v" => 5.63];

setlocale(LC_ALL, 'us_En');
http_build_query($params) // v=5.63

setlocale(LC_ALL, 'ru_RU');
http_build_query($params) // v=5,63 mind the comma
?>
up
19
flavio at agenciaeme dot com dot br
6 years ago
if you send boolean values it transform in integer :

$a = [teste1= true,teste2=false];
echo http_build_query($a)

//result will be teste1=1&teste2=0
up
50
eric dot muyser at gmail dot com
10 years ago
This function makes like this

files[0]=1&files[1]=2&...

To do it like this:

files[]=1&files[]=2&...

Do this:

$query = http_build_query($query);
$query = preg_replace('/%5B[0-9]+%5D/simU', '%5B%5D', $query);
up
24
Anonymous
13 years ago
As noted before, with php5.3 the separator is &amp; on some servers it seems. Normally if posting to another php5.3 machine this will not be a problem.

But if you post to a tomcat java server or something else the &amp; might not be handled properly.

To overcome this specify:

http_build_query($array, '', '&');

and NOT

http_build_query($array); //gives &amp; to some servers
up
5
chat dot noir at arcor dot de
6 years ago
If you need the inverse functionality, and (like me) you cannot use pecl_http, you may want to use something akin to the following.

<?php function http_parse_query($Query) {

// mimic the behavior of $_GET, see also RFC 1738 and 3986.
$Delimiter = ini_get('arg_separator.input');
$Params = array();

foreach (
explode($Delimiter, $Query) as $NameValue) {
preg_match(
'/^(?P<name>[^=\[]*)(?P<indices_present>\[(?P<indices>[^\]]*(\]\[[^\]]*)*)\]?)?(?P<value_present>=(?P<value>.*))?$/',
$NameValue,
$NameValueParts
);

if (!empty(
$NameValueParts)) {
$Param =& $Params[$NameValueParts['name']];

if (!empty(
$NameValueParts['indices_present'])) {
$Indices = explode('][', $NameValueParts['indices']);

foreach (
$Indices as $Index) {
if (!
is_array($Param)) {
$Param = array();
}

if (
$Index === '') {
$Param[] = array();
end($Param);
$Param =& $Param[key($Param)];
} else {
if (
ctype_digit($Index)) { $Index = (int) $Index; }

if (!
array_key_exists($Index, $Param)) {
$Param[$Index] = array();
}
$Param =& $Param[$Index];
}
}
}

if (!empty(
$NameValueParts['value_present'])) {
$Param = urldecode($NameValueParts['value']);
} else {
$Param = '';
}
}
}

return
$Params;

}
?>
up
14
anonymous
11 years ago
Is it worth noting that if query_data is an associative array and a value is itself an empty array, or an array of nothing but empty array (or arrays containing only empty arrays etc.), the corresponding key will not appear in the resulting query string?
E.g.

$post_data = array('name'=>'miller', 'address'=>array('address_lines'=>array()), 'age'=>23);
echo http_build_query($post_data);

will print
name=miller&age=23
up
5
irish [-@-] ytdj [-dot-] ca
14 years ago
When using the http_build_query function to create a URL query from an array for use in something like curl_setopt($ch, CURLOPT_POSTFIELDS, $post_url), be careful about the url encoding.

In my case, I simply wanted to pass on the received $_POST data to a CURL's POST data, which requires it to be in the URL format. If something like a space [ ] goes into the http_build_query, it comes out as a +. If you're then sending this off for POST again, you won't get the expected result. This is good for GET but not POST.

Instead you can make your own simple function if you simply want to pass along the data:

<?php
$post_url
= '';
foreach (
$_POST AS $key=>$value)
$post_url .= $key.'='.$value.'&';
$post_url = rtrim($post_url, '&');
?>

You can then use this to pass along POST data in CURL.

<?php
$ch
= curl_init($some_url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_url);
curl_exec($ch);
?>

Note that at the final page that processes the POST data, you should be properly filtering/escaping it.
up
2
james at dimensionengineering dot com
8 years ago
Be careful about Example 1 -- it is exactly how *not* to implement things.

& as a separator is the URL encoding.
&amp; is HTML encoding.

You should HTML encode your URL if embedding it in a web page. This is more involved than just replacing & with &amp;. Doing as this example suggests is a security hole waiting to happen.
up
2
Mark Simon
9 years ago
As noted, this function omits keys with null values. This could break some code which treats the key as boolean, and so has no value, or other code expecting the array to be populated regardless of value.

A workaround for this is to replace the null values with an empty string:

$data=array(
'a'=>'apple',
'b'=>2,
'c'=>null,
'd'=>'…',
);

// Compensate for fact that http_build_query omits null values
foreach($data as &$datum) if($datum===null) $datum='';

Losing the null-ness of the original is no real loss if it’s supposed to be a real query string. If the null is important, you could use a dummy value instead.

Mark
up
-1
Vitaly Dyatlov
10 years ago
Correct implementation of coding the array of params without indexes (valdikks fixed code - didnt work for inner arrays):

<code>
function cr_post($a,$b='',$c=0)
{
if (!is_array($a)) return false;
foreach ((array)$a as $k=>$v)
{
if ($c)
{
if( is_numeric($k) )
$k=$b."[]";
else
$k=$b."[$k]";
}
else
{ if (is_int($k))
$k=$b.$k;
}

if (is_array($v)||is_object($v))
{
$r[]=cr_post($v,$k,1);
continue;
}
$r[]=urlencode($k)."=".urlencode($v);
}
return implode("&",$r);
}
</code>
up
-1
netrox at aol dot com
14 years ago
I noticed that even with the magic quotes disabled, http_build_query() automagically adds slashes to strings.

So, I had to add "stripslashes" to every string variable.
up
-1
rishad at kaluma dot com
5 years ago
When using http_build_query($args) where $args is an array; note that there is a limit to the size of array. See max_input_vars in your php.ini to increase this size.
up
-2
v0idnull[try_to_spam_me_now] at gee-mail dot co
14 years ago
on my install of PHP 5.3, http_build_query() seems to use &amp; as the default separator. Kind of interesting when combined with stream_context_create() for a POST request, and getting $_POST['amp;fieldName'] on the receiving end.
up
-4
rmaslo at archa dot cz
7 years ago
Warning: Different arrays may return the same result

<CODE>
$a1 = array('x[y]' => array('a'=>1));
$a2 = array('x' => array('y' => array('a'=>1)));
$q1 = http_build_query($a1);
$q2 = http_build_query($a2);
var_dump($a1);
echo '<BR>';
var_dump($a2);
echo '<BR>';
echo $q1;
echo '<BR>';
echo $q2;
echo '<BR>';
</CODE>

Result:
array(1) { ["x[y]"]=> array(1) { ["a"]=> int(1) } }
array(1) { ["x"]=> array(1) { ["y"]=> array(1) { ["a"]=> int(1) } } }
x%5By%5D%5Ba%5D=1
x%5By%5D%5Ba%5D=1
up
-10
valdikss at gmail dot com
16 years ago
This function is wrong for http!
arrays in http is like this:

files[]=1&files[]=2&...

but function makes like this

files[0]=1&files[1]=2&...

Here is normal function:

<?php
function cr_post($a,$b=\'\',$c=0){
if (!is_array($a)) return false;
foreach ((array)$a as $k=>$v){
if ($c) $k=$b.\"[]\"; elseif (is_int($k)) $k=$b.$k;
if (is_array($v)||is_object($v)) {$r[]=cr_post($v,$k,1);continue;}
$r[]=urlencode($k).\"=\".urlencode($v);}return implode(\"&\",$r);}
?>
up
-3
drewdeveloperthomas at gmail dot com
3 years ago
It's not mentioned in the documentation, but when calling http_build_query on an object, public null fields are ignored.

<?php

class A {
public
int $publicNotNull;
public ?
int $publicNull;
private
string $privateNotNull;

public function
__construct()
{
$this->publicNotNull = 2;
$this->privateNotNull = "Test";
}
}

$a = new A();
echo
http_build_query($a); // publicNotNull=2
?>
up
-6
joey dot qiang at innomative dot com
8 years ago
Not recommending to eliminate the numeric indices like:
'arg[0]' --> 'arg[]'

The reason is this function will not include null values in the result string:

$data = array(
'arg' => array(
null,
2,
3
)
);
echo http_build_query($data);

The output is something like "arg[1]=2&arg[2]=3";
up
-10
Kirils Solovjovs
10 years ago
instead of some other suggestions that did not work for me, I found that the best way to build POST content (e.g. for stream_context_create) is urldecode(http_build_query($query))
up
-10
joelhy
8 years ago
Params with false value will be changed to zero in result string.

<?php
$arr
= ['foo' => false];
echo
http_build_query($arr);
?>

will produce:

foo=0
up
-20
stocki dot r at gmail dot com
11 years ago
If you need only key+value pairs, you can use this:

<?php
$array
= array(
"type" => "welcome",
"message" => "Hello World!"
);
echo
urldecode(http_build_query($array, '', ';'));
?>

Result: type=welcome;message=Hello World!
up
-3
shaun at slickdesign dot com dot au
6 years ago
While http_build_query can also be used to encode most classes, into a query string, SimpleXML Elements with <![CDATA[]]> values are picked up as empty arrays, and therefore aren't included naturally.

<?php
$xml
= simplexml_load_string( '<wrapper><key><![CDATA[value]]></key><key2>value2</key2></wrapper>' );
var_dump( $xml, http_build_query( $xml ) );
/* Outputs:
object(SimpleXMLElement)#1 (2) {
["key"]=>
object(SimpleXMLElement)#2 (0) {
}
["key2"]=>
string(6) "value2"
}
string(11) "key2=value2"
*/
?>
up
-42
jakub dot lopuszanski at nasza-klasa dot pl
10 years ago
While this is not documented, this http_build_query can return FALSE on some inputs:
<?php
//gives bool(false)
var_dump(http_build_query('whatever'));
?>
To Top