reference/json/constants.xml
3b67c8e90cdaa14f9d1a82756dcf0000ffa8f160
...
...
@@ -1,137 +1,178 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<appendix xml:id="json.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
&reftitle.constants;
6
5
&extension.constants;
7
6
<para>
8
7
The following constants indicate the type of error returned by
9
-
<function>json_last_error</function>.
8
+
<function>json_last_error</function> or stored as the <varname>code</varname>
9
+
of a <classname>JsonException</classname>.
10
10
</para>
11
11
<variablelist>
12
12
<varlistentry xml:id="constant.json-error-none">
13
13
<term>
14
14
<constant>JSON_ERROR_NONE</constant>
15
-
(<type>integer</type>)
15
+
(<type>int</type>)
16
16
</term>
17
17
<listitem>
18
18
<simpara>
19
19
No error has occurred.
20
-
Available since PHP 5.3.0.
21
20
</simpara>
22
21
</listitem>
23
22
</varlistentry>
24
23
<varlistentry xml:id="constant.json-error-depth">
25
24
<term>
26
25
<constant>JSON_ERROR_DEPTH</constant>
27
-
(<type>integer</type>)
26
+
(<type>int</type>)
28
27
</term>
29
28
<listitem>
30
29
<simpara>
31
30
The maximum stack depth has been exceeded.
32
-
Available since PHP 5.3.0.
33
31
</simpara>
34
32
</listitem>
35
33
</varlistentry>
36
34
<varlistentry xml:id="constant.json-error-state-mismatch">
37
35
<term>
38
36
<constant>JSON_ERROR_STATE_MISMATCH</constant>
39
-
(<type>integer</type>)
37
+
(<type>int</type>)
40
38
</term>
41
39
<listitem>
42
40
<simpara>
43
41
Occurs with underflow or with the modes mismatch.
44
-
Available since PHP 5.3.0.
45
42
</simpara>
46
43
</listitem>
47
44
</varlistentry>
48
45
<varlistentry xml:id="constant.json-error-ctrl-char">
49
46
<term>
50
47
<constant>JSON_ERROR_CTRL_CHAR</constant>
51
-
(<type>integer</type>)
48
+
(<type>int</type>)
52
49
</term>
53
50
<listitem>
54
51
<simpara>
55
52
Control character error, possibly incorrectly encoded.
56
-
Available since PHP 5.3.0.
57
53
</simpara>
58
54
</listitem>
59
55
</varlistentry>
60
56
<varlistentry xml:id="constant.json-error-syntax">
61
57
<term>
62
58
<constant>JSON_ERROR_SYNTAX</constant>
63
-
(<type>integer</type>)
59
+
(<type>int</type>)
64
60
</term>
65
61
<listitem>
66
62
<simpara>
67
63
Syntax error.
68
-
Available since PHP 5.3.0.
69
64
</simpara>
70
65
</listitem>
71
66
</varlistentry>
72
67
<varlistentry xml:id="constant.json-error-utf8">
73
68
<term>
74
69
<constant>JSON_ERROR_UTF8</constant>
75
-
(<type>integer</type>)
70
+
(<type>int</type>)
76
71
</term>
77
72
<listitem>
78
73
<simpara>
79
-
Malformed UTF-8 characters, possibly incorrectly encoded. This
80
-
constant is available as of PHP 5.3.3.
74
+
Malformed UTF-8 characters, possibly incorrectly encoded.
81
75
</simpara>
82
76
</listitem>
83
77
</varlistentry>
84
78
<varlistentry xml:id="constant.json-error-recursion">
85
79
<term>
86
80
<constant>JSON_ERROR_RECURSION</constant>
87
-
(<type>integer</type>)
81
+
(<type>int</type>)
88
82
</term>
89
83
<listitem>
90
-
<para>
84
+
<simpara>
91
85
The object or array passed to <function>json_encode</function> include
92
86
recursive references and cannot be encoded.
93
87
If the <constant>JSON_PARTIAL_OUTPUT_ON_ERROR</constant> option was
94
88
given, &null; will be encoded in the place of the recursive reference.
95
-
</para>
96
-
<para>
97
-
This constant is available as of PHP 5.5.0.
98
-
</para>
89
+
</simpara>
99
90
</listitem>
100
91
</varlistentry>
101
92
<varlistentry xml:id="constant.json-error-inf-or-nan">
102
93
<term>
103
94
<constant>JSON_ERROR_INF_OR_NAN</constant>
104
-
(<type>integer</type>)
95
+
(<type>int</type>)
105
96
</term>
106
97
<listitem>
107
-
<para>
98
+
<simpara>
108
99
The value passed to <function>json_encode</function> includes either
109
100
<link linkend="language.types.float.nan"><constant>NAN</constant></link>
110
101
or <link linkend="function.is-infinite"><constant>INF</constant></link>.
111
102
If the <constant>JSON_PARTIAL_OUTPUT_ON_ERROR</constant> option was
112
103
given, <literal>0</literal> will be encoded in the place of these
113
104
special numbers.
114
-
</para>
115
-
<para>
116
-
This constant is available as of PHP 5.5.0.
117
-
</para>
105
+
</simpara>
118
106
</listitem>
119
107
</varlistentry>
120
108
<varlistentry xml:id="constant.json-error-unsupported-type">
121
109
<term>
122
110
<constant>JSON_ERROR_UNSUPPORTED_TYPE</constant>
123
-
(<type>integer</type>)
111
+
(<type>int</type>)
124
112
</term>
125
113
<listitem>
126
-
<para>
114
+
<simpara>
127
115
A value of an unsupported type was given to
128
-
<function>json_encode</function>, such as a <type>resource</type>.
116
+
<function>json_encode</function>, such as a &resource;.
129
117
If the <constant>JSON_PARTIAL_OUTPUT_ON_ERROR</constant> option was
130
118
given, &null; will be encoded in the place of the unsupported value.
131
-
</para>
132
-
<para>
133
-
This constant is available as of PHP 5.5.0.
134
-
</para>
119
+
</simpara>
120
+
</listitem>
121
+
</varlistentry>
122
+
<varlistentry xml:id="constant.json-error-invalid-property-name">
123
+
<term>
124
+
<constant>JSON_ERROR_INVALID_PROPERTY_NAME</constant>
125
+
(<type>int</type>)
126
+
</term>
127
+
<listitem>
128
+
<simpara>
129
+
A key starting with \u0000 character was in the string passed to
130
+
<function>json_decode</function> when decoding a JSON object into a PHP
131
+
object.
132
+
</simpara>
133
+
</listitem>
134
+
</varlistentry>
135
+
<varlistentry xml:id="constant.json-error-utf16">
136
+
<term>
137
+
<constant>JSON_ERROR_UTF16</constant>
138
+
(<type>int</type>)
139
+
</term>
140
+
<listitem>
141
+
<simpara>
142
+
Single unpaired UTF-16 surrogate in unicode escape contained in the
143
+
JSON string passed to <function>json_decode</function>.
144
+
</simpara>
145
+
</listitem>
146
+
</varlistentry>
147
+
</variablelist>
148
+

149
+
<para>
150
+
The following constants can be combined to form options for
151
+
<function>json_decode</function>.
152
+
</para>
153
+
<variablelist>
154
+
<varlistentry xml:id="constant.json-bigint-as-string">
155
+
<term>
156
+
<constant>JSON_BIGINT_AS_STRING</constant>
157
+
(<type>int</type>)
158
+
</term>
159
+
<listitem>
160
+
<simpara>
161
+
Decodes large integers as their original string value.
162
+
</simpara>
163
+
</listitem>
164
+
</varlistentry>
165
+
<varlistentry xml:id="constant.json-object-as-array">
166
+
<term>
167
+
<constant>JSON_OBJECT_AS_ARRAY</constant>
168
+
(<type>int</type>)
169
+
</term>
170
+
<listitem>
171
+
<simpara>
172
+
Decodes JSON objects as PHP array. This option can be added automatically
173
+
by calling <function>json_decode</function> with the second parameter
174
+
equal to &true;.
175
+
</simpara>
135
176
</listitem>
136
177
</varlistentry>
137
178
</variablelist>
...
...
@@ -144,152 +185,192 @@
144
185
<varlistentry xml:id="constant.json-hex-tag">
145
186
<term>
146
187
<constant>JSON_HEX_TAG</constant>
147
-
(<type>integer</type>)
188
+
(<type>int</type>)
148
189
</term>
149
190
<listitem>
150
191
<simpara>
151
192
All &lt; and &gt; are converted to \u003C and \u003E.
152
-
Available since PHP 5.3.0.
153
193
</simpara>
154
194
</listitem>
155
195
</varlistentry>
156
196
<varlistentry xml:id="constant.json-hex-amp">
157
197
<term>
158
198
<constant>JSON_HEX_AMP</constant>
159
-
(<type>integer</type>)
199
+
(<type>int</type>)
160
200
</term>
161
201
<listitem>
162
202
<simpara>
163
-
All &amp;s are converted to \u0026.
164
-
Available since PHP 5.3.0.
203
+
All &amp; are converted to \u0026.
165
204
</simpara>
166
205
</listitem>
167
206
</varlistentry>
168
207
<varlistentry xml:id="constant.json-hex-apos">
169
208
<term>
170
209
<constant>JSON_HEX_APOS</constant>
171
-
(<type>integer</type>)
210
+
(<type>int</type>)
172
211
</term>
173
212
<listitem>
174
213
<simpara>
175
214
All ' are converted to \u0027.
176
-
Available since PHP 5.3.0.
177
215
</simpara>
178
216
</listitem>
179
217
</varlistentry>
180
218
<varlistentry xml:id="constant.json-hex-quot">
181
219
<term>
182
220
<constant>JSON_HEX_QUOT</constant>
183
-
(<type>integer</type>)
221
+
(<type>int</type>)
184
222
</term>
185
223
<listitem>
186
224
<simpara>
187
225
All " are converted to \u0022.
188
-
Available since PHP 5.3.0.
189
226
</simpara>
190
227
</listitem>
191
228
</varlistentry>
192
229
<varlistentry xml:id="constant.json-force-object">
193
230
<term>
194
231
<constant>JSON_FORCE_OBJECT</constant>
195
-
(<type>integer</type>)
232
+
(<type>int</type>)
196
233
</term>
197
234
<listitem>
198
235
<simpara>
199
236
Outputs an object rather than an array when a non-associative array is
200
237
used. Especially useful when the recipient of the output is expecting
201
238
an object and the array is empty.
202
-
Available since PHP 5.3.0.
203
239
</simpara>
204
240
</listitem>
205
241
</varlistentry>
206
242
<varlistentry xml:id="constant.json-numeric-check">
207
243
<term>
208
244
<constant>JSON_NUMERIC_CHECK</constant>
209
-
(<type>integer</type>)
245
+
(<type>int</type>)
210
246
</term>
211
247
<listitem>
212
248
<simpara>
213
249
Encodes numeric strings as numbers.
214
-
Available since PHP 5.3.3.
215
-
</simpara>
216
-
</listitem>
217
-
</varlistentry>
218
-
<varlistentry xml:id="constant.json-bigint-as-string">
219
-
<term>
220
-
<constant>JSON_BIGINT_AS_STRING</constant>
221
-
(<type>integer</type>)
222
-
</term>
223
-
<listitem>
224
-
<simpara>
225
-
Encodes large integers as their original string value.
226
-
Available since PHP 5.4.0.
227
250
</simpara>
228
251
</listitem>
229
252
</varlistentry>
230
253
<varlistentry xml:id="constant.json-pretty-print">
231
254
<term>
232
255
<constant>JSON_PRETTY_PRINT</constant>
233
-
(<type>integer</type>)
256
+
(<type>int</type>)
234
257
</term>
235
258
<listitem>
236
259
<simpara>
237
260
Use whitespace in returned data to format it.
238
-
Available since PHP 5.4.0.
239
261
</simpara>
240
262
</listitem>
241
263
</varlistentry>
242
264
<varlistentry xml:id="constant.json-unescaped-slashes">
243
265
<term>
244
266
<constant>JSON_UNESCAPED_SLASHES</constant>
245
-
(<type>integer</type>)
267
+
(<type>int</type>)
246
268
</term>
247
269
<listitem>
248
270
<simpara>
249
271
Don't escape <literal>/</literal>.
250
-
Available since PHP 5.4.0.
251
272
</simpara>
252
273
</listitem>
253
274
</varlistentry>
254
275
<varlistentry xml:id="constant.json-unescaped-unicode">
255
276
<term>
256
277
<constant>JSON_UNESCAPED_UNICODE</constant>
257
-
(<type>integer</type>)
278
+
(<type>int</type>)
258
279
</term>
259
280
<listitem>
260
281
<simpara>
261
-
Encode multibyte Unicode characters literally (default is to escape as \uXXXX).
262
-
Available since PHP 5.4.0.
282
+
Encode multibyte Unicode characters literally (default is to escape as
283
+
\uXXXX).
263
284
</simpara>
264
285
</listitem>
265
286
</varlistentry>
266
287
<varlistentry xml:id="constant.json-partial-output-on-error">
267
288
<term>
268
289
<constant>JSON_PARTIAL_OUTPUT_ON_ERROR</constant>
269
-
(<type>integer</type>)
290
+
(<type>int</type>)
270
291
</term>
271
292
<listitem>
272
293
<simpara>
273
294
Substitute some unencodable values instead of failing.
274
-
Available since PHP 5.5.0.
275
295
</simpara>
276
296
</listitem>
277
297
</varlistentry>
278
-
<varlistentry xml:id="constant.json-preserve-zero-fraction">
298
+
<varlistentry xml:id="constant.json-preserve-zero-fraction">
279
299
<term>
280
300
<constant>JSON_PRESERVE_ZERO_FRACTION</constant>
281
-
(<type>integer</type>)
301
+
(<type>int</type>)
302
+
</term>
303
+
<listitem>
304
+
<simpara>
305
+
Ensures that &float; values are always encoded as a float value.
306
+
</simpara>
307
+
</listitem>
308
+
</varlistentry>
309
+
<varlistentry xml:id="constant.json-unescaped-line-terminators">
310
+
<term>
311
+
<constant>JSON_UNESCAPED_LINE_TERMINATORS</constant>
312
+
(<type>int</type>)
282
313
</term>
283
314
<listitem>
284
315
<simpara>
285
-
Ensures that <type>float</type> values are always encoded as a float value.
286
-
Available since PHP 5.6.6.
316
+
The line terminators are kept unescaped when
317
+
<constant>JSON_UNESCAPED_UNICODE</constant> is supplied. It uses the same
318
+
behaviour as it was before PHP 7.1 without this constant.
319
+
Available as of PHP 7.1.0.
320
+
</simpara>
321
+
</listitem>
322
+
</varlistentry>
323
+
</variablelist>
324
+

325
+
<para>
326
+
The following constants can be combined to form options for
327
+
<function>json_decode</function> and <function>json_encode</function>.
328
+
</para>
329
+
<variablelist>
330
+
<varlistentry xml:id="constant.json-invalid-utf8-ignore">
331
+
<term>
332
+
<constant>JSON_INVALID_UTF8_IGNORE</constant>
333
+
(<type>int</type>)
334
+
</term>
335
+
<listitem>
336
+
<simpara>
337
+
Ignore invalid UTF-8 characters.
338
+
Available as of PHP 7.2.0.
339
+
</simpara>
340
+
</listitem>
341
+
</varlistentry>
342
+
<varlistentry xml:id="constant.json-invalid-utf8-substitute">
343
+
<term>
344
+
<constant>JSON_INVALID_UTF8_SUBSTITUTE</constant>
345
+
(<type>int</type>)
346
+
</term>
347
+
<listitem>
348
+
<simpara>
349
+
Convert invalid UTF-8 characters to \0xfffd
350
+
(Unicode Character 'REPLACEMENT CHARACTER')
351
+
Available as of PHP 7.2.0.
352
+
</simpara>
353
+
</listitem>
354
+
</varlistentry>
355
+
<varlistentry xml:id="constant.json-throw-on-error">
356
+
<term>
357
+
<constant>JSON_THROW_ON_ERROR</constant>
358
+
(<type>int</type>)
359
+
</term>
360
+
<listitem>
361
+
<simpara>
362
+
Throws <classname>JsonException</classname> if an error occurs instead
363
+
of setting the global error state that is retrieved with
364
+
<function>json_last_error</function> and <function>json_last_error_msg</function>.
365
+
<constant>JSON_PARTIAL_OUTPUT_ON_ERROR</constant> takes precedence over
366
+
<constant>JSON_THROW_ON_ERROR</constant>.
367
+
Available as of PHP 7.3.0.
287
368
</simpara>
288
369
</listitem>
289
370
</varlistentry>
290
371
</variablelist>
291
-
</appendix>
292
372

373
+
</appendix>
293
374
<!-- Keep this comment at the end of the file
294
375
Local variables:
295
376
mode: sgml
...
...
@@ -310,4 +391,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
310
391
vim: et tw=78 syn=sgml
311
392
vi: ts=1 sw=1
312
393
-->
313
-

314
394