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,20 +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 there are two supported
61
-
options. The first is <constant>JSON_BIGINT_AS_STRING</constant> that
62
-
allows casting big integers to string instead of floats which is the
63
-
default. The second option is <constant>JSON_OBJECT_AS_ARRAY</constant>
64
-
that has the same effect as setting <parameter>assoc</parameter> to
65
-
&true;.
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.
66
73
</para>
67
74
</listitem>
68
75
</varlistentry>
...
...
@@ -73,11 +80,67 @@
73
80
<refsect1 role="returnvalues">
74
81
&reftitle.returnvalues;
75
82
<para>
76
-
Returns the value encoded in <parameter>json</parameter> in appropriate
77
-
PHP type. Values <literal>true</literal>, <literal>false</literal> and
78
-
<literal>null</literal> are returned as &true;, &false; and &null;
79
-
respectively. &null; is returned if the <parameter>json</parameter> cannot
80
-
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>
81
144
</para>
82
145
</refsect1>
83
146

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

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

196
250
// Show the errors for different depths.
197
-
foreach (range(4, 3, -1) as $depth) {
198
-
var_dump(json_decode($json, true, $depth));
199
-
echo 'Last error: ', $json_errors[json_last_error()], PHP_EOL, PHP_EOL;
200
-
}
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;
201
256
?>
202
257
]]>
203
258
</programlisting>
...
...
@@ -223,10 +278,10 @@ array(1) {
223
278
}
224
279
}
225
280
}
226
-
Last error: JSON_ERROR_NONE
281
+
Last error: No error
227
282

228
283
NULL
229
-
Last error: JSON_ERROR_DEPTH
284
+
Last error: Maximum stack depth exceeded
230
285
]]>
231
286
</screen>
232
287
</example>
...
...
@@ -275,79 +330,6 @@ object(stdClass)#1 (1) {
275
330
</note>
276
331
</refsect1>
277
332

278
-
<refsect1 role="changelog">
279
-
&reftitle.changelog;
280
-
<para>
281
-
<informaltable>
282
-
<tgroup cols="2">
283
-
<thead>
284
-
<row>
285
-
<entry>&Version;</entry>
286
-
<entry>&Description;</entry>
287
-
</row>
288
-
</thead>
289
-
<tbody>
290
-
<row>
291
-
<entry>7.1.0</entry>
292
-
<entry>
293
-
An empty JSON key ("") can be encoded to the empty object property
294
-
instead of using a key with value <literal>_empty_</literal>.
295
-
</entry>
296
-
</row>
297
-
<row>
298
-
<entry>7.0.0</entry>
299
-
<entry>
300
-
Rejected RFC 7159 incompatible number formats - top level
301
-
(07, 0xff, .1, -.1) and all levels ([1.], [1.e1])
302
-
</entry>
303
-
</row>
304
-
<row>
305
-
<entry>7.0.0</entry>
306
-
<entry>
307
-
An empty PHP string or value that after casting to string is an empty
308
-
string (<literal>NULL</literal>, <literal>FALSE</literal>) results
309
-
in JSON syntax error.
310
-
</entry>
311
-
</row>
312
-
<row>
313
-
<entry>5.6.0</entry>
314
-
<entry>
315
-
Invalid non-lowercased variants of the <literal>true</literal>,
316
-
<literal>false</literal> and <literal>null</literal> literals are no
317
-
longer accepted as valid input, and will generate warnings.
318
-
</entry>
319
-
</row>
320
-
<row>
321
-
<entry>5.4.0</entry>
322
-
<entry>
323
-
The <parameter>options</parameter> parameter was added.
324
-
</entry>
325
-
</row>
326
-
<row>
327
-
<entry>5.3.0</entry>
328
-
<entry>
329
-
Added the optional <parameter>depth</parameter>. The default
330
-
recursion depth was increased from 128 to 512
331
-
</entry>
332
-
</row>
333
-
<row>
334
-
<entry>5.2.3</entry>
335
-
<entry>
336
-
The nesting limit was increased from 20 to 128
337
-
</entry>
338
-
</row>
339
-
<row>
340
-
<entry>5.2.1</entry>
341
-
<entry>
342
-
Added support for JSON decoding of basic types.
343
-
</entry>
344
-
</row>
345
-
</tbody>
346
-
</tgroup>
347
-
</informaltable>
348
-
</para>
349
-
</refsect1>
350
-

351
333
<refsect1 role="seealso">
352
334
&reftitle.seealso;
353
335
<para>
...
...
@@ -358,7 +340,6 @@ object(stdClass)#1 (1) {
358
340
</para>
359
341
</refsect1>
360
342
</refentry>
361
-

362
343
<!-- Keep this comment at the end of the file
363
344
Local variables:
364
345
mode: sgml
365
346



Tools (Polish Manual)