PHP Doku:: Erstellen eines URL-kodierten Query-Strings - function.http-build-query.html

Verlauf / Chronik / History: (1) anzeigen

Sie sind hier:
Doku-StartseitePHP-HandbuchFunktionsreferenzSonstige GrunderweiterungenURLsURL Funktionenhttp_build_query

Ein Service von Reinhard Neidl - Webprogrammierung.

URL Funktionen

<<get_meta_tags

parse_url>>

http_build_query

(PHP 5)

http_build_queryErstellen eines URL-kodierten Query-Strings

Beschreibung

string http_build_query ( array $formdata [, string $numeric_prefix [, string $arg_separator ]] )

Erstellt einen URL-kodierten Query-String aus einem gegebenen assoziativen (oder indexierten) Array.

Parameter-Liste

formdata

Kann ein Array oder ein Objekt sein, das Eigenschaften enthält.

Das Array kann eine einfache eindimensionale Struktur haben, oder ein Array aus Arrays sein (die wiederum weitere Arrays enthalten können).

numeric_prefix

Wenn numerische Indizes im äußeren Array verwendet werden und ein numeric_prefix angegeben wurde, wird dieser nur den numerischen Schlüsseln im äußeren Array vorangestellt.

Dieser Weg wurde gewählt, um gültige Variablennamen zu erhalten, wenn die Daten später von PHP oder einer anderen CGI-Applikation dekodiert werden.

arg_separator

arg_separator.output wird verwendet, um die Argumente voneinander zu trennen, es sei denn, dass der Parameter angegeben ist. In diesem Falle wird letzteres verwendet.

Rückgabewerte

Gibt einen URL-kodierten String zurück.

Changelog

Version Beschreibung
5.1.2 arg_separator-Parameter hinzugefügt.
5.1.3 Eckige Klammern werden maskiert.

Beispiele

Beispiel #1 Einfache Verwendung von http_build_query()

<?php
$data 
= array('foo'=>'bar',
              
'baz'=>'boom',
              
'cow'=>'milch',
              
'php'=>'hypertext processor');

echo 
http_build_query($data); // foo=bar&baz=boom&cow=milch&php=hypertext+processor
echo http_build_query($data'''&amp;'); // foo=bar&amp;baz=boom&amp;cow=milch&amp;php=hypertext+processor
?>

Beispiel #2 http_build_query() mit numerischen Index-Elementen.

<?php
$data 
= array('foo''bar''baz''boom''kuh' => 'milch''php' =>'hypertext processor');

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

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

0=foo&1=bar&2=baz&3=boom&kuh=milch&php=hypertext+processor
meineVariable_0=foo&meineVariable_1=bar&meineVariable_2=baz&meineVariable_3=boom&kuh=milch&php=hypertext+processor

Beispiel #3 http_build_query() mit verschachtelten Arrays

<?php
$data 
= array('user'=>array('name'=>'Bob Smith',
                            
'alter'=>47,
                            
'geschlecht'=>'M',
                            
'geb'=>'5/12/1956'),
              
'hobbies'=>array('golf''opera''poker''rap'),
              
'kinder'=>array('bobby'=>array('alter'=>12,
                                               
'geschlecht'=>'M'),
                                
'sally'=>array('alter'=>8,
                                               
'geschlecht'=>'F')),
              
'CEO');

echo 
http_build_query($data'flags_');
?>

Ausgabe: (für bessere Lesbarkeit umgebrochen!)

user[name]=Bob+Smith&user[alter]=47&user[geschlecht]=M&user[geb]=5%2F12%2F1956&
hobbies[0]=golf&hobbies[1]=opera&hobbies[2]=poker&hobbies[3]=rap&
kinder[bobby][alter]=12&kinder[bobby][geschlecht]=M&kinder[sally][alter]=8&
kinder[sally][geschlecht]=F&flags_0=CEO

Hinweis:

Nur das numerische Indexelement im äußeren Array "CEO" erhält ein Prefix. Die anderen numerischen Indizes unterhalb von hobbies benötigen kein String-Prefix, um einen gültigen Variablennamen darzustellen.

Beispiel #4 Verwendung von http_build_query() mit einem Objekt

<?php
class meineKlasse {
    var 
$foo;
    var 
$baz;

    function 
meineKlasse() {
        
$this->foo 'bar';
        
$this->baz 'boom';
    }
}

$data = new meineKlasse();

echo 
http_build_query($data); // foo=bar&baz=boom

?>

Siehe auch

  • parse_str() - Überträgt einen String in Variable
  • parse_url() - Analysiert einen URL und gibt seine Bestandteile zurück
  • urlencode() - URL-kodiert einen String
  • array_walk() - Wendet eine Benutzerfunktion auf jedem Element eines Arrays an


22 BenutzerBeiträge:
- Beiträge aktualisieren...
boukeversteegh at gmail dot com
31.08.2010 16:02
When building querystrings, you often need to pass original arguments into the new querystring. An easy way to combine a bunch of default values, plus some overwrites into a new array, is using the Array operator +. This works great with http_build_query:

<?php
   
# Suppose $_GET is set like this.
    # or put some default values in here.
   
$_GET = Array( 'page' => 'item', 'id' => 14, 'action' => 'view' );
   
   
$edit_url = http_build_query( Array( 'action' => 'edit' ) + $_GET );
   
    echo
"<a href=\"$edit_url\">Edit</a>";
   
   
/* Prints
    <a href="action=edit&page=item&id=14">Edit</a>
    */
?>
v0idnull[try_to_spam_me_now] at gee-mail dot co
11.03.2010 20:51
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.
irish [-@-] ytdj [-dot-] ca
21.01.2010 22:31
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.
Edgar at goodforall dot eu
10.09.2009 12:01
The use of square brackets is not illegal in a url. It is meant for delimiting data, so it is probably valid to use them to represent an array index. From the RFC:  

The purpose of reserved characters is to provide a set of delimiting
characters that are distinguishable from other data within a URI.
URIs that differ in the replacement of a reserved character with its
corresponding percent-encoded octet are not equivalent.  Percent-
encoding a reserved character, or decoding a percent-encoded octet
that corresponds to a reserved character, will change how the URI is
interpreted by most applications.  Thus, characters in the reserved
set are protected from normalization and are therefore safe to be
used by scheme-specific and producer-specific algorithms for
delimiting data subcomponents within a URI.
netrox at aol dot com
27.08.2009 4:24
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.
Marco K. (Germany)
22.04.2009 14:40
If You use php <5 You can use this. (It works fine with complex arrays.)

<?php
if (!function_exists('http_build_query')) {
    function
http_build_query($data, $prefix='', $sep='', $key='') {
       
$ret = array();
        foreach ((array)
$data as $k => $v) {
            if (
is_int($k) && $prefix != null) {
               
$k = urlencode($prefix . $k);
            }
            if ((!empty(
$key)) || ($key === 0))  $k = $key.'['.urlencode($k).']';
            if (
is_array($v) || is_object($v)) {
               
array_push($ret, http_build_query($v, '', $sep, $k));
            } else {
               
array_push($ret, $k.'='.urlencode($v));
            }
        }
        if (empty(
$sep)) $sep = ini_get('arg_separator.output');
        return
implode($sep, $ret);
    }
// http_build_query
}//if
?>
guido dot winkelmann at pop-hannover dot net
6.08.2008 14:33
Every encoding or escaping function needs a decoding or unescaping counterpart. The counterpart for this one is apparently parse_str().

Unfortunately, this is far from obvious from reading just this manual page, and it took me some time to find out.

I think this manual page should explicitly mention parse_str() as the decoding counterpart of http_build_query().
donovan jimenez
18.10.2007 20:37
Other languages (in my case Java) allow access to multiple values for the same GET/POST parameter without the use of the brace ([]) notation.  I wanted to use this function because it was faster than my own PHP implementation that urlencoded each part of a parameter array, but I needed to be able to send something like this to a service:

...?q=foo&q=bar

obviously http_build_query() by itself would have given me:

...?q[0]=foo&q[1]=bar

So, preg_replace to the rescue:

...
$query_string = http_build_query($params);
$query_string = preg_replace('/%5B(?:[0-9]|[1-9][0-9]+)%5D=/', '=', $query_string);
...

And I get single dimension arrays encoded how I need them. This works because the '=' character can't appear non-urlencoded except for exactly where I expect it to appear (between key / value pairs).

DISCLAIMER: this workaround was only intended for getting rid of the array notation when a parameter had multiple "simple" values. More complex structures will probably be mangled.
fabrizio[AT]bibivu[DOT]com
8.09.2007 22:28
This is my own version that I was using for php <=4, hope that will help someone

this can accomplish a few things:
if called w/o parameters will return the current link
if called with the first parameter like:
  param1=a&param2=b
will return a link with the query string containing ONLY what is passed.
if called with the first parameter like:
  &param1=a&param2=b
will return a string with the current query string plus what is passed to the function

this function uses by default PHP_SELF, but if you pass the page will create the link with what you pass.
If pass secure(boolean), will create an https or http.
$url will be the actual domain.  This function will use a global variable if nothing is passed, but feel free to modify it to use the _SERVER variables.

$html is a boolean.  If true will create links with &amp; else just &
<?php
   
function create_link($query=NULL, $page=NULL, $secure=NULL, $html=NULL, $port=NULL, $url=NULL ){
        if(
$html    === NULL)            $html = true;
        if(
$url        === NULL){
            if(
$secure==true){
               
$url = $GLOBALS['_cfg']['secure_site'];
            } else {
               
$url = $GLOBALS['_cfg']['url'];
            }
        }
        if(
$query    === NULL)            $query = $_SERVER['QUERY_STRING'];
        if(
$port    === NULL && isset($_SERVER['BIBIVU-HTTPD'])){
           
$port    === _SERVER_ADMIN_PORT;
        }
        if((isset(
$_SERVER['BIBIVU-HTTPD']) || !isset($_COOKIE[session_name()])) && $this->is_crawler()===false){
           
$query = $query.($query!=''?'&':'').session_name().'='.session_id();
        }
        if(
substr($query,0,1) == '&'){
           
$query = $this->change_query(substr($query,1));
        }
        if(
$page === NULL)            $page = $_SERVER['PHP_SELF'];
       
$page = str_replace('//','/',$page);
        if(
substr($page,0,1)=='/')    $page = substr($page,1);

       
$newQry = array();

        if(
$query!=''){
           
parse_str($query, $newQuery);
            foreach(
$newQuery as $key => $item){
               
$newQry[] = $key.'='.$item;
            }
        }
        if(
$html){
           
//I create the URL in HTML
           
$query = implode('&amp;', $newQry);
        } else {
           
$query = implode('&', $newQry);
        }

        if(isset(
$_SERVER['BIBIVU-HTTPD'])){
           
$host = '';
        } elseif(
defined('_ADMIN_BIB') && _ADMIN_BIB==1){
            if(isset(
$_SERVER['HTTPS']) && $_SERVER['HTTPS']=='on' && ($secure===NULL || $secure===true )){
               
$host = 'https://';
            } else {
               
$host = 'http://';
            }
            if (
strrpos($_SERVER['HTTP_HOST'], ':') > 0){
               
$host .= substr($_SERVER['HTTP_HOST'], 0, strrpos($_SERVER['HTTP_HOST'], ':'));
            } else {
               
$host .= $_SERVER['HTTP_HOST'];
            }
        } else {
            if(
$secure==true){
               
$host = 'https://'.$url;
            } else {
               
$host = 'http://'.$url;
            }
        }
        if(
$port==NULL){
           
//check the current port used
           
$port = $_SERVER['SERVER_PORT'];
            if(
$port<=0)    $port = 80;
        }
        if(
$port!=80 && $port!=443){
           
$host .=':'.$port;
        }

        if(
$page===''){
           
$ret = $query;
        } else {
           
$ret = $host.'/'.$page.($query!=''?'?'.$query:'');
        }
        return
$ret;
    }
    function
change_query($addto_query, $queryOld = NULL){
       
// change the QUERY_STRING adding or changing the value passed
       
if ($queryOld === NULL){
           
$query1 = $_SERVER['QUERY_STRING'];
        } else {
           
$query1 = $queryOld;
        }
       
parse_str ($query1, $array1);
       
parse_str ($addto_query, $array2);
       
$newQuery = array_merge($array1, $array2);
   
        foreach(
$newQuery as $key => $item){
           
$newQry[] = $key . '=' . $item;
        }
   
        return
implode('&', $newQry);
    }
?>
valdikss at gmail dot com
27.08.2007 10:15
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);}
?>
pinkgothic at gmail dot com
27.04.2007 11:24
Be careful if you're assuming that arg_separator defaults to "&".

For me, with my xampp installation and PHP 5.2.1, this was scary:

[php.ini]
; The separator used in PHP generated URLs to separate arguments.
; Default is "&".
arg_separator.output = "&amp;"

... as it gave me a complete headache debugging something, as I expected the string length to be the length of the string my browser was displaying. I was so certain arg_separator was "&" because I'd never changed my php.ini that it took me seemingly forever to consider looking at the source code.

D'oh.

This may seem irrelevant at first (and I realise my case is an unusual way of stumbling into this issue), but since, if you run htmlspecialchars() over "&amp;", the result will be "&amp;amp;", DON'T expect a one- or two-parameter http_build_query() to return a query you still have to run through htmlspecialchars().

I suggest using the third parameter to retain your sanity.
mqchen at gmail dot com
3.02.2007 22:27
To flyingmeteor,

Your function is pleasingly adequate, however, when comparing the results from your function with the results from the actual function, it has a minor defect. If one uses a special character (e.g. øæåöä) in a key in the $data array, it is not encoded by your function, but it is by the actual one.

This is easily solved by some minor edits:
<?php
if(!function_exists('http_build_query')) {
    function
http_build_query($data,$prefix=null,$sep='',$key='') {
       
$ret    = array();
            foreach((array)
$data as $k => $v) {
               
$k    = urlencode($k);
                if(
is_int($k) && $prefix != null) {
                   
$k    = $prefix.$k;
                };
                if(!empty(
$key)) {
                   
$k    = $key."[".$k."]";
                };

                if(
is_array($v) || is_object($v)) {
                   
array_push($ret,http_build_query($v,"",$sep,$k));
                }
                else {
                   
array_push($ret,$k."=".urlencode($v));
                };
            };

        if(empty(
$sep)) {
           
$sep = ini_get("arg_separator.output");
        };

        return   
implode($sep, $ret);
    };
};
?>
Forgive my personal coding standard.
havelka at valka dot cz
22.12.2006 12:37
I think it doesnt :( when processing array let say from MySQL db, where array is list of rows (column - value), it generates the first "row" without indexes (post_subject=xxx&post_detail=yyy) while the other rows are indexed well ( 1[post_subject]=xxx&1[post_details]=yyy )

this causes confusion when the array is read back from this string (because the first line, without index is ignored (put to another variable than rest of the array), also count of this array says n+x (N = amount of rows in the array, X = amount of columns in the first row) which is wrong. The correct way should look like

0[post_subject]=xxx&0[post_detail]=yyy

for the first entry and then to continue with the rest
flyingmeteor at gmail dot com
11.12.2006 18:46
Here is another equivalent function for users that don't have PHP5 yet, it behaves the same way as the PHP5 counterpart and has one extra parameter for added functionality.

<?php
if (!function_exists('http_build_query')) {
function
http_build_query($data, $prefix='', $sep='', $key='') {
   
$ret = array();
    foreach ((array)
$data as $k => $v) {
        if (
is_int($k) && $prefix != null) $k = urlencode($prefix . $k);
        if (!empty(
$key)) $k = $key.'['.urlencode($k).']';
       
        if (
is_array($v) || is_object($v))
           
array_push($ret, http_build_query($v, '', $sep, $k));
        else   
array_push($ret, $k.'='.urlencode($v));
    }

    if (empty(
$sep)) $sep = ini_get('arg_separator.output');
    return
implode($sep, $ret);
}}
?>
Colin Guthrie
8.03.2006 16:11
I am concerned about this function's generation of [ and ] in the variable names.

From what I can gather from http://www.faqs.org/rfcs/rfc3986.html (which I believe to be the most recent RFC on the matter), the use of square brackets is illegal here.

To be sure, always use the following:
str_replace(array('[',']'), array('%5B','%5D'), http_build_query($data));

I will also submit a bug, but thought it important to inform users.
Colin Guthrie
8.03.2006 15:25
@ xangelusx
You said that "It is actually illegal to set arg_separator.output to &amp; ("and amp ;") as every character is considered a seperator according to the documentation."

I don't think this is correct. arg_separator.input maybe, but not the output. How can PHP encode my URLs (that is what this setting is used for, e.g. on URL rewriting etc.) with more than one separator?  It doesn't make sence for that variable.

I have personally used &amp; as a separate for output for years in order to create valid XHTML output via PHP.

I long ago wrote a function to do this for me, but depending on where I use the output, I sometimes want &amp; and sometimes just a plain old & (think putting the value in a href="" versus using it in a Location: header). Unfortunatly, I can see no way to deprecate my function just yet, as this built in function is lacking that distinction (an optional argument would be perfect IMO)
Ilya Rudenko
10.01.2006 8:57
Params with null value do not present in result string.

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

will produce:

test2=1
vlad_mustafin at ukr dot net
5.10.2005 14:03
Dear anonymous, i think that your example is incorrect in some places (or at least is not flexible) and shortly only in names of variables (as $c, $k, etc.) and some spaces and line foldings  :), i can explain:
1. I think that next part of code is not wanted here:
<?if (!is_array($a)) return false;?>
because you have (array)$a in foreach! It is possible but not obligatory. Or maybe better to use trigger_error for this situation.
2. You don't use urlencode on key! It's wrong because it can have also unsafe value!
<?if ($c) $k=$b."[".$k."]"; elseif (is_int($k)) $k=$b.$k;?>
this part is wrong because $k can be integer even if $c is not empty. I can want to add numeric_prefix to all indexes in array, but your example will not allow to make it. Here using of elseif is excluded, these both conditions should exist simultaneously.
3. <?http_build_query($v,$k,1);?> - In my opinion it's a very rough error. You use second parameter (as "numeric_prefix" in my example and php manual for this function) for transfer of the current key into next iteration step of recursion. Certainly it's possible and is not of principle, but very not professionally, in my opinion. I use implicit rule: one ought not to violate function logic even inside of the same function one may only expand logic. And my <?http_build_query($v, null, $tmp_key);?> allows to add numeric_prefix to all indexes in array (see point 2), i need just to put $numeric_prefix instead of null into second parameter.

Also i want to extend my previous example because we must use ini_get('arg_separator.output') instead of '&' separator!

<?
if(!function_exists('http_build_query')) {
    function
http_build_query( $formdata, $numeric_prefix = null, $key = null ) {
       
$res = array();
        foreach ((array)
$formdata as $k=>$v) {
           
$tmp_key = urlencode(is_int($k) ? $numeric_prefix.$k : $k);
            if (
$key) $tmp_key = $key.'['.$tmp_key.']';
            if (
is_array($v) || is_object($v) ) {
               
$res[] = http_build_query($v, null /* or $numeric_prefix if you want to add numeric_prefix to all indexes in array*/, $tmp_key);
            } else {
               
$res[] = $tmp_key."=".urlencode($v);
            }
           
/*
            If you want, you can write this as one string:
            $res[] = ( ( is_array($v) || is_object($v) ) ? http_build_query($v, null, $tmp_key) : $tmp_key."=".urlencode($v) );
            */
      
}
      
$separator = ini_get('arg_separator.output');
       return
implode($separator, $res);
   }
}
?>

All best!

3.10.2005 22:33
I made my very own http_build_query function quite some time ago for php 4 and below. Works exactly like the function below; but its just a bit shorter. :P

<?
function http_build_query($a,$b='',$c=0){
if (!
is_array($a)) return false;
foreach ((array)
$a as $k=>$v){
if (
$c) $k=$b."[".$k."]"; elseif (is_int($k)) $k=$b.$k;
if (
is_array($v)||is_object($v)) {$r[]=http_build_query($v,$k,1);continue;}
$r[]=$k."=".urlencode($v);
}
return
implode("&",$r);
}
?>
vlad_mustafin at ukr dot net
29.09.2005 13:31
My example of this function for PHP versions < PHP5 without any regular expressions, just cycles, recursion and standard functions. It can work with complex arrays or objects or both combined.
<?php
if(!function_exists('http_build_query')) {
    function
http_build_query( $formdata, $numeric_prefix = null, $key = null ) {
       
$res = array();
        foreach ((array)
$formdata as $k=>$v) {
           
$tmp_key = urlencode(is_int($k) ? $numeric_prefix.$k : $k);
            if (
$key) {
               
$tmp_key = $key.'['.$tmp_key.']';
            }
            if (
is_array($v) || is_object($v) ) {
               
$res[] = http_build_query($v, null, $tmp_key);
            } else {
               
$res[] = $tmp_key."=".urlencode($v);
            }
        }
        return
implode("&", $res);
    }
}
?>
php dot net at hiddemann dot org
12.05.2005 15:22
This is a workaround for PHP versions < PHP5. It does not work with complex arrays, however.

<?

if (!function_exists('http_build_query')) {
    function
http_build_query($formdata, $numeric_prefix = "")
    {
      
$arr = array();
       foreach (
$formdata as $key => $val)
        
$arr[] = urlencode($numeric_prefix.$key)."=".urlencode($val);
       return
implode($arr, "&");
    }
}

?>
aidan at php dot net
28.05.2004 5:25
This functionality is now implemented in the PEAR package PHP_Compat.

More information about using this function without upgrading your version of PHP can be found on the below link:

http://pear.php.net/package/PHP_Compat



PHP Powered Diese Seite bei php.net
The PHP manual text and comments are covered by the Creative Commons Attribution 3.0 License © the PHP Documentation Group - Impressum - mail("TO:Reinhard Neidl",...)