reference/strings/functions/parse-str.xml
e35fbbaa52702ebf45c5e7284351e136ed67f3bb
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.parse-str">
3
+
<refentry xml:id="function.parse-str" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>parse_str</refname>
6
6
<refpurpose>Parses the string into variables</refpurpose>
...
...
@@ -10,30 +10,14 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>void</type><methodname>parse_str</methodname>
13
-
<methodparam><type>string</type><parameter>str</parameter></methodparam>
14
-
<methodparam choice="opt"><type>array</type><parameter role="reference">arr</parameter></methodparam>
13
+
<methodparam><type>string</type><parameter>string</parameter></methodparam>
14
+
<methodparam><type>array</type><parameter role="reference">result</parameter></methodparam>
15
15
</methodsynopsis>
16
16
<para>
17
-
Parses <parameter>str</parameter> as if it were the query string
18
-
passed via a URL and sets variables in the current scope.
17
+
Parses <parameter>string</parameter> as if it were the query string
18
+
passed via a URL and sets variables in the current scope (or in the array
19
+
if <parameter>result</parameter> is provided).
19
20
</para>
20
-
<note>
21
-
<para>
22
-
To get the current <literal>QUERY_STRING</literal>, you may use the variable
23
-
<varname>$_SERVER['QUERY_STRING']</varname>.
24
-
Also, you may want to read the section on
25
-
<link linkend="language.variables.external">variables from external
26
-
sources</link>.
27
-
</para>
28
-
</note>
29
-
<note>
30
-
<para>
31
-
The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> setting
32
-
affects the output of this function, as <function>parse_str</function> uses
33
-
the same mechanism that PHP uses to populate the <varname>$_GET</varname>,
34
-
<varname>$_POST</varname>, etc. variables.
35
-
</para>
36
-
</note>
37
21
</refsect1>
38
22

39
23
<refsect1 role="parameters">
...
...
@@ -41,7 +25,7 @@
41
25
<para>
42
26
<variablelist>
43
27
<varlistentry>
44
-
<term><parameter>str</parameter></term>
28
+
<term><parameter>string</parameter></term>
45
29
<listitem>
46
30
<para>
47
31
The input string.
...
...
@@ -49,12 +33,20 @@
49
33
</listitem>
50
34
</varlistentry>
51
35
<varlistentry>
52
-
<term><parameter>arr</parameter></term>
36
+
<term><parameter>result</parameter></term>
53
37
<listitem>
54
38
<para>
55
-
If the second parameter <parameter>arr</parameter> is present,
39
+
If the second parameter <parameter>result</parameter> is present,
56
40
variables are stored in this variable as array elements instead.
57
41
</para>
42
+

43
+
<warning>
44
+
<para>
45
+
Using this function without the <parameter>result</parameter> parameter is highly
46
+
<emphasis>DISCOURAGED</emphasis> and <emphasis>DEPRECATED</emphasis> as of PHP 7.2.
47
+
As of PHP 8.0.0, the <parameter>result</parameter> parameter is <emphasis>mandatory</emphasis>.
48
+
</para>
49
+
</warning>
58
50
</listitem>
59
51
</varlistentry>
60
52
</variablelist>
...
...
@@ -68,6 +60,37 @@
68
60
</para>
69
61
</refsect1>
70
62

63
+
<refsect1 role="changelog">
64
+
&reftitle.changelog;
65
+
<para>
66
+
<informaltable>
67
+
<tgroup cols="2">
68
+
<thead>
69
+
<row>
70
+
<entry>&Version;</entry>
71
+
<entry>&Description;</entry>
72
+
</row>
73
+
</thead>
74
+
<tbody>
75
+
<row>
76
+
<entry>8.0.0</entry>
77
+
<entry>
78
+
<parameter>result</parameter> is no longer optional.
79
+
</entry>
80
+
</row>
81
+
<row>
82
+
<entry>7.2.0</entry>
83
+
<entry>
84
+
Usage of <function>parse_str</function> without a second parameter
85
+
now emits an <constant>E_DEPRECATED</constant> notice.
86
+
</entry>
87
+
</row>
88
+
</tbody>
89
+
</tgroup>
90
+
</informaltable>
91
+
</para>
92
+
</refsect1>
93
+

71
94
<refsect1 role="examples">
72
95
&reftitle.examples;
73
96
<para>
...
...
@@ -77,16 +100,38 @@
77
100
<![CDATA[
78
101
<?php
79
102
$str = "first=value&arr[]=foo+bar&arr[]=baz";
80
-
parse_str($str);
81
-
echo $first; // value
82
-
echo $arr[0]; // foo bar
83
-
echo $arr[1]; // baz
84
103

104
+
// Recommended
85
105
parse_str($str, $output);
86
106
echo $output['first']; // value
87
107
echo $output['arr'][0]; // foo bar
88
108
echo $output['arr'][1]; // baz
89
109

110
+
// DISCOURAGED
111
+
parse_str($str);
112
+
echo $first; // value
113
+
echo $arr[0]; // foo bar
114
+
echo $arr[1]; // baz
115
+
?>
116
+
]]>
117
+
</programlisting>
118
+
</example>
119
+
</para>
120
+
<para>
121
+
Because variables in PHP can't have dots and spaces in their names,
122
+
those are converted to underscores. Same applies to naming of
123
+
respective key names in case of using this function with
124
+
<parameter>result</parameter> parameter.
125
+
<example>
126
+
<title><function>parse_str</function> name mangling</title>
127
+
<programlisting role="php">
128
+
<![CDATA[
129
+
<?php
130
+
parse_str("My Value=Something");
131
+
echo $My_Value; // Something
132
+

133
+
parse_str("My Value=Something", $output);
134
+
echo $output['My_Value']; // Something
90
135
?>
91
136
]]>
92
137
</programlisting>
...
...
@@ -94,6 +139,26 @@ echo $output['arr'][1]; // baz
94
139
</para>
95
140
</refsect1>
96
141
142
+
<refsect1 role="notes">
143
+
&reftitle.notes;
144
+

145
+
<note>
146
+
<para>
147
+
All variables created (or values returned into array if second parameter is set)
148
+
are already <function>urldecode</function>d.
149
+
</para>
150
+
</note>
151
+
<note>
152
+
<para>
153
+
To get the current <literal>QUERY_STRING</literal>, you may use the variable
154
+
<varname>$_SERVER['QUERY_STRING']</varname>.
155
+
Also, you may want to read the section on
156
+
<link linkend="language.variables.external">variables from external
157
+
sources</link>.
158
+
</para>
159
+
</note>
160
+
</refsect1>
161
+

97
162
<refsect1 role="seealso">
98
163
&reftitle.seealso;
99
164
<para>
...
...
@@ -101,14 +166,12 @@ echo $output['arr'][1]; // baz
101
166
<member><function>parse_url</function></member>
102
167
<member><function>pathinfo</function></member>
103
168
<member><function>http_build_query</function></member>
104
-
<member><function>get_magic_quotes_gpc</function></member>
105
169
<member><function>urldecode</function></member>
106
170
</simplelist>
107
171
</para>
108
172
</refsect1>
109
173

110
174
</refentry>
111
-

112
175
<!-- Keep this comment at the end of the file
113
176
Local variables:
114
177
mode: sgml
115
178



Tools (Spanish Manual)