reference/json/functions/json-decode.xml
ce1856e7b95807615565d2f1427582e107c450a9
...
...
@@ -11,12 +11,12 @@
11
11
<methodsynopsis>
12
12
<type>mixed</type><methodname>json_decode</methodname>
13
13
<methodparam><type>string</type><parameter>json</parameter></methodparam>
14
-
<methodparam choice="opt"><type>bool</type><parameter>assoc</parameter><initializer>false</initializer></methodparam>
14
+
<methodparam choice="opt"><type class="union"><type>bool</type><type>null</type></type><parameter>associative</parameter><initializer>&null;</initializer></methodparam>
15
15
<methodparam choice="opt"><type>int</type><parameter>depth</parameter><initializer>512</initializer></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
16
+
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
17
17
</methodsynopsis>
18
18
<para>
19
-
Takes a JSON encoded string and converts it into a PHP variable.
19
+
Takes a JSON encoded string and converts it into a PHP value.
20
20
</para>
21
21
</refsect1>
22
22

...
...
@@ -37,11 +37,14 @@
37
37
</listitem>
38
38
</varlistentry>
39
39
<varlistentry>
40
-
<term><parameter>assoc</parameter></term>
40
+
<term><parameter>associative</parameter></term>
41
41
<listitem>
42
42
<para>
43
-
When &true;, returned <type>object</type>s will be converted into
44
-
associative <type>array</type>s.
43
+
When &true;, JSON objects will be returned as
44
+
associative &array;s; when &false;, JSON objects will be returned as &object;s.
45
+
When &null;, JSON objects will be returned as associative &array;s or
46
+
&object;s depending on whether <constant>JSON_OBJECT_AS_ARRAY</constant>
47
+
is set in the <parameter>flags</parameter>.
45
48
</para>
46
49
</listitem>
47
50
</varlistentry>
...
...
@@ -49,17 +52,24 @@
49
52
<term><parameter>depth</parameter></term>
50
53
<listitem>
51
54
<para>
52
-
User specified recursion depth.
55
+
Maximum nesting depth of the structure being decoded.
56
+
The value must be greater than <literal>0</literal>,
57
+
and less than or equal to <literal>2147483647</literal>.
53
58
</para>
54
59
</listitem>
55
60
</varlistentry>
56
61
<varlistentry>
57
-
<term><parameter>options</parameter></term>
62
+
<term><parameter>flags</parameter></term>
58
63
<listitem>
59
64
<para>
60
-
Bitmask of JSON decode options. Currently only
61
-
<constant>JSON_BIGINT_AS_STRING</constant>
62
-
is supported (default is to cast large integers as floats)
65
+
Bitmask of
66
+
<constant>JSON_BIGINT_AS_STRING</constant>,
67
+
<constant>JSON_INVALID_UTF8_IGNORE</constant>,
68
+
<constant>JSON_INVALID_UTF8_SUBSTITUTE</constant>,
69
+
<constant>JSON_OBJECT_AS_ARRAY</constant>,
70
+
<constant>JSON_THROW_ON_ERROR</constant>.
71
+
The behaviour of these constants is described on the
72
+
<link linkend="json.constants">JSON constants</link> page.
63
73
</para>
64
74
</listitem>
65
75
</varlistentry>
...
...
@@ -70,11 +80,67 @@
70
80
<refsect1 role="returnvalues">
71
81
&reftitle.returnvalues;
72
82
<para>
73
-
Returns the value encoded in <parameter>json</parameter> in appropriate
74
-
PHP type. Values <literal>true</literal>, <literal>false</literal> and
75
-
<literal>null</literal> are returned as &true;, &false; and &null;
76
-
respectively. &null; is returned if the <parameter>json</parameter> cannot
77
-
be decoded or if the encoded data is deeper than the recursion limit.
83
+
Returns the value encoded in <parameter>json</parameter> as an appropriate
84
+
PHP type. Unquoted values <literal>true</literal>, <literal>false</literal>
85
+
and <literal>null</literal> are returned as &true;,
86
+
&false; and &null; respectively. &null; is returned if the
87
+
<parameter>json</parameter> cannot be decoded or if the encoded data is
88
+
deeper than the nesting limit.
89
+
</para>
90
+
</refsect1>
91
+

92
+
<refsect1 role="errors">
93
+
&reftitle.errors;
94
+
<para>
95
+
If <parameter>depth</parameter> is outside the allowed range,
96
+
a <classname>ValueError</classname> is thrown as of PHP 8.0.0,
97
+
while previously, an error of level <constant>E_WARNING</constant> was raised.
98
+
</para>
99
+
</refsect1>
100
+

101
+
<refsect1 role="changelog">
102
+
&reftitle.changelog;
103
+
<para>
104
+
<informaltable>
105
+
<tgroup cols="2">
106
+
<thead>
107
+
<row>
108
+
<entry>&Version;</entry>
109
+
<entry>&Description;</entry>
110
+
</row>
111
+
</thead>
112
+
<tbody>
113
+
<row>
114
+
<entry>7.3.0</entry>
115
+
<entry>
116
+
<constant>JSON_THROW_ON_ERROR</constant>
117
+
<parameter>flags</parameter> was added.
118
+
</entry>
119
+
</row>
120
+
<row>
121
+
<entry>7.2.0</entry>
122
+
<entry>
123
+
<parameter>associative</parameter> is nullable now.
124
+
</entry>
125
+
</row>
126
+
<row>
127
+
<entry>7.2.0</entry>
128
+
<entry>
129
+
<constant>JSON_INVALID_UTF8_IGNORE</constant>, and
130
+
<constant>JSON_INVALID_UTF8_SUBSTITUTE</constant>
131
+
<parameter>flags</parameter> were added.
132
+
</entry>
133
+
</row>
134
+
<row>
135
+
<entry>7.1.0</entry>
136
+
<entry>
137
+
An empty JSON key ("") can be encoded to the empty object property
138
+
instead of using a key with value <literal>_empty_</literal>.
139
+
</entry>
140
+
</row>
141
+
</tbody>
142
+
</tgroup>
143
+
</informaltable>
78
144
</para>
79
145
</refsect1>
80
146

...
...
@@ -165,7 +231,7 @@ json_decode($bad_json); // null
165
231
<programlisting role="php">
166
232
<![CDATA[
167
233
<?php
168
-
// Encode the data.
234
+
// Encode some data with a maximum depth of 4 (array -> array -> array -> string)
169
235
$json = json_encode(
170
236
array(
171
237
1 => array(
...
...
@@ -181,20 +247,12 @@ $json = json_encode(
181
247
)
182
248
);
183
249

184
-
// Define the errors.
185
-
$constants = get_defined_constants(true);
186
-
$json_errors = array();
187
-
foreach ($constants["json"] as $name => $value) {
188
-
if (!strncmp($name, "JSON_ERROR_", 11)) {
189
-
$json_errors[$value] = $name;
190
-
}
191
-
}
192
-

193
250
// Show the errors for different depths.
194
-
foreach (range(4, 3, -1) as $depth) {
195
-
var_dump(json_decode($json, true, $depth));
196
-
echo 'Last error: ', $json_errors[json_last_error()], PHP_EOL, PHP_EOL;
197
-
}
251
+
var_dump(json_decode($json, true, 4));
252
+
echo 'Last error: ', json_last_error_msg(), PHP_EOL, PHP_EOL;
253
+

254
+
var_dump(json_decode($json, true, 3));
255
+
echo 'Last error: ', json_last_error_msg(), PHP_EOL, PHP_EOL;
198
256
?>
199
257
]]>
200
258
</programlisting>
...
...
@@ -220,10 +278,10 @@ array(1) {
220
278
}
221
279
}
222
280
}
223
-
Last error: JSON_ERROR_NONE
281
+
Last error: No error
224
282

225
283
NULL
226
-
Last error: JSON_ERROR_DEPTH
284
+
Last error: Maximum stack depth exceeded
227
285
]]>
228
286
</screen>
229
287
</example>
...
...
@@ -272,52 +330,6 @@ object(stdClass)#1 (1) {
272
330
</note>
273
331
</refsect1>
274
332

275
-
<refsect1 role="changelog">
276
-
&reftitle.changelog;
277
-
<para>
278
-
<informaltable>
279
-
<tgroup cols="2">
280
-
<thead>
281
-
<row>
282
-
<entry>&Version;</entry>
283
-
<entry>&Description;</entry>
284
-
</row>
285
-
</thead>
286
-
<tbody>
287
-
<row>
288
-
<entry>5.6.0</entry>
289
-
<entry>
290
-
Invalid non-lowercased variants of the <literal>true</literal>,
291
-
<literal>false</literal> and <literal>null</literal> literals are no
292
-
longer accepted as valid input, and will generate warnings.
293
-
</entry>
294
-
</row>
295
-
<row>
296
-
<entry>5.4.0</entry>
297
-
<entry>
298
-
The <parameter>options</parameter> parameter was added.
299
-
</entry>
300
-
</row>
301
-
<row>
302
-
<entry>5.3.0</entry>
303
-
<entry>Added the optional <parameter>depth</parameter>. The default recursion depth was increased from 128 to 512</entry>
304
-
</row>
305
-
<row>
306
-
<entry>5.2.3</entry>
307
-
<entry>The nesting limit was increased from 20 to 128</entry>
308
-
</row>
309
-
<row>
310
-
<entry>5.2.1</entry>
311
-
<entry>
312
-
Added support for JSON decoding of basic types.
313
-
</entry>
314
-
</row>
315
-
</tbody>
316
-
</tgroup>
317
-
</informaltable>
318
-
</para>
319
-
</refsect1>
320
-

321
333
<refsect1 role="seealso">
322
334
&reftitle.seealso;
323
335
<para>
...
...
@@ -328,7 +340,6 @@ object(stdClass)#1 (1) {
328
340
</para>
329
341
</refsect1>
330
342
</refentry>
331
-

332
343
<!-- Keep this comment at the end of the file
333
344
Local variables:
334
345
mode: sgml
335
346



Tools (Spanish Manual)