http_build_query

(PHP 5, PHP 7, PHP 8)

http_build_query — Génère une chaîne de requête en encodage URL

Description

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

Génère une chaîne en encodage URL, construite à partir du tableau indexé ou associatif data.

Liste de paramètres

data

Peut être un tableau ou un objet contenant des propriétés.

Si data est un tableau, alors ce peut être un tableau à une ou plusieurs dimensions.

Si data est un objet, alors seuls les attributs publics seront utilisés dans le résultat.

numeric_prefix

Si des indices numériques sont utilisés dans le tableau de base et que numeric_prefix est fourni, il sera utilisé pour préfixer les noms des index pour les éléments du tableau de base seulement.

Cela permet de générer des noms de variables valides, si les données sont ensuite décodées par PHP ou une application CGI.

arg_separator

Le séparateur d'arguments. S'il n'est pas défini ou est null, arg_separator.output est utilisée pour séparer les arguments.

encoding_type

Par défaut, vaut PHP_QUERY_RFC1738.

Si encoding_type vaut PHP_QUERY_RFC1738, alors l'encodage est effectué conformément à la » RFC 1738 et les espaces du type de média application/x-www-form-urlencoded, qui est impacté par ce choix, seront encodés sous la forme d'un signe plus (+).

Si encoding_type vaut PHP_QUERY_RFC3986, alors l'encodage est effectué conformément à la » RFC 3986, et les espaces seront encodés en signe pourcent (%20).

Valeurs de retour

Retourne une chaîne de caractères encodée URL.

Historique

Version	Description
8.0.0	`arg_separator` est désormais nullable.

Exemples

Exemple #1 Utilisation simple de 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;');

?>

L'exemple ci-dessus va afficher :

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

Exemple #2 http_build_query() avec tableau indexé

<?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_');
?>

L'exemple ci-dessus va afficher :

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

Exemple #3 http_build_query() avec tableau complexe

<?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_');
?>

l'exemple ci-dessus va afficher : (sur plusieurs lignes pour la lisibilité)

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

Note:
Seuls les éléments indexés numériquement ("CEO") dans le tableau de base sont préfixés. Les autres indices numériques à d'autres niveaux n'ont pas besoin de l'être pour avoir des noms valides.

Exemple #4 Utilisation de http_build_query() avec un objet

<?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);
?>

L'exemple ci-dessus va afficher :

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

Voir aussi

parse_str() - Analyse une chaîne de caractères d'une variable
parse_url() - Analyse une URL et retourne ses composants
urlencode() - Encode une chaîne en URL
array_walk() - Exécute une fonction fournie par l'utilisateur sur chacun des éléments d'un tableau

add a note

User Contributed Notes 24 notes

down

134

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

down

Sergei S. ¶

5 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
?>

down

itsadok at gmail dot com ¶

9 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);

down

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

down

eric dot muyser at gmail dot com ¶

11 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);

down

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

down

chat dot noir at arcor dot de ¶

7 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;

}?>

down

anonymous ¶

12 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

down

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.

down

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

down

james at dimensionengineering dot com ¶

9 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.

down

Vitaly Dyatlov ¶

11 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>

down

-1

netrox at aol dot com ¶

15 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.

down

-1

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.

down

-1

rishad at kaluma dot com ¶

6 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.

down

-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

down

-10

valdikss at gmail dot com ¶

17 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);}
?>

down

-2

drewdeveloperthomas at gmail dot com ¶

4 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
?>

down

-6

joey dot qiang at innomative dot com ¶

9 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";

down

-10

Kirils Solovjovs ¶

11 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))

down

-9

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

down

-2

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"
*/
?>

down

-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!

down

-42

jakub dot lopuszanski at nasza-klasa dot pl ¶

11 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'));
?>

add a note