reference/url/functions/http-build-query.xml
c1413dcaa87de5d9954e5ed90f3612993b7cb12c
c1413dcaa87de5d9954e5ed90f3612993b7cb12c
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xml:id="function.http-build-query" xmlns="http://docbook.org/ns/docbook">
3
+
<refentry xml:id="function.http-build-query" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>http_build_query</refname>
6
6
<refpurpose>Generate URL-encoded query string</refpurpose>
...
...
@@ -10,9 +10,10 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>string</type><methodname>http_build_query</methodname>
13
-
<methodparam><type>array</type><parameter>formdata</parameter></methodparam>
14
-
<methodparam choice="opt"><type>string</type><parameter>numeric_prefix</parameter></methodparam>
15
-
<methodparam choice="opt"><type>string</type><parameter>arg_separator</parameter></methodparam>
13
+
<methodparam><type class="union"><type>array</type><type>object</type></type><parameter>data</parameter></methodparam>
14
+
<methodparam choice="opt"><type>string</type><parameter>numeric_prefix</parameter><initializer>""</initializer></methodparam>
15
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>arg_separator</parameter><initializer>&null;</initializer></methodparam>
16
+
<methodparam choice="opt"><type>int</type><parameter>encoding_type</parameter><initializer><constant>PHP_QUERY_RFC1738</constant></initializer></methodparam>
16
17
</methodsynopsis>
17
18
<para>
18
19
Generates a URL-encoded query string from the associative (or indexed)
...
...
@@ -25,14 +26,19 @@
25
26
<para>
26
27
<variablelist>
27
28
<varlistentry>
28
-
<term><parameter>formdata</parameter></term>
29
+
<term><parameter>data</parameter></term>
29
30
<listitem>
30
31
<para>
31
32
May be an array or object containing properties.
32
33
</para>
33
34
<para>
34
-
The array form may be a simple one-dimensional structure, or an array
35
-
of arrays (who in turn may contain other arrays).
35
+
If <parameter>data</parameter> is an array, it may be a simple
36
+
one-dimensional structure, or an array of arrays (which in
37
+
turn may contain other arrays).
38
+
</para>
39
+
<para>
40
+
If <parameter>data</parameter> is an object, then only public
41
+
properties will be incorporated into the result.
36
42
</para>
37
43
</listitem>
38
44
</varlistentry>
...
...
@@ -54,9 +60,30 @@
54
60
<term><parameter>arg_separator</parameter></term>
55
61
<listitem>
56
62
<para>
63
+
The argument separator. If not set or &null;,
57
64
<link linkend="ini.arg-separator.output">arg_separator.output</link>
58
-
is used to separate arguments, unless this parameter is specified,
59
-
and is then used.
65
+
is used to separate arguments.
66
+
</para>
67
+
</listitem>
68
+
</varlistentry>
69
+
<varlistentry>
70
+
<term><parameter>encoding_type</parameter></term>
71
+
<listitem>
72
+
<para>
73
+
By default, <constant>PHP_QUERY_RFC1738</constant>.
74
+
</para>
75
+
<para>
76
+
If <parameter>encoding_type</parameter> is
77
+
<constant>PHP_QUERY_RFC1738</constant>, then encoding is performed per
78
+
<link xlink:href="&url.rfc;1738">RFC 1738</link> and the
79
+
<literal>application/x-www-form-urlencoded</literal> media type, which
80
+
implies that spaces are encoded as plus (<literal>+</literal>) signs.
81
+
</para>
82
+
<para>
83
+
If <parameter>encoding_type</parameter> is
84
+
<constant>PHP_QUERY_RFC3986</constant>, then encoding is performed
85
+
according to <link xlink:href="&url.rfc;3986">RFC 3986</link>, and
86
+
spaces will be percent encoded (<literal>%20</literal>).
60
87
</para>
61
88
</listitem>
62
89
</varlistentry>
...
...
@@ -73,32 +100,24 @@
73
100
74
101
<refsect1 role="changelog">
75
102
&reftitle.changelog;
76
-
<para>
77
-
<informaltable>
78
-
<tgroup cols="2">
79
-
<thead>
80
-
<row>
81
-
<entry>&Version;</entry>
82
-
<entry>&Description;</entry>
83
-
</row>
84
-
</thead>
85
-
<tbody>
86
-
<row>
87
-
<entry>5.1.2</entry>
88
-
<entry>
89
-
The <parameter>arg_separator</parameter> parameter was added.
90
-
</entry>
91
-
</row>
92
-
<row>
93
-
<entry>5.1.3</entry>
94
-
<entry>
95
-
Square brackets are escaped.
96
-
</entry>
97
-
</row>
98
-
</tbody>
99
-
</tgroup>
100
-
</informaltable>
101
-
</para>
103
+
<informaltable>
104
+
<tgroup cols="2">
105
+
<thead>
106
+
<row>
107
+
<entry>&Version;</entry>
108
+
<entry>&Description;</entry>
109
+
</row>
110
+
</thead>
111
+
<tbody>
112
+
<row>
113
+
<entry>8.0.0</entry>
114
+
<entry>
115
+
<parameter>arg_separator</parameter> is now nullable.
116
+
</entry>
117
+
</row>
118
+
</tbody>
119
+
</tgroup>
120
+
</informaltable>
102
121
</refsect1>
103
122
104
123
<refsect1 role="examples">
...
...
@@ -108,17 +127,27 @@
108
127
<programlisting role="php">
109
128
<![CDATA[
110
129
<?php
111
-
$data = array('foo'=>'bar',
112
-
'baz'=>'boom',
113
-
'cow'=>'milk',
114
-
'php'=>'hypertext processor');
130
+
$data = array(
131
+
'foo' => 'bar',
132
+
'baz' => 'boom',
133
+
'cow' => 'milk',
134
+
'null' => null,
135
+
'php' => 'hypertext processor'
136
+
);
115
137
116
-
echo http_build_query($data); // foo=bar&baz=boom&cow=milk&php=hypertext+processor
117
-
echo http_build_query($data, '', '&'); // foo=bar&baz=boom&cow=milk&php=hypertext+processor
138
+
echo http_build_query($data) . "\n";
139
+
echo http_build_query($data, '', '&');
118
140
119
141
?>
120
142
]]>
121
143
</programlisting>
144
+
&example.outputs;
145
+
<screen>
146
+
<![CDATA[
147
+
foo=bar&baz=boom&cow=milk&php=hypertext+processor
148
+
foo=bar&baz=boom&cow=milk&php=hypertext+processor
149
+
]]>
150
+
</screen>
122
151
</example>
123
152
124
153
<example>
...
...
@@ -126,7 +155,7 @@ echo http_build_query($data, '', '&'); // foo=bar&baz=boom&cow=milk&
126
155
<programlisting role="php">
127
156
<![CDATA[
128
157
<?php
129
-
$data = array('foo', 'bar', 'baz', 'boom', 'cow' => 'milk', 'php' =>'hypertext processor');
158
+
$data = array('foo', 'bar', 'baz', null, 'boom', 'cow' => 'milk', 'php' => 'hypertext processor');
130
159
131
160
echo http_build_query($data) . "\n";
132
161
echo http_build_query($data, 'myvar_');
...
...
@@ -136,8 +165,8 @@ echo http_build_query($data, 'myvar_');
136
165
&example.outputs;
137
166
<screen>
138
167
<![CDATA[
139
-
0=foo&1=bar&2=baz&3=boom&cow=milk&php=hypertext+processor
140
-
myvar_0=foo&myvar_1=bar&myvar_2=baz&myvar_3=boom&cow=milk&php=hypertext+processor
168
+
0=foo&1=bar&2=baz&4=boom&cow=milk&php=hypertext+processor
169
+
myvar_0=foo&myvar_1=bar&myvar_2=baz&myvar_4=boom&cow=milk&php=hypertext+processor
141
170
]]>
142
171
</screen>
143
172
</example>
...
...
@@ -146,23 +175,27 @@ myvar_0=foo&myvar_1=bar&myvar_2=baz&myvar_3=boom&cow=milk&php=hypertext+processo
146
175
<programlisting role="php">
147
176
<![CDATA[
148
177
<?php
149
-
$data = array('user'=>array('name'=>'Bob Smith',
150
-
'age'=>47,
151
-
'sex'=>'M',
152
-
'dob'=>'5/12/1956'),
153
-
'pastimes'=>array('golf', 'opera', 'poker', 'rap'),
154
-
'children'=>array('bobby'=>array('age'=>12,
155
-
'sex'=>'M'),
156
-
'sally'=>array('age'=>8,
157
-
'sex'=>'F')),
158
-
'CEO');
178
+
$data = array(
179
+
'user' => array(
180
+
'name' => 'Bob Smith',
181
+
'age' => 47,
182
+
'sex' => 'M',
183
+
'dob' => '5/12/1956'
184
+
),
185
+
'pastimes' => array('golf', 'opera', 'poker', 'rap'),
186
+
'children' => array(
187
+
'bobby' => array('age'=>12, 'sex'=>'M'),
188
+
'sally' => array('age'=>8, 'sex'=>'F')
189
+
),
190
+
'CEO'
191
+
);
159
192
160
193
echo http_build_query($data, 'flags_');
161
194
?>
162
195
]]>
163
196
</programlisting>
164
197
<para>
165
-
this will output : (word wrapped for readability)
198
+
The above example will output: (word wrapped for readability)
166
199
</para>
167
200
<screen>
168
201
<![CDATA[
...
...
@@ -189,23 +222,39 @@ children%5Bsally%5D%5Bsex%5D=F&flags_0=CEO
189
222
<programlisting role="php">
190
223
<![CDATA[
191
224
<?php
192
-
class myClass {
193
-
var $foo;
194
-
var $baz;
225
+
class parentClass {
226
+
public $pub = 'publicParent';
227
+
protected $prot = 'protectedParent';
228
+
private $priv = 'privateParent';
229
+
public $pub_bar = null;
230
+
protected $prot_bar = null;
231
+
private $priv_bar = null;
195
232
196
-
function myClass() {
197
-
$this->foo = 'bar';
198
-
$this->baz = 'boom';
233
+
public function __construct(){
234
+
$this->pub_bar = new childClass();
235
+
$this->prot_bar = new childClass();
236
+
$this->priv_bar = new childClass();
199
237
}
200
238
}
201
239
202
-
$data = new myClass();
240
+
class childClass {
241
+
public $pub = 'publicChild';
242
+
protected $prot = 'protectedChild';
243
+
private $priv = 'privateChild';
244
+
}
203
245
204
-
echo http_build_query($data); // foo=bar&baz=boom
246
+
$parent = new parentClass();
205
247
248
+
echo http_build_query($parent);
206
249
?>
207
250
]]>
208
251
</programlisting>
252
+
&example.outputs;
253
+
<screen>
254
+
<![CDATA[
255
+
pub=publicParent&pub_bar%5Bpub%5D=publicChild
256
+
]]>
257
+
</screen>
209
258
</example>
210
259
</refsect1>
211
260
...
...
@@ -222,7 +271,6 @@ echo http_build_query($data); // foo=bar&baz=boom
222
271
</refsect1>
223
272
224
273
</refentry>
225
-
226
274
<!-- Keep this comment at the end of the file
227
275
Local variables:
228
276
mode: sgml
229
277