language-snippets.ent
21e1338e9721534c00085ff3cff25e2dd2e84dc9
21e1338e9721534c00085ff3cff25e2dd2e84dc9
...
...
@@ -1,22 +1,59 @@
1
-
<?xml version="1.0" encoding="utf-8"?>
1
+
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<!-- Keep 'em sorted -->
4
3
4
+
<!ENTITY installation.enabled.disable 'This extension is enabled by default. It may be disabled by using the following option at compile time: '>
5
+
6
+
<!-- Not used in EN anymore -->
5
7
<!ENTITY changelog.randomseed '<row xmlns="http://docbook.org/ns/docbook"><entry>4.2.0</entry><entry>The random
6
8
number generator is seeded automatically.</entry></row>'>
7
9
8
-
<!ENTITY installation.enabled.disable 'This extension is enabled by default. It may be disabled by using the following option at compile time: '>
10
+
<!ENTITY warn.deprecated.feature-5-3-0.removed-6-0-0 '<warning
11
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
12
+
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature is
13
+
highly discouraged.</simpara></warning>'>
14
+
15
+
<!ENTITY warn.deprecated.function-5-3-0.removed-6-0-0 '<warning
16
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
17
+
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature is
18
+
highly discouraged.</simpara></warning>'>
9
19
10
20
<!-- Cautions -->
11
-
<!ENTITY caution.cryptographically-insecure '<caution xmlns="http://docbook.org/ns/docbook"><para>This function does not generate cryptographically secure values, and should not be used for cryptographic purposes. If you need a cryptographically secure value, consider using <function>openssl_random_pseudo_bytes</function> instead.</para></caution>'>
21
+
<!ENTITY caution.cryptographically-insecure '<caution xmlns="http://docbook.org/ns/docbook">
22
+
<para>
23
+
This function does not generate cryptographically secure values, and <emphasis>must not</emphasis>
24
+
be used for cryptographic purposes, or purposes that require returned values to be unguessable.
25
+
</para>
26
+
<para>
27
+
If cryptographically secure randomness is required, the <classname>Random\Randomizer</classname> may be
28
+
used with the <classname>Random\Engine\Secure</classname> engine. For simple use cases, the <function>random_int</function>
29
+
and <function>random_bytes</function> functions provide a convenient and secure <acronym>API</acronym> that is backed by
30
+
the operating system’s <acronym>CSPRNG</acronym>.
31
+
</para>
32
+
</caution>'>
12
33
13
-
<!-- Notes -->
34
+
<!ENTITY caution.mt19937-tiny-seed '<caution xmlns="http://docbook.org/ns/docbook">
35
+
<para>
36
+
Because the Mt19937 (“Mersenne Twister”) engine accepts only a single 32 bit integer as the
37
+
seed, the number of possible random sequences is limited to just 2<superscript>32</superscript>
38
+
(i.e. 4,294,967,296), despite Mt19937’s huge period of 2<superscript>19937</superscript>-1.
39
+
</para>
40
+
<para>
41
+
When relying on either implicit or explicit random seeding, duplications will appear
42
+
much earlier. Duplicated seeds are expected with 50% probability after less than
43
+
80,000 randomly generated seeds according to the birthday problem. A 10% probability
44
+
of a duplicated seed happens after randomly generating roughly 30,000 seeds.
45
+
</para>
46
+
<para>
47
+
This makes Mt19937 unsuitable for applications where duplicated sequences must not happen with
48
+
more than a negligible probability. If reproducible seeding is required, both the
49
+
<classname>Random\Engine\Xoshiro256StarStar</classname> and <classname>Random\Engine\PcgOneseq128XslRr64</classname>
50
+
engines support much larger seeds that are unlikely to collide randomly. If reproducibility
51
+
is not required, the <classname>Random\Engine\Secure</classname> engine provides cryptographically
52
+
secure randomness.
53
+
</para>
54
+
</caution>'>
14
55
15
-
<!ENTITY note.regex.deprecated '<note xmlns="http://docbook.org/ns/docbook"><para>As of PHP 5.3.0, the
16
-
regex extension is deprecated in favor of the
17
-
<link linkend="book.pcre">PCRE extension</link>. Calling this function
18
-
will issue an <constant>E_DEPRECATED</constant> notice. See <link linkend="reference.pcre.pattern.posix">the list of
19
-
differences</link> for help on converting to PCRE.</para></note>'>
56
+
<!-- Notes -->
20
57
21
58
<!ENTITY note.bin-safe '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is
22
59
binary-safe.</simpara></note>'>
...
...
@@ -25,15 +62,23 @@ binary-safe.</simpara></note>'>
25
62
function are cached. See <function>clearstatcache</function> for
26
63
more details.</simpara></note>'>
27
64
28
-
<!ENTITY note.context-support '<note xmlns="http://docbook.org/ns/docbook"><simpara>Context support was added
29
-
with PHP 5.0.0. For a description of <literal>contexts</literal>, refer to
30
-
<xref linkend="book.stream"/>.</simpara></note>'>
65
+
<!ENTITY note.context-support '<para xmlns="http://docbook.org/ns/docbook">A <link linkend="stream.contexts">context stream</link>
66
+
<type>resource</type>.</para>'>
31
67
32
68
<!ENTITY note.exec-bg '<note xmlns="http://docbook.org/ns/docbook"><para>If a program is started with this function,
33
69
in order for it to continue running in the background, the output of the
34
70
program must be redirected to a file or another output stream. Failing to do so
35
71
will cause PHP to hang until the execution of the program ends.</para></note>'>
36
72
73
+
<!ENTITY note.exec-bypass-shell '<note xmlns="http://docbook.org/ns/docbook"><para>On Windows <function>exec</function>
74
+
will first start cmd.exe to launch the command. If you want to start an external program without starting cmd.exe
75
+
use <function>proc_open</function> with the <parameter>bypass_shell</parameter> option set.</para></note>'>
76
+
77
+
<!ENTITY note.extractto-windows '<note xmlns="http://docbook.org/ns/docbook"><para>Windows NTFS file systems
78
+
do not support some characters in filenames, namely <literal><|>*?":</literal>. Filenames with a trailing dot
79
+
are not supported either. Contrary to some extraction tools, this method does not replace these characters with
80
+
an underscore, but instead fails to extract such files.</para></note>'>
81
+
37
82
<!ENTITY note.func-callback '<note xmlns="http://docbook.org/ns/docbook"><simpara>Instead of a function name, an
38
83
array containing an object reference and a method name can also be
39
84
supplied.</simpara></note>'>
...
...
@@ -43,13 +88,21 @@ with functions such as <function>call_user_func</function> and <function>call_us
43
88
called if there is an uncaught exception thrown in a previous callback.</para></note>'>
44
89
45
90
<!ENTITY note.funcbyref '<note xmlns="http://docbook.org/ns/docbook"><para>If the arguments are passed by reference,
46
-
any changes to the arguments will be reflected in the values returned by this function.</para></note>'>
91
+
any changes to the arguments will be reflected in the values returned by this function. As of PHP 7
92
+
the current values will also be returned if the arguments are passed by value.</para></note>'>
47
93
48
94
<!ENTITY note.funcnoparam '<note xmlns="http://docbook.org/ns/docbook"><para>Because this function depends on the
49
95
current scope to determine parameter details, it cannot be used as a
50
96
function parameter in versions prior to 5.3.0. If this value must be passed, the results should be assigned
51
97
to a variable, and that variable should be passed.</para></note>'>
52
98
99
+
<!ENTITY note.func-named-params '<note xmlns="http://docbook.org/ns/docbook"><para>As of PHP 8.0.0, the func_*() family of
100
+
functions is intended to be mostly transparent with regard to named arguments,
101
+
by treating the arguments as if they were all passed positionally,
102
+
and missing arguments are replaced with their defaults.
103
+
This function ignores the collection of unknown named variadic arguments.
104
+
Unknown named arguments which are collected can only be accessed through the variadic parameter.</para></note>'>
105
+
53
106
<!ENTITY note.line-endings '<note xmlns="http://docbook.org/ns/docbook"><simpara>If PHP is not properly recognizing
54
107
the line endings when reading files either on or created by a Macintosh
55
108
computer, enabling the
...
...
@@ -74,33 +127,28 @@ implemented on Windows platforms.</simpara></note>'>
74
127
<!ENTITY note.no-windows.extension '<note xmlns="http://docbook.org/ns/docbook"><simpara>This extension is not
75
128
available on Windows platforms.</simpara></note>'>
76
129
77
-
<!ENTITY note.randomseed '<note xmlns="http://docbook.org/ns/docbook"><simpara>As of PHP 4.2.0, there is no need
130
+
<!ENTITY note.no-zts '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is not
131
+
available in PHP interpreters built with ZTS (Zend Thread Safety) enabled. To check whether your copy of PHP was built with ZTS enabled, use <command>php -i</command> or test the built-in constant <constant>PHP_ZTS</constant>.</simpara></note>'>
132
+
133
+
<!ENTITY note.randomseed '<note xmlns="http://docbook.org/ns/docbook"><simpara>There is no need
78
134
to seed the random number generator with <function>srand</function> or
79
-
<function>mt_srand</function> as this is now done automatically.
135
+
<function>mt_srand</function> as this is done automatically.
80
136
</simpara></note>'>
81
137
82
-
<!ENTITY note.registerglobals '<note xmlns="http://docbook.org/ns/docbook"><title>register_globals: important
83
-
note</title><para>As of PHP 4.2.0, the default value for the PHP directive
84
-
<link linkend="ini.register-globals">register_globals</link> is <emphasis>
85
-
off</emphasis>. The PHP community discourages developers from relying on this directive, and encourages the use
86
-
of other means, such as the &link.superglobals;.</para></note>'>
87
-
88
138
<!ENTITY note.is-superglobal "<note xmlns='http://docbook.org/ns/docbook'><para>This is a 'superglobal', or
89
139
automatic global, variable. This simply means that it is available in
90
140
all scopes throughout a script. There is no need to do
91
141
<command>global $variable;</command> to access it within functions or methods.
92
142
</para></note>">
93
143
94
-
<!ENTITY note.superglobals '<note xmlns="http://docbook.org/ns/docbook"><title>Superglobals: availability note
95
-
</title><para>Superglobal arrays such as <varname>$_GET</varname>,
96
-
<varname>$_POST</varname>, and <varname>$_SERVER</varname>, etc. are available
97
-
as of PHP 4.1.0. For more information, read the manual section on
98
-
&link.superglobals;</para></note>'>
99
-
100
144
<!ENTITY note.uses-ob '<note xmlns="http://docbook.org/ns/docbook"><para>When the <parameter>return</parameter> parameter
101
145
is used, this function uses internal output buffering so it cannot be used inside an
102
146
<function>ob_start</function> callback function.</para></note>'>
103
147
148
+
<!ENTITY note.uses-ob-php70 '<note xmlns="http://docbook.org/ns/docbook"><para>When the <parameter>return</parameter> parameter
149
+
is used, this function uses internal output buffering prior to PHP 7.1.0, so it cannot be used inside an
150
+
<function>ob_start</function> callback function.</para></note>'>
151
+
104
152
<!ENTITY note.filesystem-time-res '<note xmlns="http://docbook.org/ns/docbook"><para>Note that time resolution may differ
105
153
from one file system to another.</para></note>'>
106
154
...
...
@@ -116,11 +164,31 @@ from one file system to another.</para></note>'>
116
164
</note>
117
165
'>
118
166
119
-
<!ENTITY note.passwordhashing '<note xmlns="http://docbook.org/ns/docbook">
120
-
<title>Secure password hashing</title>
167
+
<!ENTITY note.sigchild '<note xmlns="http://docbook.org/ns/docbook">
121
168
<para>
122
-
It is not recommended to use this function to secure passwords, due to the fast nature of this hashing algorithm. See
123
-
<link linkend="faq.passwords.fasthash">here</link> for details.
169
+
If PHP has been compiled with --enable-sigchild, the return value of this function is undefined.
170
+
</para>
171
+
</note>
172
+
'>
173
+
174
+
<!ENTITY note.sort-unstable '<note xmlns="http://docbook.org/ns/docbook">
175
+
<para>
176
+
If two members compare as equal, they retain their original order.
177
+
Prior to PHP 8.0.0, their relative order in the sorted array was undefined.
178
+
</para>
179
+
</note>
180
+
'>
181
+
182
+
<!ENTITY note.reset-index "<note xmlns='http://docbook.org/ns/docbook'>
183
+
<para>
184
+
Resets array's internal pointer to the first element.
185
+
</para>
186
+
</note>
187
+
">
188
+
189
+
<!ENTITY note.resource-migration-8.0-dead-function '<note xmlns="http://docbook.org/ns/docbook">
190
+
<para>
191
+
This function has no effect. Prior to PHP 8.0.0, this function was used to close the resource.
124
192
</para>
125
193
</note>
126
194
'>
...
...
@@ -170,16 +238,6 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
170
238
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature
171
239
is highly discouraged.</simpara></warning>'>
172
240
173
-
<!ENTITY warn.deprecated.feature-5-3-0.removed-6-0-0 '<warning
174
-
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
175
-
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature is
176
-
highly discouraged.</simpara></warning>'>
177
-
178
-
<!ENTITY warn.deprecated.function-5-3-0.removed-6-0-0 '<warning
179
-
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
180
-
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature is
181
-
highly discouraged.</simpara></warning>'>
182
-
183
241
<!ENTITY warn.deprecated.feature-5-3-0.removed-5-4-0 '<warning
184
242
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
185
243
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0 and <emphasis>REMOVED</emphasis>
...
...
@@ -194,6 +252,117 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
194
252
<emphasis>DEPRECATED</emphasis> as of PHP 5.5.0. Relying on this feature
195
253
is highly discouraged.</simpara></warning>'>
196
254
255
+
<!ENTITY warn.deprecated.feature-5-6-0 '<warning
256
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
257
+
<emphasis>DEPRECATED</emphasis> as of PHP 5.6.0. Relying on this feature
258
+
is highly discouraged.</simpara></warning>'>
259
+
260
+
<!ENTITY warn.deprecated.feature-7-0-0 '<warning
261
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
262
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.0.0. Relying on this feature
263
+
is highly discouraged.</simpara></warning>'>
264
+
265
+
<!ENTITY warn.deprecated.feature-7-1-0 '<warning
266
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
267
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0. Relying on this feature
268
+
is highly discouraged.</simpara></warning>'>
269
+
270
+
<!ENTITY warn.deprecated.function-7-1-0 '<warning
271
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
272
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0. Relying on this function
273
+
is highly discouraged.</simpara></warning>'>
274
+
275
+
<!ENTITY warn.deprecated.function-7-0-0.removed-8-0-0 '<warning
276
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
277
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.0.0 and
278
+
<emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
279
+
is highly discouraged.</simpara></warning>'>
280
+
281
+
<!ENTITY warn.deprecated.function-7-1-0.removed-7-2-0 '<warning
282
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
283
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0 and
284
+
<emphasis>REMOVED</emphasis> as of PHP 7.2.0. Relying on this function
285
+
is highly discouraged.</simpara></warning>'>
286
+
287
+
<!ENTITY warn.deprecated.feature-7-2-0 '<warning
288
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
289
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0. Relying on this feature
290
+
is highly discouraged.</simpara></warning>'>
291
+
292
+
<!ENTITY warn.deprecated.feature-7-2-0.removed-8-0-0 '<warning
293
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
294
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this feature
295
+
is highly discouraged.</simpara></warning>'>
296
+
297
+
<!ENTITY warn.deprecated.function-7-2-0 '<warning
298
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
299
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0. Relying on this function
300
+
is highly discouraged.</simpara></warning>'>
301
+
302
+
<!ENTITY warn.deprecated.function-7-2-0.removed-8-0-0 '<warning
303
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
304
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
305
+
is highly discouraged.</simpara></warning>'>
306
+
307
+
<!ENTITY warn.deprecated.feature-7-3-0 '<warning
308
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
309
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0. Relying on this feature
310
+
is highly discouraged.</simpara></warning>'>
311
+
312
+
<!ENTITY warn.deprecated.function-7-3-0 '<warning
313
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
314
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0. Relying on this function
315
+
is highly discouraged.</simpara></warning>'>
316
+
317
+
<!ENTITY warn.deprecated.function-7-3-0.removed-8-0-0 '<warning
318
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
319
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
320
+
is highly discouraged.</simpara></warning>'>
321
+
322
+
<!ENTITY warn.deprecated.feature-7-4-0 '<warning
323
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
324
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0. Relying on this feature
325
+
is highly discouraged.</simpara></warning>'>
326
+
327
+
<!ENTITY warn.deprecated.function-7-4-0 '<warning
328
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
329
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0. Relying on this function
330
+
is highly discouraged.</simpara></warning>'>
331
+
332
+
<!ENTITY warn.deprecated.function-7-4-0.removed-8-0-0 '<warning
333
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
334
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
335
+
is highly discouraged.</simpara></warning>'>
336
+
337
+
<!ENTITY warn.feature.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook">
338
+
<simpara>This feature was <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara>
339
+
</warning>'>
340
+
341
+
<!ENTITY warn.deprecated.function-8-0-0 '<warning
342
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
343
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0. Relying on this function
344
+
is highly discouraged.</simpara></warning>'>
345
+
346
+
<!ENTITY warn.deprecated.function-8-1-0 '<warning
347
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
348
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
349
+
is highly discouraged.</simpara></warning>'>
350
+
351
+
<!ENTITY warn.deprecated.function-8-2-0 '<warning
352
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
353
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.2.0. Relying on this function
354
+
is highly discouraged.</simpara></warning>'>
355
+
356
+
<!ENTITY warn.deprecated.feature-8-3-0 '<warning
357
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
358
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this feature
359
+
is highly discouraged.</simpara></warning>'>
360
+
361
+
<!ENTITY warn.deprecated.function-8-3-0 '<warning
362
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
363
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this function
364
+
is highly discouraged.</simpara></warning>'>
365
+
197
366
<!ENTITY removed.php.future 'This deprecated feature <emphasis xmlns="http://docbook.org/ns/docbook">will</emphasis>
198
367
certainly be <emphasis xmlns="http://docbook.org/ns/docbook">removed</emphasis> in the future.'>
199
368
...
...
@@ -221,6 +390,50 @@ on this alias is highly discouraged.</simpara></warning>'>
221
390
<simpara>This function has been <emphasis>DEPRECATED</emphasis> as of PHP 5.5.0. Relying
222
391
on this function is highly discouraged.</simpara></warning>'>
223
392
393
+
<!ENTITY warn.deprecated.feature-5-5-0.removed-7-0-0 '<warning
394
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature was
395
+
<emphasis>DEPRECATED</emphasis> in PHP 5.5.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
396
+
397
+
<!ENTITY warn.deprecated.function-5-5-0.removed-7-0-0 '<warning
398
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
399
+
<emphasis>DEPRECATED</emphasis> in PHP 5.5.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
400
+
401
+
<!ENTITY warn.deprecated.function-4-1-0.removed-7-0-0 '<warning
402
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
403
+
<emphasis>DEPRECATED</emphasis> in PHP 4.1.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
404
+
405
+
<!ENTITY warn.deprecated.function-5-3-0.removed-7-0-0 '<warning
406
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
407
+
<emphasis>DEPRECATED</emphasis> in PHP 5.3.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
408
+
409
+
<!ENTITY warn.deprecated.alias-5-3-0.removed-7-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was
410
+
<emphasis>DEPRECATED</emphasis> in PHP 5.3.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
411
+
412
+
<!ENTITY warn.deprecated.feature-5-6-0.removed-7-0-0 '<warning
413
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature was
414
+
<emphasis>DEPRECATED</emphasis> in PHP 5.6.0, and
415
+
<emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
416
+
417
+
<!ENTITY warn.removed.function-7-0-0 '<warning
418
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
419
+
<emphasis>REMOVED</emphasis> in PHP 7.0.0.</simpara></warning>'>
420
+
421
+
<!ENTITY warn.removed.function-7-4-0 '<warning
422
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
423
+
<emphasis>REMOVED</emphasis> in PHP 7.4.0.</simpara></warning>'>
424
+
425
+
<!ENTITY warn.deprecated.alias-7-2-0.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was
426
+
<emphasis>DEPRECATED</emphasis> in PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
427
+
428
+
<!ENTITY warn.deprecated.alias-7-4-0.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was
429
+
<emphasis>DEPRECATED</emphasis> in PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
430
+
431
+
<!ENTITY warn.deprecated.alias-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias is
432
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
433
+
434
+
<!ENTITY warn.removed.alias-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias is
435
+
<emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
436
+
224
437
<!ENTITY warn.experimental.func '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function is
225
438
<emphasis>EXPERIMENTAL</emphasis>. The behaviour of this function, its name, and
226
439
surrounding documentation may change without notice in a future release of PHP.
...
...
@@ -228,9 +441,9 @@ This function should be used at your own risk.
228
441
</simpara></warning>'>
229
442
230
443
<!ENTITY warn.imaprecodeyaz '<warning xmlns="http://docbook.org/ns/docbook"><simpara>The <link
231
-
linkend="book.imap">IMAP</link>, <link linkend="book.recode">recode</link>,
232
-
<link linkend="book.yaz">YAZ</link> and <link linkend="book.cyrus">Cyrus</link>
233
-
extensions cannot be used in conjuction, because they
444
+
linkend="book.imap">IMAP</link>, <link linkend="book.recode">recode</link> and
445
+
<link linkend="book.yaz">YAZ</link>
446
+
extensions cannot be used in conjunction, because they
234
447
share the same internal symbols. Note: Yaz 2.0 and above does not suffer from this problem.</simpara></warning>'>
235
448
236
449
<!ENTITY warn.install.cgi '<warning xmlns="http://docbook.org/ns/docbook"><para>A server deployed in CGI mode is open
...
...
@@ -238,16 +451,16 @@ to several possible vulnerabilities. Please read our
238
451
<link linkend="security.cgi-bin">CGI security section</link> to learn how to
239
452
defend yourself from such attacks.</para></warning>'>
240
453
241
-
<!ENTITY note.magicquotes.gpc '<note xmlns="http://docbook.org/ns/docbook"><title>directive note: magic_quotes_gpc
242
-
</title><para>The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>
243
-
directive defaults to <literal>on</literal>. It essentially runs
244
-
<function>addslashes</function> on all GET, POST, and COOKIE data.
245
-
<function>stripslashes</function> may be used to remove them.</para></note>'>
246
-
247
-
<!ENTITY warn.no-win32-fopen-wrapper '<warning xmlns="http://docbook.org/ns/docbook"><para>Windows versions of PHP
248
-
prior to PHP 4.3.0 do not support access of remote files via this function,
249
-
even if <link linkend="ini.allow-url-fopen">allow_url_fopen</link> is enabled.
250
-
</para></warning>'>
454
+
<!ENTITY warn.passwordhashing '
455
+
<warning xmlns="http://docbook.org/ns/docbook">
456
+
<para>
457
+
It is not recommended to use this function to secure passwords,
458
+
due to the fast nature of this hashing algorithm. See the
459
+
<link linkend="faq.passwords.fasthash">Password Hashing FAQ</link>
460
+
for details and best practices.
461
+
</para>
462
+
</warning>
463
+
'>
251
464
252
465
<!ENTITY warn.ssl-non-standard '<warning xmlns="http://docbook.org/ns/docbook"><para>When using SSL, Microsoft IIS
253
466
will violate the protocol by closing the connection without sending a
...
...
@@ -255,35 +468,163 @@ will violate the protocol by closing the connection without sending a
255
468
Protocol Error" when you reach the end of the data. To work around this, the
256
469
value of <link linkend="ini.error-reporting">error_reporting</link> should be
257
470
lowered to a level that does not include warnings.
258
-
PHP 4.3.7 and higher can detect buggy IIS server software when you open
471
+
PHP can detect buggy IIS server software when you open
259
472
the stream using the <literal>https://</literal> wrapper and will suppress the
260
473
warning. When using <function>fsockopen</function> to create an
261
474
<literal>ssl://</literal> socket, the developer is responsible for detecting
262
475
and suppressing this warning.</para></warning>'>
263
476
477
+
<!ENTITY warn.undocumented.class '
478
+
<warning xmlns="http://docbook.org/ns/docbook">
479
+
<simpara>
480
+
This class is currently undocumented; only a list of its properties and
481
+
methods is available.
482
+
</simpara>
483
+
</warning>
484
+
'>
485
+
264
486
<!ENTITY warn.undocumented.func '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function is
265
487
currently not documented; only its argument list is available.
266
488
</simpara></warning>'>
267
489
268
490
491
+
<!-- Deprecation and removal warnings designed for use with a list of
492
+
alternatives. See en/reference/regex/functions/ereg.xml and
493
+
en/reference/regex/reference.xml for examples of these in action. -->
494
+
495
+
<!ENTITY warn.deprecated.function.4-1-0.removed.7-0-0.alternatives '
496
+
<para xmlns="http://docbook.org/ns/docbook">
497
+
This function was <emphasis>DEPRECATED</emphasis> in PHP 4.1.0, and
498
+
<emphasis>REMOVED</emphasis> in PHP 7.0.0.
499
+
</para>
500
+
<para xmlns="http://docbook.org/ns/docbook">
501
+
Alternatives to this function include:
502
+
</para>
503
+
'>
504
+
505
+
<!ENTITY warn.deprecated.feature.5-3-0.removed.7-0-0.alternatives '
506
+
<para xmlns="http://docbook.org/ns/docbook">
507
+
This feature was <emphasis>DEPRECATED</emphasis> in PHP 5.3.0, and
508
+
<emphasis>REMOVED</emphasis> in PHP 7.0.0.
509
+
</para>
510
+
<para xmlns="http://docbook.org/ns/docbook">
511
+
Alternatives to this feature include:
512
+
</para>
513
+
'>
514
+
515
+
<!ENTITY warn.deprecated.function.5-3-0.removed.7-0-0.alternatives '
516
+
<para xmlns="http://docbook.org/ns/docbook">
517
+
This function was <emphasis>DEPRECATED</emphasis> in PHP 5.3.0, and
518
+
<emphasis>REMOVED</emphasis> in PHP 7.0.0.
519
+
</para>
520
+
<para xmlns="http://docbook.org/ns/docbook">
521
+
Alternatives to this function include:
522
+
</para>
523
+
'>
524
+
525
+
<!ENTITY warn.deprecated.function.5-5-0.removed.7-0-0.alternatives '
526
+
<para xmlns="http://docbook.org/ns/docbook">
527
+
This function was <emphasis>DEPRECATED</emphasis> in PHP 5.5.0, and
528
+
<emphasis>REMOVED</emphasis> in PHP 7.0.0.
529
+
</para>
530
+
<para xmlns="http://docbook.org/ns/docbook">
531
+
Alternatives to this function include:
532
+
</para>
533
+
'>
534
+
535
+
<!ENTITY warn.removed.feature.7-0-0.alternatives '
536
+
<para xmlns="http://docbook.org/ns/docbook">
537
+
This feature was <emphasis>REMOVED</emphasis> in PHP 7.0.0.
538
+
</para>
539
+
<para xmlns="http://docbook.org/ns/docbook">
540
+
Alternatives to this feature include:
541
+
</para>
542
+
'>
543
+
544
+
<!ENTITY warn.removed.function.7-0-0.alternatives '
545
+
<para xmlns="http://docbook.org/ns/docbook">
546
+
This function was <emphasis>REMOVED</emphasis> in PHP 7.0.0.
547
+
</para>
548
+
<para xmlns="http://docbook.org/ns/docbook">
549
+
Alternatives to this function include:
550
+
</para>
551
+
'>
552
+
553
+
<!ENTITY warn.deprecated.feature.7-1-0.removed.7-2-0.alternatives '
554
+
<para xmlns="http://docbook.org/ns/docbook">
555
+
This feature was <emphasis>DEPRECATED</emphasis> in PHP 7.1.0, and
556
+
<emphasis>REMOVED</emphasis> in PHP 7.2.0.
557
+
</para>
558
+
<para xmlns="http://docbook.org/ns/docbook">
559
+
Alternatives to this feature include:
560
+
</para>
561
+
'>
562
+
563
+
<!ENTITY warn.deprecated.function.7-1-0.removed.7-2-0.alternatives '
564
+
<para xmlns="http://docbook.org/ns/docbook">
565
+
This function was <emphasis>DEPRECATED</emphasis> in PHP 7.1.0, and
566
+
<emphasis>REMOVED</emphasis> in PHP 7.2.0.
567
+
</para>
568
+
<para xmlns="http://docbook.org/ns/docbook">
569
+
Alternatives to this function include:
570
+
</para>
571
+
'>
572
+
573
+
<!ENTITY warn.deprecated.function-8-1-0.alternatives '<warning
574
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
575
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
576
+
is highly discouraged.</simpara></warning>
577
+
<para xmlns="http://docbook.org/ns/docbook">
578
+
Alternatives to this function include:
579
+
</para>
580
+
'>
581
+
269
582
<!-- Misc -->
270
583
271
584
<!ENTITY version.exists.asof 'This exists as of PHP '>
272
585
273
-
<!ENTITY version.trunk.after.53 '<emphasis xmlns="http://docbook.org/ns/docbook">This change
274
-
exists in the <link linkend="about.phpversions">development version</link> of PHP, and will
275
-
probably exist after 5.3.</emphasis>'>
276
-
277
586
<!ENTITY version.trunk.changelog 'Future'>
278
587
279
588
<!ENTITY no.function.parameters '<para xmlns="http://docbook.org/ns/docbook">This function has no parameters.</para>'>
280
589
281
590
<!ENTITY example.outputs '<para xmlns="http://docbook.org/ns/docbook">The above example will output:</para>'>
282
591
592
+
<!ENTITY example.outputs.5 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5:</para>'>
593
+
283
594
<!ENTITY example.outputs.53 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.3:</para>'>
284
595
285
596
<!ENTITY example.outputs.54 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.4:</para>'>
286
597
598
+
<!ENTITY example.outputs.55 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.5:</para>'>
599
+
600
+
<!ENTITY example.outputs.56 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.6:</para>'>
601
+
602
+
<!ENTITY example.outputs.7 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7:</para>'>
603
+
604
+
<!ENTITY example.outputs.70 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.0:</para>'>
605
+
606
+
<!ENTITY example.outputs.71 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.1:</para>'>
607
+
608
+
<!ENTITY example.outputs.72 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.2:</para>'>
609
+
610
+
<!ENTITY example.outputs.73 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.3:</para>'>
611
+
612
+
<!ENTITY example.outputs.8 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8:</para>'>
613
+
614
+
<!ENTITY example.outputs.8.similar '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8 is similar to:</para>'>
615
+
616
+
<!ENTITY example.outputs.80 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.0:</para>'>
617
+
618
+
<!ENTITY example.outputs.81 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.1:</para>'>
619
+
620
+
<!ENTITY example.outputs.82 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.2:</para>'>
621
+
622
+
<!ENTITY example.outputs.82.similar '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.2 is similar to:</para>'>
623
+
624
+
<!ENTITY example.outputs.83 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.3:</para>'>
625
+
626
+
<!ENTITY example.outputs.83.similar '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.3 is similar to:</para>'>
627
+
287
628
<!ENTITY example.outputs.32bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 32 bit machines:</para>'>
288
629
289
630
<!ENTITY example.outputs.64bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 64 bit machines:</para>'>
...
...
@@ -304,17 +645,110 @@ something similar to:</para>'>
304
645
<function>reset</function> the <type>array</type> pointer of the input array after
305
646
use.</simpara></note>'>
306
647
648
+
<!ENTITY array.changelog.by-ref '<row xmlns="http://docbook.org/ns/docbook">
649
+
<entry>8.0.0</entry>
650
+
<entry>
651
+
If <parameter>callback</parameter> expects a parameter to be passed
652
+
by reference, this function will now emit an <constant>E_WARNING</constant>.
653
+
</entry>
654
+
</row>'>
655
+
656
+
<!ENTITY array.changelog.require-only-one '<row xmlns="http://docbook.org/ns/docbook">
657
+
<entry>8.0.0</entry>
658
+
<entry>
659
+
This function can now be called with only one parameter.
660
+
Formerly, at least two parameters have been required.
661
+
</entry>
662
+
</row>'>
663
+
307
664
<!ENTITY seealso.array.sorting 'The <link xmlns="http://docbook.org/ns/docbook" linkend="array.sorting">comparison of array sorting functions</link>'>
308
665
309
-
<!ENTITY seealso.callback 'information about the <link xmlns="http://docbook.org/ns/docbook" linkend="language.types.callback">callback</link> type'>
666
+
<!ENTITY sort.flags.parameter '<varlistentry xmlns="http://docbook.org/ns/docbook">
667
+
<term><parameter>flags</parameter></term>
668
+
<listitem>
669
+
<para>
670
+
The optional second parameter <parameter>flags</parameter>
671
+
may be used to modify the sorting behavior using these values:
672
+
</para>
673
+
<para>
674
+
Sorting type flags:
675
+
<itemizedlist>
676
+
<listitem>
677
+
<simpara><constant>SORT_REGULAR</constant> - compare items normally;
678
+
the details are described in the <link linkend="language.operators.comparison">comparison operators</link> section</simpara>
679
+
</listitem>
680
+
<listitem>
681
+
<simpara><constant>SORT_NUMERIC</constant> - compare items numerically</simpara>
682
+
</listitem>
683
+
<listitem>
684
+
<simpara><constant>SORT_STRING</constant> - compare items as strings</simpara>
685
+
</listitem>
686
+
<listitem>
687
+
<simpara>
688
+
<constant>SORT_LOCALE_STRING</constant> - compare items as
689
+
strings, based on the current locale. It uses the locale,
690
+
which can be changed using <function>setlocale</function>
691
+
</simpara>
692
+
</listitem>
693
+
<listitem>
694
+
<simpara>
695
+
<constant>SORT_NATURAL</constant> - compare items as strings
696
+
using "natural ordering" like <function>natsort</function>
697
+
</simpara>
698
+
</listitem>
699
+
<listitem>
700
+
<simpara>
701
+
<constant>SORT_FLAG_CASE</constant> - can be combined
702
+
(bitwise OR) with
703
+
<constant>SORT_STRING</constant> or
704
+
<constant>SORT_NATURAL</constant> to sort strings case-insensitively
705
+
</simpara>
706
+
</listitem>
707
+
</itemizedlist>
708
+
</para>
709
+
</listitem>
710
+
</varlistentry>
711
+
'>
712
+
713
+
<!ENTITY sort.callback.description '<para xmlns="http://docbook.org/ns/docbook">
714
+
&return.callbacksort;
715
+
</para>
716
+
&callback.cmp;
717
+
<caution xmlns="http://docbook.org/ns/docbook">
718
+
<para>
719
+
Returning <emphasis>non-integer</emphasis> values from the comparison
720
+
function, such as <type>float</type>, will result in an internal cast to
721
+
<type>int</type> of the callback's return value. So values such as
722
+
<literal>0.99</literal> and <literal>0.1</literal> will both be cast to an
723
+
integer value of <literal>0</literal>, which will compare such values as equal.
724
+
</para>
725
+
</caution>'>
310
726
311
-
<!ENTITY avail.register-long-arrays 'As of PHP 5.0.0, the long PHP
312
-
<link xmlns="http://docbook.org/ns/docbook" linkend="language.variables.predefined">predefined variable</link>
313
-
arrays may be disabled with the
314
-
<link xmlns="http://docbook.org/ns/docbook" linkend="ini.register-long-arrays">register_long_arrays</link>
315
-
directive.'>
727
+
<!ENTITY sort.callback.description.presort '<caution xmlns="http://docbook.org/ns/docbook">
728
+
<para>
729
+
The sorting callback must handle any value from any array in any order,
730
+
regardless of the order they were originally provided.
731
+
This is because each individual array is first sorted before being compared against other arrays.
316
732
317
-
<!ENTITY ini.shorthandbytes '<simpara xmlns="http://docbook.org/ns/docbook">When an <type>integer</type> is used, the
733
+
For example:
734
+
<programlisting role="php">
735
+
<![CDATA[
736
+
<?php
737
+
$arrayA = ["string", 1];
738
+
$arrayB = [["value" => 1]];
739
+
// $item1 and $item2 can be any of "string", 1 or ["value" => 1]
740
+
$compareFunc = static function ($item1, $item2) {
741
+
$value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);
742
+
$value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);
743
+
return $value1 <=> $value2;
744
+
};
745
+
?>
746
+
]]>
747
+
</programlisting>
748
+
</para>
749
+
</caution>'>
750
+
751
+
<!ENTITY ini.shorthandbytes '<simpara xmlns="http://docbook.org/ns/docbook">When an <type>int</type> is used, the
318
752
value is measured in bytes. Shorthand notation, as described
319
753
in <link linkend="faq.using.shorthandbytes">this FAQ</link>, may also be used.
320
754
</simpara>'>
...
...
@@ -333,25 +767,27 @@ function is not recommended, as it may be removed from PHP in the future.
333
767
334
768
<!ENTITY ext.windows.path.dll 'In order for this extension to work, there are
335
769
<acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> files that must be available to the Windows
336
-
system <literal xmlns="http://docbook.org/ns/docbook">PATH</literal>. For information on how to do this, see the
770
+
system <envar xmlns="http://docbook.org/ns/docbook">PATH</envar>. For information on how to do this, see the
337
771
<acronym xmlns="http://docbook.org/ns/docbook">FAQ</acronym> entitled "<link
338
772
xmlns="http://docbook.org/ns/docbook" linkend="faq.installation.addtopath">How do I add my PHP directory to the PATH
339
773
on Windows</link>". Although copying DLL
340
774
files from the PHP folder into the Windows system directory also works
341
775
(because the system directory is by default in the system's
342
-
<literal xmlns="http://docbook.org/ns/docbook">PATH</literal>), this is not recommended.
776
+
<envar xmlns="http://docbook.org/ns/docbook">PATH</envar>), this is not recommended.
343
777
<emphasis xmlns="http://docbook.org/ns/docbook">This extension requires the following files to be in the
344
-
<literal>PATH</literal>:</emphasis> '>
778
+
<envar>PATH</envar>:</emphasis> '>
345
779
346
780
<!ENTITY manual.migration.seealso 'See also the migration guides for PHP versions'>
347
781
348
-
<!ENTITY style.oop 'Object oriented style'>
782
+
<!ENTITY style.oop 'Object-oriented style'>
349
783
<!ENTITY style.procedural 'Procedural style'>
350
784
351
785
<!ENTITY resource '<link xmlns="http://docbook.org/ns/docbook" linkend="language.types.resource">resource</link>'>
352
786
353
787
<!ENTITY foreach '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.foreach">foreach</link>'>
354
788
789
+
<!ENTITY match '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.match">match</link>'>
790
+
355
791
<!ENTITY yield '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.yield">yield</link>'>
356
792
357
793
<!ENTITY parameter.context 'Refer to the <link xmlns="http://docbook.org/ns/docbook" linkend="context">context</link>
...
...
@@ -362,13 +798,24 @@ searched for within the <link xmlns="http://docbook.org/ns/docbook" linkend="ini
362
798
363
799
<!-- Returns -->
364
800
801
+
<!ENTITY return.type.true '<row xmlns="http://docbook.org/ns/docbook">
802
+
<entry>8.2.0</entry>
803
+
<entry>
804
+
The return type is &true; now; previously, it was <type>bool</type>.
805
+
</entry>
806
+
</row>'>
807
+
365
808
<!ENTITY return.falseforfailure ' or &false; on failure'>
366
809
<!ENTITY return.falseforfailure.style.procedural '&style.procedural; returns &false; on failure.'>
367
810
368
811
<!ENTITY return.success 'Returns &true; on success&return.falseforfailure;.'>
369
812
813
+
<!ENTITY return.nullorfalse 'Returns &null; on success&return.falseforfailure;.'>
814
+
370
815
<!ENTITY return.void 'No value is returned.'>
371
816
817
+
<!ENTITY return.true.always 'Always returns &true;.'>
818
+
372
819
<!ENTITY return.callbacksort 'The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.'>
373
820
374
821
<!ENTITY return.falseproblem '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function may
...
...
@@ -379,6 +826,42 @@ information. Use <link linkend="language.operators.comparison">the ===
379
826
operator</link> for testing the return value of this
380
827
function.</simpara></warning>'>
381
828
829
+
<!-- Standard -->
830
+
<!ENTITY standard.changelog.calling-on-objects '<row xmlns="http://docbook.org/ns/docbook">
831
+
<entry>8.1.0</entry>
832
+
<entry>
833
+
Calling this function on &object;s is deprecated.
834
+
Either convert the &object; to an &array; using <function>get_mangled_object_vars</function> first, or use the methods
835
+
provided by a class that implements <interfacename>Iterator</interfacename>, such as <classname>ArrayIterator</classname>, instead.
836
+
</entry>
837
+
</row>
838
+
<row xmlns="http://docbook.org/ns/docbook">
839
+
<entry>7.4.0</entry>
840
+
<entry>
841
+
Instances of <link xmlns="http://docbook.org/ns/docbook" linkend="book.spl">SPL</link> classes are now treated like empty objects that have no properties instead of calling the <interfacename>Iterator</interfacename> method with the same name as this function.
842
+
</entry>
843
+
</row>
844
+
'>
845
+
846
+
<!ENTITY standard.changelog.binary-safe-string-comparison '<row xmlns="http://docbook.org/ns/docbook">
847
+
<entry>8.2.0</entry>
848
+
<entry>
849
+
This function now returns <literal>-1</literal> or <literal>1</literal>,
850
+
where it previously returned a negative or positive number.
851
+
</entry>
852
+
</row>
853
+
'>
854
+
855
+
<!-- FileInfo -->
856
+
<!ENTITY fileinfo.parameters.finfo '<para xmlns="http://docbook.org/ns/docbook">An <classname>finfo</classname> instance, returned by <function>finfo_open</function>.</para>'>
857
+
<!ENTITY fileinfo.changelog.finfo-object '<row xmlns="http://docbook.org/ns/docbook">
858
+
<entry>8.1.0</entry>
859
+
<entry>
860
+
The <parameter>finfo</parameter> parameter expects an <classname>finfo</classname>
861
+
instance now; previously, a &resource; was expected.
862
+
</entry>
863
+
</row>'>
864
+
382
865
<!-- OpenSSL -->
383
866
<!ENTITY openssl.param.x509 '<varlistentry xmlns="http://docbook.org/ns/docbook">
384
867
<term><parameter>x509</parameter></term>
...
...
@@ -389,41 +872,105 @@ function.</simpara></warning>'>
389
872
</listitem>
390
873
</varlistentry>'>
391
874
875
+
<!ENTITY openssl.param.csr '<varlistentry xmlns="http://docbook.org/ns/docbook">
876
+
<term><parameter>csr</parameter></term>
877
+
<listitem>
878
+
<para>
879
+
See <link linkend="openssl.certparams">CSR parameters</link> for a list of valid values.
880
+
</para>
881
+
</listitem>
882
+
</varlistentry>'>
883
+
884
+
<!ENTITY openssl.param.key '<varlistentry xmlns="http://docbook.org/ns/docbook">
885
+
<term><parameter>key</parameter></term>
886
+
<listitem>
887
+
<para>
888
+
See <link linkend="openssl.certparams">Public/Private Key parameters</link> for a list of valid values.
889
+
</para>
890
+
</listitem>
891
+
</varlistentry>'>
892
+
392
893
<!-- Image (GD) Notes -->
393
894
<!ENTITY note.config.t1lib '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available
394
895
if PHP is compiled using <option role="configure">--with-t1lib[=DIR]</option>.
395
896
</simpara></note>'>
396
897
397
-
<!ENTITY note.config.jpeg '<note xmlns="http://docbook.org/ns/docbook"><simpara>JPEG support is only available if
398
-
PHP was compiled against GD-1.8 or later.</simpara></note>'>
399
-
400
-
<!ENTITY note.config.wbmp '<note xmlns="http://docbook.org/ns/docbook"><simpara>WBMP support is only available if
401
-
PHP was compiled against GD-1.8 or later.</simpara></note>'>
402
-
403
-
<!ENTITY note.bundled.gd '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available if
404
-
PHP is compiled with the bundled version of the GD library.</simpara></note>'>
405
-
406
898
<!ENTITY note.freetype '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available if
407
899
PHP is compiled with freetype support (<option role="configure">--with-freetype-dir=DIR</option>)
408
900
</simpara></note>'>
409
901
410
-
<!ENTITY note.gd.2 '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function requires GD 2.0.1 or later (2.0.28 or later is recommended).</simpara></note>'>
411
-
412
902
<!ENTITY note.gd.notrequired '<note xmlns="http://docbook.org/ns/docbook"><para>This function does not require the GD image library.</para></note>'>
413
903
414
904
<!ENTITY note.gd.interpolation '<note xmlns="http://docbook.org/ns/docbook"><para>This function is affected by the interpolation method set by <function>imagesetinterpolation</function>.</para></note>'>
415
905
416
-
<!ENTITY gd.image.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
417
-
image</parameter></term><listitem><para>An image resource, returned by one of the image creation functions,
906
+
<!ENTITY gd.image.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
907
+
<parameter>image</parameter></term><listitem><para>A <classname>GdImage</classname> object, returned by one of the image creation functions,
418
908
such as <function>imagecreatetruecolor</function>.</para></listitem></varlistentry>'>
419
909
420
-
<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
421
-
font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in
422
-
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or any of your
423
-
own font identifiers registered with <function>imageloadfont</function>.
424
-
</para></listitem></varlistentry>'>
425
-
426
-
<!ENTITY gd.return.identifier 'Returns an image resource identifier on success, &false; on errors.'>
910
+
<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
911
+
<parameter>font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in
912
+
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or <classname>GdFont</classname> instance,
913
+
returned by <function>imageloadfont</function>.</para></listitem></varlistentry>'>
914
+
915
+
<!ENTITY gd.changelog.gdfont-instance '<row xmlns="http://docbook.org/ns/docbook">
916
+
<entry>8.1.0</entry>
917
+
<entry>
918
+
The <parameter>font</parameter> parameter now accepts both an <classname>GdFont</classname> instance
919
+
and an &integer;; previously only &integer; was accepted.
920
+
</entry>
921
+
</row>'>
922
+
923
+
<!ENTITY gd.ttf.fontfile "
924
+
<varlistentry xmlns='http://docbook.org/ns/docbook'>
925
+
<term><parameter>fontfile</parameter></term>
926
+
<listitem>
927
+
<para>
928
+
The path to the TrueType font you wish to use.
929
+
</para>
930
+
<para>
931
+
Depending on which version of the GD library PHP is using, <emphasis>when
932
+
<parameter>fontfile</parameter> does not begin with a leading
933
+
<literal>/</literal> then <literal>.ttf</literal> will be appended</emphasis>
934
+
to the filename and the library will attempt to search for that
935
+
filename along a library-defined font path.
936
+
</para>
937
+
<para>
938
+
When using versions of the GD library lower than 2.0.18, a <literal>space</literal> character,
939
+
rather than a semicolon, was used as the 'path separator' for different font files.
940
+
Unintentional use of this feature will result in the warning message:
941
+
<literal>Warning: Could not find/open font</literal>. For these affected versions, the
942
+
only solution is moving the font to a path which does not contain spaces.
943
+
</para>
944
+
<para>
945
+
In many cases where a font resides in the same directory as the script using it
946
+
the following trick will alleviate any include problems.
947
+
<programlisting role='php'>
948
+
<![CDATA[
949
+
<?php
950
+
// Set the environment variable for GD
951
+
putenv('GDFONTPATH=' . realpath('.'));
952
+
953
+
// Name the font to be used (note the lack of the .ttf extension)
954
+
$font = 'SomeFont';
955
+
?>
956
+
]]>
957
+
</programlisting>
958
+
</para>
959
+
<note>
960
+
<para>
961
+
Note that <link linkend='ini.open-basedir'>open_basedir</link> does
962
+
<emphasis>not</emphasis> apply to <parameter>fontfile</parameter>.
963
+
</para>
964
+
</note>
965
+
</listitem>
966
+
</varlistentry>
967
+
">
968
+
969
+
<!ENTITY gd.return.identifier 'Returns an image object on success, &false; on errors.'>
970
+
971
+
<!ENTITY gd.return.trueonerror '<caution xmlns="http://docbook.org/ns/docbook"><simpara>However, if libgd fails to output the image, this function returns &true;.</simpara></caution>'>
972
+
973
+
<!ENTITY gd.identifier.color "A color identifier created with <function xmlns='http://docbook.org/ns/docbook'>imagecolorallocate</function>.">
427
974
428
975
<!ENTITY gd.value.red 'Value of red component.'>
429
976
...
...
@@ -435,40 +982,223 @@ own font identifiers registered with <function>imageloadfont</function>.
435
982
436
983
<!ENTITY gd.source.width 'Source width.'>
437
984
438
-
<!ENTITY gd.image.path 'The path to save the file to. If not set or &null;, the raw image stream will be outputted directly.'>
985
+
<!ENTITY gd.image.path 'The path or an open stream resource (which is automatically closed after this function returns) to save the file to. If not set or &null;, the raw image stream will be output directly.'>
439
986
440
987
<!ENTITY gd.image.new 'Create a new image from file or URL'>
441
988
442
-
<!ENTITY gd.image.source 'Source image link resource.'>
989
+
<!ENTITY gd.image.source 'Source image resource.'>
443
990
444
-
<!ENTITY gd.image.destination 'Destination image link resource.'>
991
+
<!ENTITY gd.image.destination 'Destination image resource.'>
445
992
446
993
<!ENTITY gd.image.output 'Output image to browser or file'>
447
994
448
995
<!ENTITY gd.image.colors 'If you created the image from a file, only colors used in the image are resolved. Colors present only in the palette are not resolved.'>
449
996
450
-
<!ENTITY gd.font.size 'The font size. Depending on your version of GD, this should be specified as the pixel size (GD1) or point size (GD2).'>
997
+
<!ENTITY gd.font.size 'The font size in points.'>
998
+
999
+
<!ENTITY gd.constants.types '<simpara xmlns="http://docbook.org/ns/docbook">
1000
+
Used as a return value by <function>imagetypes</function>
1001
+
</simpara>'>
1002
+
1003
+
<!ENTITY gd.constants.color '<simpara xmlns="http://docbook.org/ns/docbook">
1004
+
Special color option which can be used instead of a color allocated with
1005
+
<function>imagecolorallocate</function> or
1006
+
<function>imagecolorallocatealpha</function>.
1007
+
</simpara>'>
1008
+
1009
+
<!ENTITY gd.constants.affine '<simpara xmlns="http://docbook.org/ns/docbook">
1010
+
An affine transformation type constant used by the <function>imageaffinematrixget</function> function.
1011
+
</simpara>'>
1012
+
1013
+
<!ENTITY gd.constants.arc '<simpara xmlns="http://docbook.org/ns/docbook">
1014
+
A style constant used by the <function>imagefilledarc</function> function.
1015
+
</simpara>'>
1016
+
1017
+
<!ENTITY gd.constants.gd2 '<simpara xmlns="http://docbook.org/ns/docbook">
1018
+
A type constant used by the <function>imagegd2</function> function.
1019
+
</simpara>'>
1020
+
1021
+
<!ENTITY gd.constants.effect '<simpara xmlns="http://docbook.org/ns/docbook">
1022
+
Alpha blending effect used by the <function>imagelayereffect</function> function.
1023
+
</simpara>'>
1024
+
1025
+
<!ENTITY gd.constants.filter '<simpara xmlns="http://docbook.org/ns/docbook">
1026
+
Special GD filter used by the <function>imagefilter</function> function.
1027
+
</simpara>'>
1028
+
1029
+
<!ENTITY gd.constants.type '<simpara xmlns="http://docbook.org/ns/docbook">
1030
+
Image type constant used by the <function>image_type_to_mime_type</function>
1031
+
and <function>image_type_to_extension</function> functions.
1032
+
</simpara>'>
1033
+
1034
+
<!ENTITY gd.constants.png-filter '<simpara xmlns="http://docbook.org/ns/docbook">
1035
+
A special PNG filter, used by the <function>imagepng</function> function.
1036
+
</simpara>'>
1037
+
1038
+
<!ENTITY gd.constants.flip '<simpara xmlns="http://docbook.org/ns/docbook">
1039
+
Used together with <function>imageflip</function>, available as of PHP 5.5.0.
1040
+
</simpara>'>
1041
+
1042
+
<!ENTITY gd.constants.interpolation '<simpara xmlns="http://docbook.org/ns/docbook">
1043
+
Used together with <function>imagesetinterpolation</function>, available as of PHP 5.5.0.
1044
+
</simpara>'>
1045
+
1046
+
<!ENTITY gd.changlog.t1lib '<row xmlns="http://docbook.org/ns/docbook">
1047
+
<entry>7.0.0</entry><entry>T1Lib support was removed from PHP, thus this function was removed.</entry>
1048
+
</row>'>
1049
+
1050
+
<!ENTITY gd.deprecated.gd-formats '<warning xmlns="http://docbook.org/ns/docbook"><simpara>The GD
1051
+
and GD2 image formats are proprietary image formats of libgd. They have to be regarded
1052
+
<emphasis>obsolete</emphasis>, and should only be used for development and testing
1053
+
purposes.</simpara></warning>'>
1054
+
1055
+
<!ENTITY gd.changelog.image-param '<row xmlns="http://docbook.org/ns/docbook">
1056
+
<entry>8.0.0</entry>
1057
+
<entry>
1058
+
<parameter>image</parameter> expects a <classname>GdImage</classname>
1059
+
instance now; previously, a valid <literal>gd</literal> <type>resource</type> was expected.
1060
+
</entry>
1061
+
</row>'>
451
1062
452
1063
<!-- DBM notes -->
453
1064
454
-
<!ENTITY dbm.dbm-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
455
-
dbm_identifier</parameter></term><listitem><para>The DBM link identifier,
1065
+
<!ENTITY dbm.dbm-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1066
+
<parameter>dbm_identifier</parameter></term><listitem><para>The DBM link identifier,
456
1067
returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
457
1068
1069
+
<!-- JSON notes -->
1070
+
1071
+
<!ENTITY json.implementation.superset '
1072
+
<note xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
1073
+
<para>
1074
+
PHP implements a superset of JSON as specified in the original
1075
+
<link xlink:href="&url.rfc;7159">RFC 7159</link>.
1076
+
</para>
1077
+
</note>
1078
+
'>
1079
+
458
1080
<!-- cURL notes -->
459
1081
460
-
<!ENTITY curl.ch.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>ch</parameter>
1082
+
<!ENTITY curl.ch.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>handle</parameter>
461
1083
</term><listitem><para>A cURL handle returned by
462
1084
<function>curl_init</function>.</para></listitem></varlistentry>'>
463
1085
464
-
<!ENTITY curl.mh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>mh</parameter>
1086
+
<!ENTITY curl.mh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>multi_handle</parameter>
465
1087
</term><listitem><para>A cURL multi handle returned by
466
1088
<function>curl_multi_init</function>.</para></listitem></varlistentry>'>
467
1089
1090
+
<!ENTITY curl.sh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>share_handle</parameter>
1091
+
</term><listitem><para>A cURL share handle returned by
1092
+
<function>curl_share_init</function>.</para></listitem></varlistentry>'>
1093
+
1094
+
<!ENTITY curl.changelog.handle-param '<row xmlns="http://docbook.org/ns/docbook">
1095
+
<entry>8.0.0</entry>
1096
+
<entry>
1097
+
<parameter>handle</parameter> expects a <classname>CurlHandle</classname>
1098
+
instance now; previously, a <type>resource</type> was expected.
1099
+
</entry>
1100
+
</row>'>
1101
+
1102
+
<!ENTITY curl.changelog.multi-handle-param '<row xmlns="http://docbook.org/ns/docbook">
1103
+
<entry>8.0.0</entry>
1104
+
<entry>
1105
+
<parameter>multi_handle</parameter> expects a <classname>CurlMultiHandle</classname>
1106
+
instance now; previously, a <type>resource</type> was expected.
1107
+
</entry>
1108
+
</row>'>
1109
+
1110
+
<!ENTITY curl.changelog.share-handle-param '<row xmlns="http://docbook.org/ns/docbook">
1111
+
<entry>8.0.0</entry>
1112
+
<entry>
1113
+
<parameter>share_handle</parameter> expects a <classname>CurlShareHandle</classname>
1114
+
instance now; previously, a <type>resource</type> was expected.
1115
+
</entry>
1116
+
</row>'>
1117
+
1118
+
<!-- dbase notes -->
1119
+
1120
+
<!ENTITY dbase.type-conversion '<para xmlns="http://docbook.org/ns/docbook">
1121
+
Each field is converted to the appropriate PHP type, except:
1122
+
<itemizedlist>
1123
+
<listitem>
1124
+
<simpara>
1125
+
Dates are left as strings.
1126
+
</simpara>
1127
+
</listitem>
1128
+
<listitem>
1129
+
<simpara>
1130
+
DateTime values are converted to strings.
1131
+
</simpara>
1132
+
</listitem>
1133
+
<listitem>
1134
+
<simpara>
1135
+
Integers outside the range
1136
+
<constant>PHP_INT_MIN</constant>..<constant>PHP_INT_MAX</constant> are
1137
+
returned as strings.
1138
+
</simpara>
1139
+
</listitem>
1140
+
<listitem>
1141
+
<simpara>
1142
+
Before dbase 7.0.0, booleans (<literal>L</literal>) were converted to <literal>1</literal> or
1143
+
<literal>0</literal>.
1144
+
</simpara>
1145
+
</listitem>
1146
+
</itemizedlist>
1147
+
</para>'>
1148
+
1149
+
<!-- enchant entities -->
1150
+
1151
+
<!ENTITY enchant.param.broker '<varlistentry xmlns="http://docbook.org/ns/docbook">
1152
+
<term><parameter>broker</parameter></term>
1153
+
<listitem>
1154
+
<para>
1155
+
An Enchant broker returned by <function>enchant_broker_init</function>.
1156
+
</para>
1157
+
</listitem>
1158
+
</varlistentry>'>
1159
+
1160
+
<!ENTITY enchant.param.dictionary '<varlistentry xmlns="http://docbook.org/ns/docbook">
1161
+
<term><parameter>dictionary</parameter></term>
1162
+
<listitem>
1163
+
<para>
1164
+
An Enchant dictionary returned by <function>enchant_broker_request_dict</function>
1165
+
or <function>enchant_broker_request_pwl_dict</function>.
1166
+
</para>
1167
+
</listitem>
1168
+
</varlistentry>'>
1169
+
1170
+
<!ENTITY enchant.changelog.broker-param '<row xmlns="http://docbook.org/ns/docbook">
1171
+
<entry>8.0.0</entry>
1172
+
<entry>
1173
+
<parameter>broker</parameter> expects an <classname>EnchantBroker</classname> instance now;
1174
+
previoulsy, a &resource; was expected.
1175
+
</entry>
1176
+
</row>'>
1177
+
1178
+
<!ENTITY enchant.changelog.dictionary-param '<row xmlns="http://docbook.org/ns/docbook">
1179
+
<entry>8.0.0</entry>
1180
+
<entry>
1181
+
<parameter>dictionary</parameter> expects an <classname>EnchantDictionary</classname> instance now;
1182
+
previoulsy, a &resource; was expected.
1183
+
</entry>
1184
+
</row>'>
1185
+
468
1186
<!-- IMAP notes -->
469
1187
470
-
<!ENTITY imap.imap-stream.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
471
-
imap_stream</parameter></term><listitem><para>An IMAP stream returned by
1188
+
<!ENTITY imap.changelog.imap-param '<row xmlns="http://docbook.org/ns/docbook">
1189
+
<entry>8.1.0</entry>
1190
+
<entry>
1191
+
The <parameter>imap</parameter> parameter expects an <classname>IMAP\Connection</classname>
1192
+
instance now; previously, a valid <literal>imap</literal> &resource; was expected.
1193
+
</entry>
1194
+
</row>'>
1195
+
1196
+
<!ENTITY imap.imap-parameter.imap '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1197
+
<parameter>imap</parameter></term><listitem><para>An <classname>IMAP\Connection</classname> instance.</para></listitem></varlistentry>'>
1198
+
1199
+
<!-- Deprecated -->
1200
+
<!ENTITY imap.imap-stream.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1201
+
<parameter>imap</parameter></term><listitem><para>An IMAP stream returned by
472
1202
<function>imap_open</function>.</para></listitem></varlistentry>'>
473
1203
474
1204
<!ENTITY imap.pattern '<para xmlns="http://docbook.org/ns/docbook">Specifies where in the mailbox hierarchy
...
...
@@ -484,34 +1214,158 @@ means to return the current level only.
484
1214
parameter will return only the top level
485
1215
mailboxes; '<literal>~/mail/%</literal>' on <literal>UW_IMAPD</literal> will return every mailbox in the <filename>~/mail</filename> directory, but none in subfolders of that directory.</para>'>
486
1216
1217
+
<!ENTITY imap.mailboxname.insecure '<warning xmlns="http://docbook.org/ns/docbook"><simpara>
1218
+
Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unless
1219
+
<link linkend="ini.imap.enable-insecure-rsh">imap.enable_insecure_rsh</link> is disabled.
1220
+
</simpara></warning>'>
1221
+
1222
+
<!-- intl notes -->
1223
+
1224
+
<!ENTITY intl.parameter.intl-calendar '<para xmlns="http://docbook.org/ns/docbook">An <classname>IntlCalendar</classname> instance.</para>'>
1225
+
1226
+
<!ENTITY intl.error.intl-calendar '<para xmlns="http://docbook.org/ns/docbook">On failure &false; is also returned. To detect error conditions use <function>intl_get_error_code</function>, or set up Intl to throw <link linkend="ini.intl.use-exceptions">exceptions</link>.</para>'>
1227
+
1228
+
<!ENTITY intl.codepoint.parameter '<para xmlns="http://docbook.org/ns/docbook">The <type>int</type> codepoint value (e.g. <literal>0x2603</literal> for <emphasis>U+2603 SNOWMAN</emphasis>), or the character encoded as a UTF-8 <type>string</type> (e.g. <literal>"\u{2603}"</literal>)</para>'>
1229
+
1230
+
<!ENTITY intl.codepoint.return '<para xmlns="http://docbook.org/ns/docbook">The return type is <type>int</type> unless the code point was passed as a UTF-8 <type>string</type>, in which case a <type>string</type> is returned. Returns &null; on failure.</para>'>
1231
+
1232
+
<!ENTITY intl.codepoint.example 'Testing different code points'>
1233
+
1234
+
<!ENTITY intl.locale-len.return '<para xmlns="http://docbook.org/ns/docbook">Returns &null; when the length of <parameter>locale</parameter> exceeds <constant>INTL_MAX_LOCALE_LEN</constant>.</para>'>
1235
+
1236
+
<!ENTITY intl.property.parameter '<para xmlns="http://docbook.org/ns/docbook">The Unicode property to lookup (see the <literal>IntlChar::PROPERTY_*</literal> constants).</para>'>
1237
+
1238
+
<!ENTITY intl.property.example 'Testing different properties'>
1239
+
1240
+
<!-- LDAP notes -->
1241
+
1242
+
<!ENTITY ldap.parameter.ldap 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\Connection</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_connect</function>.'>
1243
+
1244
+
<!ENTITY ldap.parameter.result 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_list</function> or <function xmlns="http://docbook.org/ns/docbook">ldap_search</function>.'>
1245
+
1246
+
<!ENTITY ldap.parameter.entry 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\ResultEntry</classname> instance.'>
1247
+
1248
+
<!ENTITY ldap.warn.control-paged '<warning xmlns="http://docbook.org/ns/docbook">
1249
+
<simpara>
1250
+
This function has been <emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.
1251
+
Instead the <parameter>controls</parameter> parameter of <function>ldap_search</function> should be used.
1252
+
See also <link linkend="ldap.controls">LDAP Controls</link> for details.
1253
+
</simpara>
1254
+
</warning>'>
1255
+
1256
+
<!ENTITY ldap.changelog.controls-nullable '<row xmlns="http://docbook.org/ns/docbook">
1257
+
<entry>8.0.0</entry>
1258
+
<entry>
1259
+
<parameter>controls</parameter> is nullable now; previously, it defaulted to <literal>[]</literal>.
1260
+
</entry>
1261
+
</row>'>
1262
+
1263
+
<!ENTITY ldap.changelog.ldap-object '<row xmlns="http://docbook.org/ns/docbook">
1264
+
<entry>8.1.0</entry>
1265
+
<entry>
1266
+
The <parameter>ldap</parameter> parameter expects an <classname>LDAP\Connection</classname>
1267
+
instance now; previously, a valid <literal>ldap link</literal> &resource; was expected.
1268
+
</entry>
1269
+
</row>'>
1270
+
1271
+
<!ENTITY ldap.changelog.entry-object '<row xmlns="http://docbook.org/ns/docbook">
1272
+
<entry>8.1.0</entry>
1273
+
<entry>
1274
+
The <parameter>entry</parameter> parameter expects an <classname>LDAP\ResultEntry</classname>
1275
+
instance now; previously, a valid <literal>ldap result entry</literal> &resource; was expected.
1276
+
</entry>
1277
+
</row>'>
1278
+
1279
+
<!ENTITY ldap.changelog.result-object '<row xmlns="http://docbook.org/ns/docbook">
1280
+
<entry>8.1.0</entry>
1281
+
<entry>
1282
+
The <parameter>result</parameter> parameter expects an <classname>LDAP\Result</classname>
1283
+
instance now; previously, a valid <literal>ldap result</literal> &resource; was expected.
1284
+
</entry>
1285
+
</row>'>
1286
+
1287
+
<!ENTITY ldap.changelog.return-result-object '<row xmlns="http://docbook.org/ns/docbook">
1288
+
<entry>8.1.0</entry>
1289
+
<entry>
1290
+
Returns an <classname>LDAP\Result</classname> instance now;
1291
+
previously, a &resource; was returned.
1292
+
</entry>
1293
+
</row>'>
1294
+
1295
+
<!ENTITY ldap.changelog.return-result-entry-object '<row xmlns="http://docbook.org/ns/docbook">
1296
+
<entry>8.1.0</entry>
1297
+
<entry>
1298
+
Returns an <classname>LDAP\ResultEntry</classname> instance now;
1299
+
previously, a &resource; was returned.
1300
+
</entry>
1301
+
</row>'>
1302
+
1303
+
<!ENTITY ldap.return-result 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance,&return.falseforfailure;.'>
1304
+
<!ENTITY ldap.return-result-array 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance, an array of <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instances,&return.falseforfailure;.'>
1305
+
1306
+
<!ENTITY ldap.return-result-array-info '<para xmlns="http://docbook.org/ns/docbook">It is also possible to perform parallel searches. In this case, the first argument should be an array of
1307
+
<classname>LDAP\Connection</classname> instances, rather than a single one.
1308
+
If the searches should not all use the same base DN and filter, an array of base DNs and/or an array of filters can be passed as arguments instead.
1309
+
These arrays must be of the same size as the <classname>LDAP\Connection</classname> instances array,
1310
+
since the first entries of the arrays are used for one search, the second entries are used for another, and so on.
1311
+
When doing parallel searches an array of <classname>LDAP\Result</classname> instances is returned, except in case of error, when the return value will be &false;.</para>'>
1312
+
487
1313
<!-- mbstring notes -->
488
1314
489
1315
<!ENTITY note.mbstring.encoding.internal '<note xmlns="http://docbook.org/ns/docbook"><para>The internal encoding or the
490
1316
character encoding specified by <function>mb_regex_encoding</function>
491
1317
will be used as the character encoding for this function.</para></note>'>
492
1318
1319
+
<!ENTITY note.mbstring.encoding.current '<note xmlns="http://docbook.org/ns/docbook"><para>The
1320
+
character encoding specified by <function>mb_regex_encoding</function>
1321
+
will be used as the character encoding for this function by default.</para></note>'>
1322
+
493
1323
<!ENTITY mbstring.encoding.parameter '<para xmlns="http://docbook.org/ns/docbook">The <parameter>encoding</parameter>
494
-
parameter is the character encoding. If it is omitted, the internal character
1324
+
parameter is the character encoding. If it is omitted or &null;, the internal character
495
1325
encoding value will be used.</para>'>
496
1326
497
1327
<!ENTITY mbstring.warning.e-modifier '<warning xmlns="http://docbook.org/ns/docbook"><para>Never use the <literal>e</literal> modifier when working on untrusted input. No automatic escaping will happen (as known from <function>preg_replace</function>). Not taking care of this will most likely create remote code execution vulnerabilities in your application.</para></warning>'>
498
1328
1329
+
<!ENTITY mbstring.changelog.encoding-nullable '<row xmlns="http://docbook.org/ns/docbook">
1330
+
<entry>8.0.0</entry>
1331
+
<entry>
1332
+
<parameter>encoding</parameter> is nullable now.
1333
+
</entry>
1334
+
</row>'>
1335
+
1336
+
<!ENTITY mbstring.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
1337
+
<entry>8.0.0</entry>
1338
+
<entry>
1339
+
<parameter>needle</parameter> now accepts an empty string.
1340
+
</entry>
1341
+
</row>'>
1342
+
499
1343
<!-- mcrypt notes -->
500
1344
501
1345
<!ENTITY mcrypt.parameter.cipher '<para xmlns="http://docbook.org/ns/docbook">One of the <constant>MCRYPT_ciphername</constant> constants, or the name of the algorithm as string.</para>'>
502
1346
503
1347
<!ENTITY mcrypt.parameter.iv '<para xmlns="http://docbook.org/ns/docbook">Used for the initialization in CBC, CFB, OFB modes, and in some algorithms in STREAM mode. If you do not supply an IV, while it is needed for an algorithm, the function issues a warning and uses an IV with all its bytes set to "<literal>\0</literal>".</para>'>
504
1348
1349
+
<!ENTITY mcrypt.parameter.iv.strict '<para xmlns="http://docbook.org/ns/docbook">Used for the initialization in CBC, CFB, OFB modes, and in some algorithms in STREAM mode. If the provided IV size is not supported by the chaining mode or no IV was provided, but the chaining mode requires one, the function will emit a warning and return &false;.</para>'>
1350
+
505
1351
<!ENTITY mcrypt.parameter.mode '<para xmlns="http://docbook.org/ns/docbook">One of the <constant>MCRYPT_MODE_modename</constant> constants, or one of the following strings: "ecb", "cbc", "cfb", "ofb", "nofb" or "stream".</para>'>
506
1352
507
1353
<!-- MCVE notes -->
508
1354
509
-
<!ENTITY mcve.conn.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
510
-
conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
1355
+
<!ENTITY mcve.conn.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1356
+
<parameter>conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
511
1357
<function>m_initengine</function>.</para></listitem></varlistentry>'>
512
1358
513
1359
<!-- memcached notes -->
514
1360
1361
+
<!ENTITY memcached.note.delete-time '<note xmlns="http://docbook.org/ns/docbook"><simpara>
1362
+
As of memcached 1.3.0 (released 2009) this feature is no longer
1363
+
supported. Passing a non-zero <parameter>time</parameter> will cause
1364
+
the deletion to fail. <methodname>Memcached::getResultCode</methodname>
1365
+
will return <constant>MEMCACHED_INVALID_ARGUMENTS</constant>.
1366
+
</simpara></note>
1367
+
'>
1368
+
515
1369
<!ENTITY memcached.parameter.expiration 'The expiration time, defaults to 0. See <link
516
1370
linkend="memcached.expiration" xmlns="http://docbook.org/ns/docbook">Expiration Times</link> for more info.'>
517
1371
...
...
@@ -525,16 +1379,77 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
525
1379
526
1380
<!ENTITY memcached.result.getresultcode 'Use <methodname xmlns="http://docbook.org/ns/docbook">Memcached::getResultCode</methodname> if necessary.'>
527
1381
1382
+
<!ENTITY memcached.result.delete-multi '<para xmlns="http://docbook.org/ns/docbook">
1383
+
Returns an array indexed by <parameter>keys</parameter>. Each element
1384
+
is &true; if the corresponding key was deleted, or one of the
1385
+
<constant>Memcached::RES_*</constant> constants if the corresponding deletion
1386
+
failed.
1387
+
</para>
1388
+
<para xmlns="http://docbook.org/ns/docbook">
1389
+
The <methodname>Memcached::getResultCode</methodname> will return
1390
+
the result code for the last executed delete operation, that is, the delete
1391
+
operation for the last element of <parameter>keys</parameter>.
1392
+
</para>
1393
+
'>
1394
+
528
1395
<!-- password notes -->
529
1396
530
1397
<!ENTITY password.parameter.algo 'A <link xmlns="http://docbook.org/ns/docbook" linkend="password.constants">password algorithm constant</link> denoting the algorithm to use when hashing the password.'>
531
1398
532
1399
<!ENTITY password.parameter.hash 'A hash created by <function xmlns="http://docbook.org/ns/docbook">password_hash</function>.'>
533
1400
534
-
<!ENTITY password.parameter.options 'An associative array containing options. Currently, two options are supported: <literal xmlns="http://docbook.org/ns/docbook">salt</literal>, to provide a salt to use when hashing the password, and <literal xmlns="http://docbook.org/ns/docbook">cost</literal>, which denotes the algorithmic cost that should be used. Examples of these values can be found on the <function xmlns="http://docbook.org/ns/docbook">crypt</function> page.'>
1401
+
<!ENTITY password.parameter.options 'An associative array containing options. See the <link xmlns="http://docbook.org/ns/docbook" linkend="password.constants">password algorithm constants</link> for documentation on the supported options for each algorithm.'>
535
1402
536
1403
<!ENTITY password.parameter.password 'The user's password.'>
537
1404
1405
+
<!-- pspell notes -->
1406
+
1407
+
<!ENTITY pspell.changelog.pspell-dictionary '<row xmlns="http://docbook.org/ns/docbook">
1408
+
<entry>8.1.0</entry>
1409
+
<entry>
1410
+
The <parameter>dictionary</parameter> parameter expects an <classname>PSpell\Dictionary</classname>
1411
+
instance now; previously, a &resource; was expected.
1412
+
</entry>
1413
+
</row>'>
1414
+
1415
+
<!ENTITY pspell.changelog.pspell-config '<row xmlns="http://docbook.org/ns/docbook">
1416
+
<entry>8.1.0</entry>
1417
+
<entry>
1418
+
The <parameter>config</parameter> parameter expects an <classname>PSpell\Config</classname>
1419
+
instance now; previously, a &resource; was expected.
1420
+
</entry>
1421
+
</row>'>
1422
+
1423
+
<!ENTITY pspell.parameter.pspell-dictionary '<para xmlns="http://docbook.org/ns/docbook">An <classname>PSpell\Dictionary</classname> instance.</para>'>
1424
+
1425
+
<!ENTITY pspell.parameter.pspell-config '<para xmlns="http://docbook.org/ns/docbook">An <classname>PSpell\Config</classname> instance.</para>'>
1426
+
1427
+
<!-- RNP -->
1428
+
1429
+
<!ENTITY rnp.parameter.ffi-description 'The FFI object returned by rnp_ffi_create.'>
1430
+
1431
+
<!ENTITY rnp.parameter.key-format 'The key format of the data (GPG, KBX, G10).'>
1432
+
1433
+
<!ENTITY rnp.parameter.loadsave-flags 'See RNP_LOAD_SAVE_* flags description.'>
1434
+
1435
+
<!-- socket entities -->
1436
+
1437
+
<!ENTITY sockets.changelog.socket-param '<row xmlns="http://docbook.org/ns/docbook">
1438
+
<entry>8.0.0</entry>
1439
+
<entry>
1440
+
<parameter>socket</parameter> is a <classname>Socket</classname> instance now;
1441
+
previously, it was a <type>resource</type>.
1442
+
</entry>
1443
+
</row>'>
1444
+
1445
+
<!ENTITY sockets.changelog.address-param '<row xmlns="http://docbook.org/ns/docbook">
1446
+
<entry>8.0.0</entry>
1447
+
<entry>
1448
+
<parameter>address</parameter> is an <classname>AddressInfo</classname> instance now;
1449
+
previously, it was a <type>resource</type>.
1450
+
</entry>
1451
+
</row>'>
1452
+
538
1453
<!-- geaman notes -->
539
1454
540
1455
<!ENTITY gearman.parameter.host 'The job server host name.'>
...
...
@@ -559,21 +1474,43 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
559
1474
<!ENTITY date.timezone.intro "<para xmlns='http://docbook.org/ns/docbook'>
560
1475
Here you'll find the complete list of timezones supported by PHP, which are
561
1476
meant to be used with e.g. <function>date_default_timezone_set</function>.
1477
+
<caution><simpara>The behavior of timezones not listed here is undefined.</simpara></caution>
562
1478
</para><note xmlns='http://docbook.org/ns/docbook'><simpara>The latest version of the timezone database can be
563
1479
installed via PECL's <link xlink:href='&url.pecl.package.get;timezonedb' xmlns:xlink='http://www.w3.org/1999/xlink'>timezonedb</link>.
564
1480
</simpara></note>">
565
1481
566
1482
<!ENTITY date.timezone.bc '<simpara xmlns="http://docbook.org/ns/docbook">Please do not use any of the timezones
567
-
listed here (besides UTC), they only exist for backward compatible reasons.
1483
+
listed here (besides UTC), they only exist for backward compatible reasons, and may expose erroneous behavior.
1484
+
Furthermore, these timezones may be removed from the IANA timezone database at any time.
1485
+
</simpara>'>
1486
+
1487
+
<!ENTITY date.timezone.posix-signs '<simpara xmlns="http://docbook.org/ns/docbook">
1488
+
If you disregard the above warning, please also note that the IANA
1489
+
timezone database that provides PHP's timezone support uses POSIX style
1490
+
signs, which results in the <literal>Etc/GMT+n</literal> and
1491
+
<literal>Etc/GMT-n</literal> time zones being reversed from common usage.
1492
+
</simpara>
1493
+
<simpara xmlns="http://docbook.org/ns/docbook">
1494
+
For example, the time zone 8 hours ahead of GMT that is used in China and
1495
+
Western Australia (among other places) is actually
1496
+
<literal>Etc/GMT-8</literal> in this database, not
1497
+
<literal>Etc/GMT+8</literal> as you would normally expect.
1498
+
</simpara>
1499
+
<simpara xmlns="http://docbook.org/ns/docbook">
1500
+
Once again, it is strongly recommended that you use the correct time zone
1501
+
for your location, such as <literal>Asia/Shanghai</literal> or
1502
+
<literal>Australia/Perth</literal> for the above examples.
568
1503
</simpara>'>
569
1504
1505
+
<!ENTITY date.timezone.abbrev-volatile '<simpara xmlns="http://docbook.org/ns/docbook">
1506
+
These timezone abbreviations have to be regarded as highly volatile, i.e. they
1507
+
might be different for each timezonedb release, and should not be relied upon.
1508
+
It is strongly recommended to avoid timezone abbreviations.
1509
+
</simpara>'>
570
1510
571
1511
<!ENTITY date.timezone.errors.description '<para xmlns="http://docbook.org/ns/docbook">
572
-
Every call to a date/time function will generate a <constant>E_NOTICE</constant>
573
-
if the time zone is not valid, and/or a <constant>E_STRICT</constant>
574
-
or <constant>E_WARNING</constant> message
575
-
if using the system settings or the <varname>TZ</varname> environment
576
-
variable. See also <function>date_default_timezone_set</function></para>'>
1512
+
Every call to a date/time function will generate a <constant>E_WARNING</constant>
1513
+
if the time zone is not valid. See also <function>date_default_timezone_set</function></para>'>
577
1514
578
1515
<!ENTITY date.timezone.errors.changelog '<row xmlns="http://docbook.org/ns/docbook"><entry>5.1.0</entry><entry><para>
579
1516
Now issues the <constant>E_STRICT</constant> and <constant>E_NOTICE</constant>
...
...
@@ -582,8 +1519,8 @@ time zone errors.</para></entry></row>'>
582
1519
<!ENTITY date.timestamp.description '
583
1520
<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>timestamp</parameter></term><listitem><para>
584
1521
The optional <parameter>timestamp</parameter> parameter is an
585
-
<type>integer</type> Unix timestamp that defaults to the current
586
-
local time if a <parameter>timestamp</parameter> is not given. In other
1522
+
<type>int</type> Unix timestamp that defaults to the current
1523
+
local time if <parameter>timestamp</parameter> is omitted or &null;. In other
587
1524
words, it defaults to the value of <function>time</function>.
588
1525
</para></listitem></varlistentry>'>
589
1526
...
...
@@ -596,14 +1533,14 @@ returned by <function>date_create</function></para></listitem></varlistentry>'>
596
1533
returned by <function>date_create</function>.
597
1534
The function modifies this object.</para></listitem></varlistentry>'>
598
1535
599
-
<!ENTITY date.datetimezone.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
600
-
object</parameter></term><listitem><para>Procedural style only: A <classname>DateTimeZone</classname> object
1536
+
<!ENTITY date.datetimezone.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1537
+
<parameter>object</parameter></term><listitem><para>Procedural style only: A <classname>DateTimeZone</classname> object
601
1538
returned by <function>timezone_open</function></para></listitem></varlistentry>'>
602
1539
603
-
<!ENTITY date.datetime.retval.changelog '<row xmlns="http://docbook.org/ns/docbook"><entry>5.3.0</entry><entry>Changed the
604
-
return value on success from &null; to <classname>DateTime</classname>.</entry></row>'>
605
-
606
-
<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining&return.falseforfailure;.'>
1540
+
<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the modified <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining&return.falseforfailure;.'>
1541
+
<!ENTITY date.datetime.return.modifiedobject 'Returns the modified <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining.'>
1542
+
<!ENTITY date.datetimeimmutable.return.modifiedobjectorfalseforfailure 'Returns a new <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object with the modified data &return.falseforfailure;.'>
1543
+
<!ENTITY date.datetimeimmutable.return.modifiedobject 'Returns a new <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object with the modified data.'>
607
1544
608
1545
<!ENTITY date.timezone.dbversion 'This list is based upon the timezone database version'>
609
1546
...
...
@@ -618,6 +1555,7 @@ return value on success from &null; to <classname>DateTime</classname>.</entry><
618
1555
<!ENTITY date.timezone.indian 'Indian'>
619
1556
<!ENTITY date.timezone.pacific 'Pacific'>
620
1557
<!ENTITY date.timezone.others 'Others'>
1558
+
<!ENTITY date.timezone.abbreviations 'Abbreviations'>
621
1559
622
1560
<!ENTITY date.formats 'Valid formats are explained in <link xmlns="http://docbook.org/ns/docbook" linkend="datetime.formats">Date and Time Formats</link>.'>
623
1561
<!ENTITY date.formats.parameter 'A date/time string. &date.formats;'>
...
...
@@ -631,8 +1569,11 @@ is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">domnode_
631
1569
<!ENTITY dom.node.inserted 'This node will not show up in the document unless
632
1570
it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNode::appendChild</function>.'>
633
1571
634
-
<!ENTITY dom.allowstatic '<para xmlns="http://docbook.org/ns/docbook">This method <emphasis>may</emphasis> be called statically, but will issue an <constant>E_STRICT</constant> error.</para>'>
635
1572
<!ENTITY dom.malformederror '<para xmlns="http://docbook.org/ns/docbook">While malformed HTML should load successfully, this function may generate <constant>E_WARNING</constant> errors when it encounters bad markup. <link linkend="function.libxml-use-internal-errors">libxml's error handling functions</link> may be used to handle these errors.</para>'>
1573
+
<!ENTITY dom.note.utf8 '<note xmlns="http://docbook.org/ns/docbook"><para>The DOM extension uses UTF-8 encoding. Use <function>mb_convert_encoding</function>, <methodname>UConverter::transcode</methodname>, or <function>iconv</function> to handle other encodings.</para></note>'>
1574
+
<!ENTITY dom.note.json '<note xmlns="http://docbook.org/ns/docbook"><para>When using <function>json_encode</function> on a <classname>DOMDocument</classname> object the result will be that of encoding an empty object.</para></note>'>
1575
+
1576
+
636
1577
637
1578
<!-- Dom Examples -->
638
1579
<!ENTITY dom.book.example '<para xmlns="http://docbook.org/ns/docbook">The following examples use <filename>book.xml</filename> which contains the following:</para>
...
...
@@ -668,6 +1609,58 @@ it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNo
668
1609
</books>
669
1610
]]></programlisting>'>
670
1611
1612
+
<!-- Dom entities -->
1613
+
<!ENTITY dom.parameter.options '<para xmlns="http://docbook.org/ns/docbook">
1614
+
<link linkend="language.operators.bitwise">Bitwise <literal>OR</literal></link>
1615
+
of the <link linkend="libxml.constants">libxml option constants</link>.
1616
+
</para>'>
1617
+
1618
+
<!ENTITY dom.parameters.register_node_ns '<varlistentry xmlns="http://docbook.org/ns/docbook">
1619
+
<term><parameter>registerNodeNS</parameter></term>
1620
+
<listitem>
1621
+
<para>
1622
+
Whether to automatically register the in-scope namespace prefixes of the context node to the <classname>DOMXPath</classname> object.
1623
+
This can be used to avoid needing to call <methodname>DOMXPath::registerNamespace</methodname> manually for each in-scope namespaces.
1624
+
When a namespace prefix conflict exists, only the nearest descendant namespace prefix is registered.
1625
+
</para>
1626
+
</listitem>
1627
+
</varlistentry>'>
1628
+
1629
+
<!ENTITY dom.errors.hierarchy.parent '<varlistentry xmlns="http://docbook.org/ns/docbook">
1630
+
<term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
1631
+
<listitem>
1632
+
<para>
1633
+
Raised if the parent is of a type that does not allow children of the
1634
+
type of one of the passed <parameter>nodes</parameter>, or if the node to
1635
+
put in is one of this node's ancestors or this node itself.
1636
+
</para>
1637
+
</listitem>
1638
+
</varlistentry>'>
1639
+
1640
+
<!ENTITY dom.errors.hierarchy.self '<varlistentry xmlns="http://docbook.org/ns/docbook">
1641
+
<term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
1642
+
<listitem>
1643
+
<para>
1644
+
Raised if this node is of a type that does not allow children of the
1645
+
type of one of the passed <parameter>nodes</parameter>, or if the node to
1646
+
put in is one of this node's ancestors or this node itself.
1647
+
</para>
1648
+
</listitem>
1649
+
</varlistentry>'>
1650
+
1651
+
<!ENTITY dom.errors.wrong_document '<varlistentry xmlns="http://docbook.org/ns/docbook">
1652
+
<term><constant>DOM_WRONG_DOCUMENT_ERR</constant></term>
1653
+
<listitem>
1654
+
<para>
1655
+
Raised if one of the passed <parameter>nodes</parameter> was created from a different
1656
+
document than the one that created this node.
1657
+
</para>
1658
+
</listitem>
1659
+
</varlistentry>'>
1660
+
1661
+
<!ENTITY dom.changelog.previous_hierarchy_exception 'Previously this threw a
1662
+
<classname xmlns="http://docbook.org/ns/docbook">DOMException</classname> with code
1663
+
<constant xmlns="http://docbook.org/ns/docbook">DOM_HIERARCHY_REQUEST_ERR</constant>.'>
671
1664
672
1665
<!-- FileSystem entities -->
673
1666
<!ENTITY fs.emits.warning.on.failure '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -688,6 +1681,15 @@ that is typically created using <function>fopen</function>.</para>'>
688
1681
are larger than 2GB.
689
1682
</simpara></note>'>
690
1683
1684
+
<!ENTITY ini.scanner.typed '<para xmlns="http://docbook.org/ns/docbook">
1685
+
As of PHP 5.6.1 can also be specified as <constant>INI_SCANNER_TYPED</constant>.
1686
+
In this mode boolean, null and integer types are preserved when possible.
1687
+
String values <literal>"true"</literal>, <literal>"on"</literal> and <literal>"yes"</literal>
1688
+
are converted to &true;. <literal>"false"</literal>, <literal>"off"</literal>, <literal>"no"</literal>
1689
+
and <literal>"none"</literal> are considered &false;. <literal>"null"</literal> is converted to &null;
1690
+
in typed mode. Also, all numeric strings are converted to integer type if it is possible.
1691
+
</para>'>
1692
+
691
1693
<!-- GNUPG -->
692
1694
<!ENTITY gnupg.identifier '<para xmlns="http://docbook.org/ns/docbook">The gnupg identifier, from a call to
693
1695
<function>gnupg_init</function> or <classname>gnupg</classname>.</para>'>
...
...
@@ -701,8 +1703,15 @@ that is typically created using <function>fopen</function>.</para>'>
701
1703
<!ENTITY odbc.connection.id '<para xmlns="http://docbook.org/ns/docbook">The ODBC connection identifier,
702
1704
see <function>odbc_connect</function> for details.</para>'>
703
1705
1706
+
<!ENTITY odbc.parameter.catalog 'The catalog ('qualifier' in ODBC 2 parlance).'>
1707
+
1708
+
<!ENTITY odbc.parameter.schema 'The schema ('owner' in ODBC 2 parlance).'>
1709
+
704
1710
<!ENTITY odbc.parameter.search 'This parameter accepts the following search patterns:
705
-
"%" to match zero or more characters, and "_" to match a single character.'>
1711
+
<literal xmlns="http://docbook.org/ns/docbook">%</literal> to match zero or more characters,
1712
+
and <literal xmlns="http://docbook.org/ns/docbook">_</literal> to match a single character.'>
1713
+
1714
+
<!ENTITY odbc.result.driver-specific 'Drivers can report additional columns.'>
706
1715
707
1716
<!-- OAUTH -->
708
1717
<!ENTITY oauth.callback.error 'Emits an <constant xmlns="http://docbook.org/ns/docbook">E_ERROR</constant> level
...
...
@@ -718,7 +1727,7 @@ string</link>, or a Connect Name from
718
1727
the <filename>tnsnames.ora</filename> file, or the name of a local
719
1728
Oracle instance.
720
1729
</para>
721
-
<para xmlns='http://docbook.org/ns/docbook'>If not specified, PHP uses
1730
+
<para xmlns='http://docbook.org/ns/docbook'>If not specified or &null;, PHP uses
722
1731
environment variables such as <constant>TWO_TASK</constant> (on Linux)
723
1732
or <constant>LOCAL</constant> (on Windows)
724
1733
and <constant>ORACLE_SID</constant> to determine the
...
...
@@ -726,23 +1735,23 @@ and <constant>ORACLE_SID</constant> to determine the
726
1735
</para>
727
1736
<para xmlns='http://docbook.org/ns/docbook'>
728
1737
To use the Easy Connect naming method, PHP must be linked with Oracle
729
-
10g or greater Client libraries. The Easy Connect string for Oracle
730
-
10g is of the form:
731
-
<emphasis>[//]host_name[:port][/service_name]</emphasis>. With Oracle
732
-
11g, the syntax is:
1738
+
10<emphasis>g</emphasis> or greater Client libraries. The Easy Connect string for Oracle
1739
+
10<emphasis>g</emphasis> is of the form:
1740
+
<emphasis>[//]host_name[:port][/service_name]</emphasis>. From Oracle
1741
+
11<emphasis>g</emphasis>, the syntax is:
733
1742
<emphasis>[//]host_name[:port][/service_name][:server_type][/instance_name]</emphasis>.
734
-
Service names can be found by running the Oracle
735
-
utility <literal>lsnrctl status</literal> on the database server
1743
+
Further options were introduced with Oracle 19c, including timeout and keep-alive
1744
+
settings. Refer to Oracle documentation. Service names can be found by running
1745
+
the Oracle utility <literal>lsnrctl status</literal> on the database server
736
1746
machine.
737
1747
</para>
738
1748
<para xmlns='http://docbook.org/ns/docbook'>
739
-
The <filename>tnsnames.ora</filename> file can be in the Oracle Net
740
-
search path, which
741
-
includes <filename>$ORACLE_HOME/network/admin</filename>
742
-
and <filename>/etc</filename>. Alternatively
743
-
set <literal>TNS_ADMIN</literal> so
744
-
that <filename>$TNS_ADMIN/tnsnames.ora</filename> is read. Make sure
745
-
the web daemon has read access to the file.
1749
+
The <filename>tnsnames.ora</filename> file can be in the Oracle Net search path,
1750
+
which
1751
+
includes <filename>/your/path/to/instantclient/network/admin</filename>, <filename>$ORACLE_HOME/network/admin</filename>
1752
+
and <filename>/etc</filename>. Alternatively set <literal>TNS_ADMIN</literal>
1753
+
so that <filename>$TNS_ADMIN/tnsnames.ora</filename> is read. Make sure the web
1754
+
daemon has read access to the file.
746
1755
</para>">
747
1756
748
1757
<!ENTITY oci.charset "<para xmlns='http://docbook.org/ns/docbook'>Determines
...
...
@@ -757,7 +1766,7 @@ Oracle Client libraries determine a character set from
757
1766
the <constant>NLS_LANG</constant> environment variable.
758
1767
</para>
759
1768
<para xmlns='http://docbook.org/ns/docbook'>Passing this parameter can
760
-
reduce connection time.
1769
+
reduce the time taken to connect.
761
1770
</para>">
762
1771
763
1772
<!ENTITY oci.sessionmode '<para xmlns="http://docbook.org/ns/docbook">This
...
...
@@ -798,20 +1807,17 @@ supported by the driver</link></para>'>
798
1807
returned by <function>oci_connect</function>, <function>oci_pconnect</function>,
799
1808
or <function>oci_new_connect</function>.</para>'>
800
1809
801
-
<!ENTITY oci.name.compat.note 'The old function name can still be used
802
-
in current versions, however it is deprecated and not recommended.'>
803
-
804
1810
<!ENTITY oci.availability.note.10g '<note xmlns="http://docbook.org/ns/docbook"><title>Oracle version requirement</title>
805
1811
<para>This function is available when PHP is linked with Oracle Database
806
-
libraries from version 10g onwards.</para></note>'>
1812
+
libraries from version 10<emphasis>g</emphasis> onwards.</para></note>'>
807
1813
808
1814
<!ENTITY oci.clientinfo.tip '<tip xmlns="http://docbook.org/ns/docbook"><title>Performance</title><para>With older versions of
809
1815
OCI8 or the Oracle Database, the client information can be set using the Oracle
810
1816
<literal>DBMS_APPLICATION_INFO</literal> package. This is less efficient than
811
1817
using <function>oci_set_client_info</function>.</para></tip>'>
812
1818
813
-
<!ENTITY oci.roundtrip.caution '<caution xmlns="http://docbook.org/ns/docbook"><title>Roundtrip Gotcha</title>
814
-
<para>Some but not all OCI8 functions cause roundtrips. Roundtrips to the
1819
+
<!ENTITY oci.roundtrip.caution '<caution xmlns="http://docbook.org/ns/docbook"><title>Round-trip Gotcha</title>
1820
+
<para>Some but not all OCI8 functions cause round-trips. Round-trips to the
815
1821
database may not occur with queries when result caching is enabled.
816
1822
</para></caution>'>
817
1823
...
...
@@ -839,30 +1845,18 @@ call to <function>pcntl_waitpid</function>.</para>'>
839
1845
is printed or viewed but it will show up if the document is converted to
840
1846
pdf by either Acrobat Distiller™ or Ghostview.</para>'>
841
1847
842
-
<!-- XSLT Notes -->
843
-
<!ENTITY note.xslt.windows '<note xmlns="http://docbook.org/ns/docbook"><para>Please note that
844
-
<literal>file://</literal> is needed in front of the path when using Windows.
845
-
</para></note>'>
846
-
847
-
<!ENTITY xslt.parameter.processor '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
848
-
processor</parameter></term><listitem><para>The <acronym>XSLT</acronym> processor
849
-
link identifier, created with <function>xslt_create</function>.</para></listitem>
850
-
</varlistentry>'>
851
-
852
-
<!ENTITY xslt.parameter.xh '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
853
-
xh</parameter></term><listitem><para>The <acronym>XSLT</acronym> processor
854
-
link identifier, created with <function>xslt_create</function>.</para></listitem>
855
-
</varlistentry>'>
856
-
857
-
858
1848
<!-- Notes for safe-mode limited functions: -->
1849
+
1850
+
<!-- Not used in EN anymore -->
859
1851
<!ENTITY note.sm.disabled '<note xmlns="http://docbook.org/ns/docbook"><simpara>&sm.disabled;</simpara></note>'>
860
1852
1853
+
<!-- Not used in EN anymore -->
861
1854
<!ENTITY note.sm.uidcheck '<note xmlns="http://docbook.org/ns/docbook"><simpara>When <link
862
1855
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether
863
1856
the files or directories being operated upon have the same UID (owner) as the
864
1857
script that is being executed.</simpara></note>'>
865
1858
1859
+
<!-- Not used in EN anymore -->
866
1860
<!ENTITY note.sm.uidcheck.dir '<note xmlns="http://docbook.org/ns/docbook"><simpara>When <link
867
1861
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether
868
1862
the directory in which the script is operating has the same UID (owner) as the
...
...
@@ -874,29 +1868,36 @@ linkend="ini.open-basedir">open_basedir</link>.</para></note>'>
874
1868
875
1869
<!ENTITY note.language-construct '<note xmlns="http://docbook.org/ns/docbook"><simpara>Because this is a
876
1870
language construct and not a function, it cannot be called using
877
-
<link linkend="functions.variable-functions">variable functions</link>.</simpara>
1871
+
<link linkend="functions.variable-functions">variable functions</link>,
1872
+
or <link linkend="functions.named-arguments">named arguments</link>.</simpara>
878
1873
</note>'>
879
1874
880
1875
<!-- Common pieces in features/safe-mode.xml
881
1876
Jade doesn't allow in-line entities, so I put them here... Though they
882
1877
should have been inline in safe-mode.xml -->
1878
+
1879
+
<!-- Not used in EN anymore -->
883
1880
<!ENTITY sm.uidcheck 'Checks whether the files or directories being operated
884
1881
upon have the same UID (owner) as the script that is being executed.'>
885
1882
1883
+
<!-- Not used in EN anymore -->
886
1884
<!ENTITY warn.sm.exec '<warning xmlns="http://docbook.org/ns/docbook"><simpara>With <link linkend="features.safe-mode">safe mode</link> enabled,
887
1885
the command string is escaped with <function>escapeshellcmd</function>. Thus,
888
1886
<literal>echo y | echo x</literal> becomes <literal>echo y \| echo x</literal>.</simpara></warning>'>
889
1887
1888
+
<!-- Not used in EN anymore -->
890
1889
<!ENTITY note.exec-path '<note xmlns="http://docbook.org/ns/docbook"><simpara>When
891
1890
<link linkend="features.safe-mode">safe mode</link> is enabled, you can only
892
1891
execute files within the <link linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
893
1892
For practical reasons, it is currently not allowed to have <literal>..</literal>
894
1893
components in the path to the executable.</simpara></note>'>
895
1894
1895
+
<!-- Not used in EN anymore -->
896
1896
<!ENTITY sm.uidcheck.dir 'Checks whether the directory in which
897
1897
the script is operating has the same UID (owner) as the script that is being
898
1898
executed.'>
899
1899
1900
+
<!-- Not used in EN anymore -->
900
1901
<!ENTITY sm.disabled 'This function is disabled when PHP is running in <link xmlns="http://docbook.org/ns/docbook"
901
1902
linkend="features.safe-mode">safe mode</link>.'>
902
1903
...
...
@@ -920,7 +1921,7 @@ The behaviour of these functions is affected by settings in &php.ini;.
920
1921
</simpara>'>
921
1922
922
1923
<!ENTITY ini.php.constants 'For further details and definitions of the
923
-
PHP_INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>
1924
+
INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>
924
1925
925
1926
<!-- Used in reference/$extname/constants.xml -->
926
1927
<!ENTITY extension.constants '<simpara xmlns="http://docbook.org/ns/docbook">
...
...
@@ -951,15 +1952,26 @@ compiled into PHP or dynamically loaded at runtime. In addition, these
951
1952
driver-specific constants should only be used if you are using this driver.
952
1953
Using driver-specific attributes with another driver may result in
953
1954
unexpected behaviour. <function>PDO::getAttribute</function> may be used to
954
-
obtain the <constant>PDO_ATTR_DRIVER_NAME</constant> attribute to check the
1955
+
obtain the <constant>PDO::ATTR_DRIVER_NAME</constant> attribute to check the
955
1956
driver, if your code can run against multiple drivers.</simpara>'>
956
1957
1958
+
<!ENTITY pdo.errors.exception-not-errmode '<note xmlns="http://docbook.org/ns/docbook"><simpara>An exception is raised even when the <constant>PDO::ATTR_ERRMODE</constant> attribute is not <constant>PDO::ERRMODE_EXCEPTION</constant>.</simpara></note>'>
1959
+
1960
+
<!-- PDO errors -->
1961
+
1962
+
<!ENTITY pdo.errors '<para xmlns="http://docbook.org/ns/docbook">
1963
+
Emits an error with level <constant>E_WARNING</constant> if the attribute <constant>PDO::ATTR_ERRMODE</constant> is set
1964
+
to <constant>PDO::ERRMODE_WARNING</constant>.
1965
+
</para>
1966
+
<para xmlns="http://docbook.org/ns/docbook">
1967
+
Throws a <classname>PDOException</classname> if the attribute <constant>PDO::ATTR_ERRMODE</constant>
1968
+
is set to <constant>PDO::ERRMODE_EXCEPTION</constant>.
1969
+
</para>'>
1970
+
957
1971
<!-- PECL entities -->
958
-
<!ENTITY pecl.moved 'This <link xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> extension
959
-
is not bundled with PHP.'>
1972
+
<!ENTITY pecl.moved 'This &link.pecl; extension is not bundled with PHP.'>
960
1973
961
-
<!ENTITY pecl.bundled 'This <link xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> extension
962
-
is bundled with PHP.'>
1974
+
<!ENTITY pecl.bundled 'This &link.pecl; extension is bundled with PHP.'>
963
1975
964
1976
<!ENTITY pecl.info 'Information for installing this PECL extension may be
965
1977
found in the manual chapter titled <link xmlns="http://docbook.org/ns/docbook" linkend="install.pecl">Installation
...
...
@@ -971,30 +1983,83 @@ located here: '>
971
1983
this extension is still available within <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym>
972
1984
<acronym xmlns="http://docbook.org/ns/docbook">SVN</acronym> here: '>
973
1985
974
-
<!ENTITY pecl.source.4 'In PHP 4 this <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extensions
975
-
source can be found in the <filename xmlns="http://docbook.org/ns/docbook">ext/</filename> directory within the
976
-
PHP source or at the <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> link above.'>
977
-
978
-
<!ENTITY pecl.windows.4 'In PHP 4 this <acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> resides in
979
-
the <filename xmlns="http://docbook.org/ns/docbook">extensions/</filename> directory within the PHP Windows
980
-
binaries download.'>
1986
+
<!ENTITY pecl.info.dead.git 'This extension is considered unmaintained and dead. However, the source code for
1987
+
this extension is still available within <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym>
1988
+
<acronym xmlns="http://docbook.org/ns/docbook">GIT</acronym> here: '>
981
1989
982
1990
<!ENTITY pecl.windows.download 'A <acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> for this
983
1991
<acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension is currently unavailable. See also the
984
1992
<link xmlns="http://docbook.org/ns/docbook" linkend="install.windows.building">building on Windows</link>
985
1993
section.'>
986
1994
987
-
<!ENTITY pecl.windows.download.unbundled '&pecl.windows.download;'>
1995
+
<!ENTITY pecl.windows.download.avail 'Windows binaries (<acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> files)
1996
+
for this <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension are available from the PECL website.'>
988
1997
989
-
<!ENTITY pecl.moved-ver 'This extension has been moved to the
990
-
<link xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> repository and is no longer bundled with
991
-
PHP as of PHP '>
1998
+
<!ENTITY pecl.windows.download.unbundled '&pecl.windows.download;'>
992
1999
993
-
<!-- kept for BC -->
994
-
<!ENTITY note.pecl-php5 '<note xmlns="http://docbook.org/ns/docbook"><simpara>
995
-
This extension has been removed as of PHP 5 and moved to the
996
-
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> repository.
997
-
</simpara></note>'>
2000
+
<!ENTITY pecl.moved-ver 'This extension has been moved to the &link.pecl;
2001
+
repository and is no longer bundled with PHP as of PHP '>
2002
+
2003
+
<!-- PGSQL entities -->
2004
+
2005
+
<!ENTITY pgsql.parameter.connection '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.</para>'>
2006
+
2007
+
<!ENTITY pgsql.parameter.connection-with-unspecified-default '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.
2008
+
When <parameter>connection</parameter> is unspecified, the default connection is used.
2009
+
The default connection is the last connection made by <function>pg_connect</function>
2010
+
or <function>pg_pconnect</function>.
2011
+
<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>
2012
+
2013
+
<!ENTITY pgsql.parameter.connection-with-nullable-default '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.
2014
+
When <parameter>connection</parameter> is &null;, the default connection is used.
2015
+
The default connection is the last connection made by <function>pg_connect</function>
2016
+
or <function>pg_pconnect</function>.
2017
+
<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>
2018
+
2019
+
<!ENTITY pgsql.parameter.result '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Result</classname> instance, returned by <function>pg_query</function>,
2020
+
<function>pg_query_params</function> or <function>pg_execute</function>(among others).</para>'>
2021
+
2022
+
<!ENTITY pgsql.parameter.lob '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Lob</classname> instance, returned by <function>pg_lo_open</function>.</para>'>
2023
+
2024
+
<!ENTITY pgsql.parameter.mode '<para xmlns="http://docbook.org/ns/docbook">
2025
+
An optional parameter that controls how the returned <type>array</type> is indexed.
2026
+
<parameter>mode</parameter> is a constant and can take the following values:
2027
+
<constant>PGSQL_ASSOC</constant>, <constant>PGSQL_NUM</constant> and <constant>PGSQL_BOTH</constant>.
2028
+
Using <constant>PGSQL_NUM</constant>, the function will return an array with numerical indices,
2029
+
using <constant>PGSQL_ASSOC</constant> it will return only associative indices
2030
+
while <constant>PGSQL_BOTH</constant> will return both numerical and associative indices.</para>'>
2031
+
2032
+
<!ENTITY pgsql.changelog.connection-object '<row xmlns="http://docbook.org/ns/docbook">
2033
+
<entry>8.1.0</entry>
2034
+
<entry>
2035
+
The <parameter>connection</parameter> parameter expects an <classname>PgSql\Connection</classname>
2036
+
instance now; previously, a &resource; was expected.
2037
+
</entry>
2038
+
</row>'>
2039
+
2040
+
<!ENTITY pgsql.changelog.result-object '<row xmlns="http://docbook.org/ns/docbook">
2041
+
<entry>8.1.0</entry>
2042
+
<entry>
2043
+
The <parameter>result</parameter> parameter expects an <classname>PgSql\Result</classname>
2044
+
instance now; previously, a &resource; was expected.
2045
+
</entry>
2046
+
</row>'>
2047
+
2048
+
<!ENTITY pgsql.changelog.lob-object '<row xmlns="http://docbook.org/ns/docbook">
2049
+
<entry>8.1.0</entry>
2050
+
<entry>
2051
+
The <parameter>lob</parameter> parameter expects an <classname>PgSql\Lob</classname>
2052
+
instance now; previously, a &resource; was expected.
2053
+
</entry>
2054
+
</row>'>
2055
+
2056
+
<!ENTITY pgsql.changelog.return-result-object '<row xmlns="http://docbook.org/ns/docbook">
2057
+
<entry>8.1.0</entry>
2058
+
<entry>
2059
+
Returns an <classname>PgSql\Result</classname> instance now;
2060
+
previously, a &resource; was returned.
2061
+
</entry>
2062
+
</row>'>
998
2063
999
2064
<!-- Common pieces for reference part END -->
1000
2065
...
...
@@ -1009,8 +2074,8 @@ extensions in order to use these functions.</simpara>'>
1009
2074
<!ENTITY sqlsafemode '<link xmlns="http://docbook.org/ns/docbook" linkend="ini.sql.safe-mode">SQL safe mode</link>'>
1010
2075
1011
2076
<!-- APD Notes -->
1012
-
<!ENTITY apd.debug-level.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1013
-
debug_level</parameter></term><listitem><para>An integer which is formed by adding
2077
+
<!ENTITY apd.debug-level.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2078
+
<parameter>debug_level</parameter></term><listitem><para>An integer which is formed by adding
1014
2079
together the <literal>XXX_TRACE</literal> constants.</para><para>It is not recommended
1015
2080
to use <constant>MEMORY_TRACE</constant>. It is very slow and does not appear to be accurate.
1016
2081
<constant>ASSIGNMENT_TRACE</constant> is not implemented yet.</para><para>To turn on all
...
...
@@ -1018,49 +2083,52 @@ functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the val
1018
2083
</listitem></varlistentry>'>
1019
2084
1020
2085
<!-- BCMath Notes -->
1021
-
<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1022
-
scale</parameter></term><listitem><para>This optional parameter is used to set the number
1023
-
of digits after the decimal place in the result. You can also set the global default scale
1024
-
for all functions by using <function>bcscale</function>.</para></listitem></varlistentry>'>
2086
+
<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2087
+
<parameter>scale</parameter></term><listitem><para>This optional parameter is used to set the number
2088
+
of digits after the decimal place in the result. If omitted, it will default to the scale set
2089
+
globally with the <function>bcscale</function> function, or fallback to <literal>0</literal> if
2090
+
this has not been set.</para></listitem></varlistentry>'>
1025
2091
1026
2092
<!-- CTYPE Notes -->
1027
2093
<!ENTITY note.ctype.parameter.integer '<note xmlns="http://docbook.org/ns/docbook"><para>
1028
-
If an <type>integer</type> between -128 and 255 inclusive is provided, it is interpreted as
2094
+
If an <type>int</type> between -128 and 255 inclusive is provided, it is interpreted as
1029
2095
the ASCII value of a single character (negative values have 256 added in order to allow
1030
2096
characters in the Extended ASCII range). Any other integer is interpreted as a string
1031
2097
containing the decimal digits of the integer.</para></note>'>
1032
2098
1033
-
<!-- FBSQL Notes -->
1034
-
<!ENTITY fbsql.link-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1035
-
link_identifier</parameter></term><listitem><para>A FrontBase link identifier
1036
-
returned by <function>fbsql_connect</function> or
1037
-
<function>fbsql_pconnect</function>.</para><para>If optional and not specified,
1038
-
the function will try to find an open link to the FrontBase server and if no
1039
-
such link is found it will try to create one as if
1040
-
<function>fbsql_connect</function> was called with no arguments.</para>
1041
-
</listitem></varlistentry>'>
2099
+
<!ENTITY note.ctype.parameter.non-string '<warning xmlns="http://docbook.org/ns/docbook"><para>
2100
+
As of PHP 8.1.0, passing a non-string argument is deprecated.
2101
+
In the future, the argument will be interpreted as a string instead of an ASCII codepoint.
2102
+
Depending on the intended behavior, the argument should either be cast to &string;
2103
+
or an explicit call to <function>chr</function> should be made.</para></warning>'>
1042
2104
1043
-
<!ENTITY fbsql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1044
-
result</parameter></term><listitem><para>A result identifier
1045
-
returned by <function>fbsql_query</function> or
1046
-
<function>fbsql_db_query</function>.</para></listitem></varlistentry>'>
2105
+
<!ENTITY ctype.result.empty-string 'When called with an empty string the result will always be &false;.'>
2106
+
2107
+
<!-- FTP Notes -->
2108
+
<!ENTITY ftp.changelog.ftp-param '<row xmlns="http://docbook.org/ns/docbook">
2109
+
<entry>8.1.0</entry>
2110
+
<entry>
2111
+
The <parameter>ftp</parameter> parameter expects an <classname>FTP\Connection</classname>
2112
+
instance now; previously, a &resource; was expected.
2113
+
</entry>
2114
+
</row>'>
2115
+
<!ENTITY ftp.parameter.ftp '<para xmlns="http://docbook.org/ns/docbook">An <classname>FTP\Connection</classname> instance.</para>'>
1047
2116
1048
2117
<!-- GMP Notes -->
1049
-
<!ENTITY gmp.return 'A GMP number <type xmlns="http://docbook.org/ns/docbook">resource</type>.'>
1050
-
<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">It can be either a GMP number <type>resource</type>, or a
1051
-
numeric string given that it is possible to convert the latter to a number.</para>'>
2118
+
<!ENTITY gmp.return 'A <classname xmlns="http://docbook.org/ns/docbook">GMP</classname> object.'>
2119
+
<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">A <classname>GMP</classname> object, an &integer; or a numeric &string;.</para>'>
1052
2120
1053
2121
<!-- MySQLi Notes -->
1054
-
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1055
-
result</parameter></term><listitem><para>Procedural style only: A result set
1056
-
identifier returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>
1057
-
or <function>mysqli_use_result</function>.</para></listitem></varlistentry>'>
1058
-
<!ENTITY mysqli.link.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1059
-
link</parameter></term><listitem><para>Procedural style only: A link identifier
2122
+
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2123
+
<parameter>result</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_result</classname>
2124
+
object returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>,
2125
+
<function>mysqli_use_result</function> or <function>mysqli_stmt_get_result</function>.</para></listitem></varlistentry>'>
2126
+
<!ENTITY mysqli.link.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2127
+
<parameter>mysql</parameter></term><listitem><para>Procedural style only: A <classname>mysqli</classname> object
1060
2128
returned by <function>mysqli_connect</function> or <function>mysqli_init</function>
1061
2129
</para></listitem></varlistentry>'>
1062
-
<!ENTITY mysqli.stmt.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1063
-
stmt</parameter></term><listitem><para>Procedural style only: A statement identifier
2130
+
<!ENTITY mysqli.stmt.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2131
+
<parameter>statement</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_stmt</classname> object
1064
2132
returned by <function>mysqli_stmt_init</function>.</para></listitem></varlistentry>'>
1065
2133
<!ENTITY mysqli.available.mysqlnd 'Available only with <link xmlns="http://docbook.org/ns/docbook"
1066
2134
linkend="book.mysqlnd">mysqlnd</link>.'>
...
...
@@ -1069,14 +2137,35 @@ linkend="book.mysqlnd">mysqlnd</link>.'>
1069
2137
hand-shake/authentication, which mysqlnd will use.</para><para>Libmysqlclient uses the default charset set in the
1070
2138
<filename>my.cnf</filename> or by an explicit call to <function>mysqli_options</function> prior to
1071
2139
calling <function>mysqli_real_connect</function>, but after <function>mysqli_init</function>.</para></note>'>
2140
+
<!ENTITY mysqli.integer.overflow.as.string.note '<note xmlns="http://docbook.org/ns/docbook">
2141
+
<para>If the number of rows is greater than <constant>PHP_INT_MAX</constant>,
2142
+
the number will be returned as a &string;.</para></note>'>
2143
+
<!ENTITY mysqli.sqlinjection.warning '<warning xmlns="http://docbook.org/ns/docbook">
2144
+
<title>Security warning: SQL injection</title><para>If the query contains any variable
2145
+
input then <link linkend="mysqli.quickstart.prepared-statements">parameterized
2146
+
prepared statements</link> should be used instead. Alternatively, the
2147
+
data must be properly formatted and all strings must be escaped using
2148
+
the <function>mysqli_real_escape_string</function>
2149
+
function.</para></warning>'>
2150
+
<!ENTITY mysqli.conditionalexception '<para xmlns="http://docbook.org/ns/docbook">
2151
+
If mysqli error reporting is enabled (<constant>MYSQLI_REPORT_ERROR</constant>) and the requested operation fails,
2152
+
a warning is generated. If, in addition, the mode is set to <constant>MYSQLI_REPORT_STRICT</constant>,
2153
+
a <classname>mysqli_sql_exception</classname> is thrown instead.</para>'>
2154
+
2155
+
<!-- Notes for PCRE -->
2156
+
<!ENTITY pcre.pattern.warning '<para xmlns="http://docbook.org/ns/docbook">
2157
+
If the regex pattern passed does not compile to a valid regex, an <constant>E_WARNING</constant> is emitted.
2158
+
</para>'>
1072
2159
1073
2160
<!-- Notes for SAPI/Apache -->
1074
-
<!ENTITY note.apache.nsapi-module '<para xmlns="http://docbook.org/ns/docbook">As of PHP 4.3.3 you can use this function with the
1075
-
<link linkend="book.nsapi">NSAPI server module</link> in Netscape/iPlanet/SunONE
1076
-
webservers, too.</para>'>
2161
+
<!ENTITY apache.req.module '<simpara xmlns="http://docbook.org/ns/docbook">This function is supported when PHP
2162
+
is installed as an Apache module webserver.
2163
+
</simpara>'>
1077
2164
1078
-
<!ENTITY apache.req.module '<simpara xmlns="http://docbook.org/ns/docbook">This function is only supported when PHP
1079
-
is installed as an Apache module.</simpara>'>
2165
+
<!-- Notes for SAPI/FPM -->
2166
+
<!ENTITY fpm.intro '<para xmlns="http://docbook.org/ns/docbook">FPM (FastCGI Process Manager) is
2167
+
a primary PHP FastCGI implementation containing some features (mostly) useful for heavy-loaded sites.
2168
+
</para>'>
1080
2169
1081
2170
<!-- SimpleXML Notes -->
1082
2171
<!ENTITY simplexml.iteration '<note xmlns="http://docbook.org/ns/docbook"><simpara>SimpleXML has made a rule of adding
...
...
@@ -1122,59 +2211,90 @@ the PHP &null; value.</simpara></note>'>
1122
2211
1123
2212
<!-- MSQL Notes -->
1124
2213
<!-- The msql.*.description entities are used in the parameters refsect1 -->
1125
-
<!ENTITY msql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1126
-
link_identifier</parameter></term><listitem><para>The mSQL connection.
2214
+
<!ENTITY msql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2215
+
<parameter>link_identifier</parameter></term><listitem><para>The mSQL connection.
1127
2216
If not specified, the last link opened by <function>msql_connect</function>
1128
2217
is assumed. If no such link is found, the function will try to establish a
1129
2218
link as if <function>msql_connect</function> was called, and use it.
1130
2219
</para></listitem></varlistentry>'>
1131
2220
1132
-
<!ENTITY msql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1133
-
result</parameter></term><listitem><para>The result <type>resource</type> that
2221
+
<!ENTITY msql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2222
+
<parameter>result</parameter></term><listitem><para>The result <type>resource</type> that
1134
2223
is being evaluated. This result comes from a call to
1135
2224
<function>msql_query</function>.</para></listitem></varlistentry>'>
1136
2225
1137
-
<!ENTITY msql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1138
-
field_offset</parameter></term><listitem><para>The numerical field offset. The
2226
+
<!ENTITY msql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2227
+
<parameter>field_offset</parameter></term><listitem><para>The numerical field offset. The
1139
2228
<parameter>field_offset</parameter> starts at <literal>1</literal>.</para></listitem></varlistentry>'>
1140
2229
1141
2230
1142
2231
<!-- MySQL Notes -->
1143
2232
<!-- The mysql.*.description entities are used in the parameters refsect1 -->
1144
-
<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1145
-
link_identifier</parameter></term><listitem><para>The MySQL connection. If the
2233
+
<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2234
+
<parameter>link_identifier</parameter></term><listitem><para>The MySQL connection. If the
1146
2235
link identifier is not specified, the last link opened by
1147
2236
<function>mysql_connect</function> is assumed. If no such link is found, it
1148
-
will try to create one as if <function>mysql_connect</function> was called
2237
+
will try to create one as if <function>mysql_connect</function> had been called
1149
2238
with no arguments. If no connection is found or established, an
1150
2239
<constant>E_WARNING</constant> level error is generated.</para></listitem>
1151
2240
</varlistentry>'>
1152
2241
1153
2242
<!ENTITY mysql.linkid-noreopen.description '<varlistentry
1154
-
xmlns="http://docbook.org/ns/docbook"><term><parameter>
1155
-
link_identifier</parameter></term><listitem><para>The MySQL connection. If the
2243
+
xmlns="http://docbook.org/ns/docbook"><term>
2244
+
<parameter>link_identifier</parameter></term><listitem><para>The MySQL connection. If the
1156
2245
link identifier is not specified, the last link opened by
1157
2246
<function>mysql_connect</function> is assumed. If no connection is found or
1158
2247
established, an <constant>E_WARNING</constant> level error is
1159
2248
generated.</para></listitem></varlistentry>'>
1160
2249
1161
-
<!ENTITY mysql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1162
-
result</parameter></term><listitem><para>The result <type>resource</type> that
2250
+
<!ENTITY mysql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2251
+
<parameter>result</parameter></term><listitem><para>The result <type>resource</type> that
1163
2252
is being evaluated. This result comes from a call to
1164
2253
<function>mysql_query</function>.</para></listitem></varlistentry>'>
1165
2254
1166
-
<!ENTITY mysql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1167
-
field_offset</parameter></term><listitem><para>The numerical field offset. The
2255
+
<!ENTITY mysql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2256
+
<parameter>field_offset</parameter></term><listitem><para>The numerical field offset. The
1168
2257
<parameter>field_offset</parameter> starts at <literal>0</literal>. If
1169
2258
<parameter>field_offset</parameter> does not exist, an error of level
1170
2259
<constant>E_WARNING</constant> is also issued.</para></listitem></varlistentry>'>
1171
2260
1172
-
<!ENTITY mysql.alternative.note '<para xmlns="http://docbook.org/ns/docbook">This extension is deprecated as of PHP 5.5.0, and will be removed in the future.
1173
-
Instead, the <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extension should be used.
1174
-
See also <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and
1175
-
<link linkend="faq.databases.mysql.deprecated">related FAQ</link> for more information.
2261
+
<!ENTITY mysql.alternative.note '<para xmlns="http://docbook.org/ns/docbook">This extension was deprecated in PHP 5.5.0, and it was removed in PHP 7.0.0.
2262
+
Instead, the <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extension should be used.
2263
+
See also <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
2264
+
Alternatives to this function include:</para>'>
2265
+
2266
+
<!ENTITY mysql.alternative.note.4-3-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 4.3.0, and it
2267
+
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
2268
+
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
2269
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
2270
+
Alternatives to this function include:</para>'>
2271
+
2272
+
<!ENTITY mysql.alternative.note.5-3-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 5.3.0, and it
2273
+
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
2274
+
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
2275
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
2276
+
Alternatives to this function include:</para>'>
2277
+
2278
+
<!ENTITY mysql.alternative.note.5-4-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 5.4.0, and it
2279
+
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
2280
+
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
2281
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
2282
+
Alternatives to this function include:</para>'>
2283
+
2284
+
<!ENTITY mysql.alternative.note.5-5-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 5.5.0, and it
2285
+
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
2286
+
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
2287
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
1176
2288
Alternatives to this function include:</para>'>
1177
2289
2290
+
<!ENTITY mysql.close.connections.result.sets '<para xmlns="http://docbook.org/ns/docbook">
2291
+
Open non-persistent MySQL connections and result sets are automatically destroyed when a
2292
+
PHP script finishes its execution. So, while explicitly closing open
2293
+
connections and freeing result sets is optional, doing so is recommended.
2294
+
This will immediately return resources to PHP and MySQL, which can
2295
+
improve performance. For related information, see
2296
+
<link linkend="language.types.resource.self-destruct">freeing resources</link></para>'>
2297
+
1178
2298
<!-- Sybase Notes -->
1179
2299
<!ENTITY sybase.ct.only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when
1180
2300
using the CT library interface to Sybase, and not with the DB library.
...
...
@@ -1183,8 +2303,8 @@ using the CT library interface to Sybase, and not with the DB library.
1183
2303
<!ENTITY sybase.db.only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when
1184
2304
using the DB library interface to Sybase, and not with the CT library.</simpara></note>'>
1185
2305
1186
-
<!ENTITY sybase.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1187
-
link_identifier</parameter></term><listitem><para>The Sybase connection. If the
2306
+
<!ENTITY sybase.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2307
+
<parameter>link_identifier</parameter></term><listitem><para>The Sybase connection. If the
1188
2308
link identifier is not specified, the last link opened by
1189
2309
<function>sybase_connect</function> is assumed. If no such link is found, it
1190
2310
will try to create one as if <function>sybase_connect</function> was called
...
...
@@ -1198,15 +2318,15 @@ determines the unit length. If it is <literal>0</literal> or omitted, the
1198
2318
default unit as specified for the page is used. In other cases, the coordinates
1199
2319
are measured in postscript points, disregarding the current unit.</para>'>
1200
2320
1201
-
<!ENTITY cpdf.mode.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1202
-
mode</parameter></term><listitem><para>The optional parameter <parameter>mode</parameter>
2321
+
<!ENTITY cpdf.mode.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2322
+
<parameter>mode</parameter></term><listitem><para>The optional parameter <parameter>mode</parameter>
1203
2323
determines the unit length. If it is <literal>0</literal> or omitted, the
1204
2324
default unit as specified for the page is used. In other cases, the coordinates
1205
2325
are measured in postscript points, disregarding the current unit.</para>
1206
2326
</listitem></varlistentry>'>
1207
2327
1208
-
<!ENTITY cpdf.pdf-document.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1209
-
pdf_document</parameter></term><listitem><para>The document handle, returned by
2328
+
<!ENTITY cpdf.pdf-document.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2329
+
<parameter>pdf_document</parameter></term><listitem><para>The document handle, returned by
1210
2330
<function>cpdf_open</function>.</para></listitem></varlistentry>'>
1211
2331
1212
2332
<!-- Xattr entities -->
...
...
@@ -1225,19 +2345,8 @@ brackets—for example, <literal>tcp://[fe80::1]:80</literal>.</simpara></note>'
1225
2345
</simpara></note>'>
1226
2346
1227
2347
<!-- Notes for tidy -->
1228
-
<!ENTITY note.tidy.ze2 '<note xmlns="http://docbook.org/ns/docbook"><simpara> This function is only available with
1229
-
Zend Engine 2 (PHP >= 5.0.0).</simpara></note>'>
1230
-
1231
2348
<!ENTITY tidy.object 'The <classname xmlns="http://docbook.org/ns/docbook">Tidy</classname> object.'>
1232
2349
1233
-
<!ENTITY note.tidy.1only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available in
1234
-
Tidy 1.0. It became obsolete in Tidy 2.0, and thus has been removed.
1235
-
</simpara></note>'>
1236
-
1237
-
<!ENTITY note.tidy.2only '<note xmlns="http://docbook.org/ns/docbook"><simpara>The optional parameters
1238
-
<parameter>config</parameter> and <parameter>encoding</parameter> were
1239
-
added in Tidy 2.0.</simpara></note>'>
1240
-
1241
2350
<!ENTITY tidy.conf-enc '<para xmlns="http://docbook.org/ns/docbook">The <parameter>config</parameter> parameter
1242
2351
can be passed either as an array or as a string. If a string is passed,
1243
2352
it is interpreted as the name of the configuration file, otherwise, it is
...
...
@@ -1270,7 +2379,7 @@ slash may also be necessary for directories.</simpara></note>'>
1270
2379
<!ENTITY Credit.Authors.and.Contributors 'Authors and Contributors'>
1271
2380
1272
2381
<!ENTITY Credit.Introduction '<para xmlns="http://docbook.org/ns/docbook"> We highlight the currently most active
1273
-
people on front page of the manual, but there are many more contributors who
2382
+
people on the front page of the manual, but there are many more contributors who
1274
2383
currently help in our work or have provided a great amount of help to the project
1275
2384
in the past. There are a lot of unnamed people who help out with user
1276
2385
notes on manual pages, which continually get included in the references, the
...
...
@@ -1326,48 +2435,21 @@ is used for managing public keys on a server to which the client is
1326
2435
using public key authentication, use the
1327
2436
<function>ssh2_auth_pubkey_file</function> function instead.</simpara></note>'>
1328
2437
1329
-
<!-- HTTP -->
1330
-
<!ENTITY see.http.request.options '<para xmlns="http://docbook.org/ns/docbook">See the full list of &link.http.request.options;.</para>'>
1331
-
<!ENTITY see.http.configuration.force_exit 'See the &link.http.configuration;
1332
-
<link xmlns="http://docbook.org/ns/docbook" linkend="http.configuration.force-exit">http.force_exit</link> for what "exits" means.'>
1333
-
1334
-
<!ENTITY link.http.configuration '<link xmlns="http://docbook.org/ns/docbook" linkend="http.configuration">INI setting</link>'>
1335
-
<!ENTITY link.http.request.option '<link xmlns="http://docbook.org/ns/docbook" linkend="http.request.options">request option</link>'>
1336
-
<!ENTITY link.http.request.options '<link xmlns="http://docbook.org/ns/docbook" linkend="http.request.options">request options</link>'>
1337
-
<!ENTITY link.http.request.info '<link xmlns="http://docbook.org/ns/docbook" linkend="http.request.info">Request/response information</link>'>
1338
-
<!ENTITY returns.http.response 'Returns the HTTP response(s) as string on
1339
-
success, or &false; on failure.'>
1340
-
<!ENTITY returns.http.false.orexits 'Returns &false; or <emphasis xmlns="http://docbook.org/ns/docbook">exits</emphasis> on success'>
2438
+
<!-- Session notes -->
1341
2439
<!ENTITY returns.session.storage.retval 'The return value (usually &true; on success, &false; on failure). Note this value is returned internally to PHP for processing.'>
1342
-
<!ENTITY http.request.affects 'Affects the following request method(s) only:'>
1343
-
<!ENTITY http.request.affects.any 'Affects any request method.'>
1344
-
<!ENTITY http.response.class.php51 'the <link xmlns="http://docbook.org/ns/docbook" linkend="class.httpresponse">
1345
-
<classname>HttpResponse</classname></link> class if you are using PHP 5.1.0
1346
-
and above'>
1347
-
<!ENTITY http.maynotwork.SAPI 'This may not work as expected with the following SAPI(s):'>
1348
-
<!ENTITY http.content.disposition 'The <literal xmlns="http://docbook.org/ns/docbook">Content-Disposition</literal>
1349
-
header is very useful if the data actually being sent came from a file or
1350
-
something similar, that should be "saved" by the client/user (i.e. by
1351
-
the browser's "Save as..." popup window).'>
1352
-
<!ENTITY http.use.ob_start 'For use with <function xmlns="http://docbook.org/ns/docbook">ob_start</function>.'>
1353
-
1354
-
<!ENTITY note.http.response.recalculate.etag.lm '<note xmlns="http://docbook.org/ns/docbook"><simpara>Previously calculated or defined <literal>ETag</literal>
1355
-
and <literal>Last-Modified</literal> will be recalculated and redefined.</simpara></note>'>
1356
-
<!ENTITY note.http.throttling.yields.process '<note xmlns="http://docbook.org/ns/docbook"><simpara>Provides a basic throttling mechanism, which will yield
1357
-
the current process or thread until the entity has been completely sent.</simpara></note>'>
1358
-
<!ENTITY note.http.send.API '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function should be used in conjunction with
1359
-
<function>http_send_data</function>, <function>http_send_file</function> &listendand; <function>http_send_stream</function>.</simpara></note>'>
1360
-
<!ENTITY note.http.send.API.mayuse '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function may be used in conjunction with
1361
-
<function>http_send_data</function>, <function>http_send_file</function> &listendand; <function>http_send_stream</function>.</simpara></note>'>
1362
-
<!ENTITY note.http.request.encodecookies '<note xmlns="http://docbook.org/ns/docbook"><simpara>The &link.http.request.option; <literal>encodecookies</literal> controls
1363
-
whether the cookie values should be <function>urlencode</function>d.</simpara></note>'>
1364
-
<!ENTITY note.http.request.affects.any '<note xmlns="http://docbook.org/ns/docbook"><simpara>&http.request.affects.any;</simpara></note>'>
1365
-
<!ENTITY note.http.ob.once '<note xmlns="http://docbook.org/ns/docbook"><simpara>This output handler can only be used once.</simpara></note>'>
1366
2440
1367
2441
<!-- XMLWriter Notes -->
1368
-
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1369
-
xmlwriter</parameter></term><listitem><para>Only for procedural calls.
1370
-
The XMLWriter <type>resource</type> that is being modified. This resource comes from a call to <function>xmlwriter_open_uri</function> or <function>xmlwriter_open_memory</function>.</para></listitem></varlistentry>'>
2442
+
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2443
+
<parameter>writer</parameter></term><listitem><para>Only for procedural calls.
2444
+
The <classname>XMLWriter</classname> instance that is being modified. This object is returned from a call to <function>xmlwriter_open_uri</function> or <function>xmlwriter_open_memory</function>.</para></listitem></varlistentry>'>
2445
+
2446
+
<!ENTITY xmlwriter.changelog.writer-param '<row xmlns="http://docbook.org/ns/docbook">
2447
+
<entry>8.0.0</entry>
2448
+
<entry>
2449
+
<parameter>writer</parameter> expects an <classname>XMLWriter</classname>
2450
+
instance now; previously, a <type>resource</type> was expected.
2451
+
</entry>
2452
+
</row>'>
1371
2453
1372
2454
<!-- SOAP notes -->
1373
2455
<!ENTITY soap.wsdl.mode.only "<note xmlns='http://docbook.org/ns/docbook'><para>This function only works in WSDL mode.</para></note>">
...
...
@@ -1383,6 +2465,16 @@ The XMLWriter <type>resource</type> that is being modified. This resource comes
1383
2465
<!ENTITY svn.referto.status 'Refer to <link xmlns="http://docbook.org/ns/docbook" linkend="svn.constants.status">status constants</link> for possible values.'>
1384
2466
<!ENTITY svn.referto.type 'Refer to <link xmlns="http://docbook.org/ns/docbook" linkend="svn.constants.type">type constants</link> for possible values.'>
1385
2467
2468
+
<!-- FANN notes -->
2469
+
<!ENTITY fann.ann.description '<para xmlns="http://docbook.org/ns/docbook">Neural network <type>resource</type>.</para>'>
2470
+
<!ENTITY fann.train.description '<para xmlns="http://docbook.org/ns/docbook">Neural network training data <type>resource</type>.</para>'>
2471
+
<!ENTITY fann.errdat.description '<para xmlns="http://docbook.org/ns/docbook">Either neural network <type>resource</type> or neural network trainining data <type>resource</type>.</para>'>
2472
+
<!ENTITY fann.return.void '<para xmlns="http://docbook.org/ns/docbook">No value is returned.</para>'>
2473
+
<!ENTITY fann.return.bool '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>
2474
+
<!ENTITY fann.return.ann '<para xmlns="http://docbook.org/ns/docbook"> Returns a neural network <type>resource</type> on success, or &false; on error.</para>'>
2475
+
<!ENTITY fann.return.train '<para xmlns="http://docbook.org/ns/docbook"> Returns a train data <type>resource</type> on success, or &false; on error.</para>'>
2476
+
<!ENTITY fann.note.function.fann-2.2 '<note xmlns="http://docbook.org/ns/docbook"><para>This function is only available if the fann extension has been build against libfann >= 2.2.</para></note>'>
2477
+
1386
2478
<!-- Imagick generic return types -->
1387
2479
<!ENTITY imagick.return.success 'Returns &true; on success.'>
1388
2480
<!ENTITY imagick.imagick.throws 'Throws ImagickException on error.'>
...
...
@@ -1409,8 +2501,12 @@ The XMLWriter <type>resource</type> that is being modified. This resource comes
1409
2501
<!ENTITY imagick.method.available.0x653 'This method is available if Imagick has been compiled against ImageMagick version 6.5.3 or newer.'>
1410
2502
<!ENTITY imagick.method.available.0x657 'This method is available if Imagick has been compiled against ImageMagick version 6.5.7 or newer.'>
1411
2503
2504
+
<!ENTITY imagick.method.not.available.0x700 'This method is not available if Imagick has been compiled against ImageMagick version 7.0.0 or newer.'>
2505
+
1412
2506
<!ENTITY imagick.constant.available 'This constant is available if Imagick has been compiled against ImageMagick version'>
1413
2507
2508
+
<!ENTITY imagick.deprecated.function-3-4-4 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function has been <emphasis>DEPRECATED</emphasis> as of Imagick 3.4.4. Relying on this function is highly discouraged.</simpara></warning>'>
2509
+
1414
2510
<!-- Imagick default channel information -->
1415
2511
<!ENTITY imagick.default.channel.info 'Defaults to <constant xmlns="http://docbook.org/ns/docbook">Imagick::CHANNEL_DEFAULT</constant>. Refer to this list of <link xmlns="http://docbook.org/ns/docbook" linkend="imagick.constants.channel">channel constants</link>'>
1416
2512
...
...
@@ -1495,11 +2591,32 @@ method has been removed from the phar extension as of version 2.0.0. Alternativ
1495
2591
implementations are available using <function>PharFileInfo::isCompressed</function>,
1496
2592
<function>PharFileInfo::decompress</function>, and <function>PharFileInfo::compress</function>.</para></note>'>
1497
2593
2594
+
<!ENTITY phar.note.performance '<note xmlns="http://docbook.org/ns/docbook">
2595
+
<simpara>
2596
+
<function>Phar::addFile</function>, <function>Phar::addFromString</function> and <function>Phar::offsetSet</function>
2597
+
save a new phar archive each time they are called. If performance is a concern,
2598
+
<function>Phar::buildFromDirectory</function> or <function>Phar::buildFromIterator</function>
2599
+
should be used instead.
2600
+
</simpara>
2601
+
</note>'>
2602
+
2603
+
<!ENTITY phardata.note.performance '<note xmlns="http://docbook.org/ns/docbook">
2604
+
<simpara>
2605
+
<function>PharData::addFile</function>, <function>PharData::addFromString</function> and <function>PharData::offsetSet</function>
2606
+
save a new phar archive each time they are called. If performance is a concern,
2607
+
<function>PharData::buildFromDirectory</function> or <function>PharData::buildFromIterator</function>
2608
+
should be used instead.
2609
+
</simpara>
2610
+
</note>'>
2611
+
1498
2612
<!-- XML -->
1499
-
<!ENTITY libxml.required '<para xmlns="http://docbook.org/ns/docbook">This extension requires the
1500
-
<link linkend="book.libxml">libxml</link> PHP extension. This means that passing in
1501
-
<option role="configure">--enable-libxml</option> is also required, although this is implicitly accomplished
1502
-
because libxml is enabled by default.</para>'>
2613
+
<!ENTITY libxml.required '<para xmlns="http://docbook.org/ns/docbook">
2614
+
This extension requires the <link linkend="book.libxml">libxml</link> PHP extension.
2615
+
This means passing the <option role="configure">--with-libxml</option>,
2616
+
or prior to PHP 7.4 the <option role="configure">--enable-libxml</option>,
2617
+
configuration flag, although this is implicitly accomplished because libxml
2618
+
is enabled by default.
2619
+
</para>'>
1503
2620
1504
2621
<!-- XMLReader -->
1505
2622
<!ENTITY xmlreader.libxml20620.note '<caution xmlns="http://docbook.org/ns/docbook"><para>This function is only available when PHP is compiled against libxml 20620 or later.</para></caution>'>
...
...
@@ -1534,6 +2651,34 @@ to be references, then they must be references in the passed argument list.'>
1534
2651
1535
2652
<!ENTITY reflection.export.param.name 'The reflection to export.'>
1536
2653
2654
+
<!ENTITY reflection.getattributes.param.name '<varlistentry xmlns="http://docbook.org/ns/docbook">
2655
+
<term><parameter>name</parameter></term>
2656
+
<listitem>
2657
+
<para>
2658
+
Filter the results to include only <classname>ReflectionAttribute</classname>
2659
+
instances for attributes matching this class name.
2660
+
</para>
2661
+
</listitem>
2662
+
</varlistentry>'>
2663
+
2664
+
<!ENTITY reflection.getattributes.param.flags '<varlistentry xmlns="http://docbook.org/ns/docbook">
2665
+
<term><parameter>flags</parameter></term>
2666
+
<listitem>
2667
+
<para>
2668
+
Flags for determining how to filter the results, if <parameter>name</parameter>
2669
+
is provided.
2670
+
</para>
2671
+
<para>
2672
+
Default is <literal>0</literal> which will only return results for attributes that
2673
+
are of the class <parameter>name</parameter>.
2674
+
</para>
2675
+
<para>
2676
+
The only other option available, is to use <constant>ReflectionAttribute::IS_INSTANCEOF</constant>,
2677
+
which will instead use <literal>instanceof</literal> for filtering.
2678
+
</para>
2679
+
</listitem>
2680
+
</varlistentry>'>
2681
+
1537
2682
<!-- SPL -->
1538
2683
<!ENTITY spl.datastructures.intro.title '<title xmlns="http://docbook.org/ns/docbook">Datastructures</title>'>
1539
2684
...
...
@@ -1553,10 +2698,13 @@ to be references, then they must be references in the passed argument list.'>
1553
2698
<!ENTITY spl.misc.intro.title '<title xmlns="http://docbook.org/ns/docbook">Miscellaneous Classes and Interfaces</title>'>
1554
2699
<!ENTITY spl.misc.intro '<partintro xmlns="http://docbook.org/ns/docbook"><para>Classes and interfaces which do not fit into the other SPL categories.</para></partintro>'>
1555
2700
2701
+
<!-- ZIP -->
2702
+
<!ENTITY zip.filename.separator '<note xmlns="http://docbook.org/ns/docbook"><simpara>For maximum portability, it is recommended to always use forward slashes (<literal>/</literal>) as directory separator in ZIP filenames.</simpara></note>'>
2703
+
1556
2704
<!-- Win32Service -->
1557
2705
<!ENTITY win32service.false.error ', &false; if there is a problem with the parameters or a <link xmlns="http://docbook.org/ns/docbook" linkend="win32service.constants.errors">Win32 Error Code</link> on failure.'>
1558
2706
<!ENTITY win32service.success.false.error 'Returns &true; on success&win32service.false.error;'>
1559
-
<!ENTITY win32service.noerror.false.error 'Returns <constant xmlns="http://docbook.org/ns/docbook">WIN32_NO_ERROR</constant> on success&win32service.false.error;'>
2707
+
<!ENTITY win32service.noerror.false.error 'returned <constant xmlns="http://docbook.org/ns/docbook">WIN32_NO_ERROR</constant> on success&win32service.false.error;'>
1560
2708
1561
2709
<!-- SNMP -->
1562
2710
<!ENTITY snmp.set.type.values '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1714,14 +2862,1565 @@ paths</simpara></warning>
1714
2862
<!ENTITY mongo.setreadpreference.returnvalues '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>
1715
2863
<!ENTITY mongo.setreadpreference.errors '<para xmlns="http://docbook.org/ns/docbook">Emits <constant>E_WARNING</constant> if either parameter is invalid, or if one or more tag sets are provided with the <constant>MongoClient::RP_PRIMARY</constant> read preference mode.</para>'>
1716
2864
<!ENTITY mongo.getreadpreference.returnvalues '<para xmlns="http://docbook.org/ns/docbook">This function returns an array describing the read preference. The array contains the values <literal>type</literal> for the string read preference mode (corresponding to the <classname>MongoClient</classname> constants), and <literal>tagsets</literal> containing a list of all tag set criteria. If no tag sets were specified, <literal>tagsets</literal> will not be present in the array.</para>'>
1717
-
<!ENTITY mongo.writes.parameters.writeconcern '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"w"</literal></para><para>See <link linkend="mongo.writeconcerns">WriteConcerns</link>. The default value for <classname>MongoClient</classname> is <literal>1</literal>.</para></listitem>'>
1718
-
<!ENTITY mongo.writes.parameters.writeconcerntimeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"wtimeout"</literal></para><para>How long to wait for <link linkend="mongo.writeconcerns">WriteConcern</link> acknowledgement. The default value for <classname>MongoClient</classname> is <literal>10000</literal> milliseconds.</para></listitem>'>
1719
-
<!ENTITY mongo.writes.parameters.fsync '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"fsync"</literal></para><para>Boolean, defaults to &false;. Forces the insert to be synced to disk before returning success. If &true;, an acknowledged insert is implied and will override setting <literal>w</literal> to <literal>0</literal>.</para></listitem>'>
1720
-
<!-- <!ENTITY mongo.writes.parameters.sockettimeoutms '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"socketTimeoutMS"</literal></para><para>Integer, defaults to <literal>MongoCursor::$timeout</literal>. If acknowledged writes are used, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a <classname>MongoCursorTimeoutException</classname> will be thrown.</para></listitem>'> -->
1721
-
<!ENTITY mongo.writes.parameters.journal '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"j"</literal></para><para>Boolean, defaults to &false;. Forces the insert to be synced to the journal before returning success. If &true;, an acknowledged insert is implied and will override setting <literal>w</literal> to <literal>0</literal>.</para></listitem>'>
1722
-
<!ENTITY mongo.writes.parameters.safe '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"safe"</literal></para><para><emphasis>Deprecated</emphasis>. Please use the <link linkend="mongo.writeconcerns">WriteConcern</link> <literal>w</literal> option.</para></listitem>'>
1723
-
<!ENTITY mongo.writes.parameters.timeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"timeout"</literal></para><para>Integer, defaults to <literal>MongoCursor::$timeout</literal>. If acknowledged writes are used, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a <classname>MongoCursorTimeoutException</classname> will be thrown.</para></listitem>'>
1724
-
<!ENTITY mongo.errors.exceptions.writeconcern '<para xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoCursorException</classname> if the "w" option is set and the write fails.</para><para xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoCursorTimeoutException</classname> if the "w" option is set to a value greater than one and the operation takes longer than <varname>MongoCursor::$timeout</varname> milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout. The operation in <literal>MongoCollection::$wtimeout</literal> is milliseconds.</para>'>
2865
+
<!ENTITY mongo.setwriteconcern.parameters '<variablelist xmlns="http://docbook.org/ns/docbook"><varlistentry><term><parameter>w</parameter></term><listitem><para>The write concern. This may be an integer denoting the number of servers required to acknowledge the write, or a string mode (e.g. "majority").</para></listitem></varlistentry><varlistentry><term><parameter>wtimeout</parameter></term><listitem><para>The maximum number of milliseconds to wait for the server to satisfy the write concern.</para></listitem></varlistentry></variablelist>'>
2866
+
<!ENTITY mongo.setwriteconcern.returnvalues '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>
2867
+
<!ENTITY mongo.setwriteconcern.errors '<para xmlns="http://docbook.org/ns/docbook">Emits <constant>E_WARNING</constant> if the <literal>w</literal> parameter is not an integer or string value.</para>'>
2868
+
<!ENTITY mongo.getwriteconcern.returnvalues '<para xmlns="http://docbook.org/ns/docbook">This function returns an array describing the write concern. The array contains the values <literal>w</literal> for an integer acknowledgement level or string mode, and <literal>wtimeout</literal> denoting the maximum number of milliseconds to wait for the server to satisfy the write concern.</para>'>
2869
+
<!ENTITY mongo.command.parameters.maxtimems '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"maxTimeMS"</literal></para><para>Specifies a cumulative time limit in milliseconds for processing the operation on the server (does not include idle time). If the operation is not completed by the server within the timeout period, a <classname>MongoExecutionTimeoutException</classname> will be thrown.</para></listitem>'>
2870
+
<!ENTITY mongo.index.parameters.background '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"background"</literal></para><para>Builds the index in the background so that building an index does <emphasis>not</emphasis> block other database activities. Specify &true; to build in the background. The default value is &false;.</para><warning xmlns="http://docbook.org/ns/docbook"><para>Prior to MongoDB 2.6.0, index builds on secondaries were executed as foreground operations, irrespective of this option. See <link xlink:href="&url.mongodb.dochub.indexes.rs;" xmlns:xlink="http://www.w3.org/1999/xlink">Building Indexes with Replica Sets</link> for more information.</para></warning></listitem>'>
2871
+
<!ENTITY mongo.index.parameters.dropdups '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"dropDups"</literal></para><para>Specify &true; to force creation of a unique index where the collection may contain duplicate values for a key. MongoDB will index the first occurrence of a key and delete all subsequent documents from the collection that contain a duplicate value for that key. The default value is &false;.</para><warning xmlns="http://docbook.org/ns/docbook"><para><literal>"dropDups"</literal> may delete data from your database. Use with extreme caution.</para></warning><note xmlns="http://docbook.org/ns/docbook"><para>This option is not supported on MongoDB 2.8+. Index creation will fail if the collection contains duplicate values.</para></note></listitem>'>
2872
+
<!ENTITY mongo.index.parameters.expireafterseconds '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"expireAfterSeconds"</literal></para><para>The value of this option should specify the number of seconds after which a document should be considered expired and automatically removed from the collection. This option is only compatible with single-field indexes where the field will contain <classname>MongoDate</classname> values.</para><note xmlns="http://docbook.org/ns/docbook"><para>This feature is available in MongoDB 2.2+. See <link xlink:href="&url.mongodb.docs.expire_data;" xmlns:xlink="http://www.w3.org/1999/xlink">Expire Data from Collections by Setting TTL</link> for more information.</para></note></listitem>'>
2873
+
<!ENTITY mongo.index.parameters.name '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"name"</literal></para><para>A optional name that uniquely identifies the index.</para><note xmlns="http://docbook.org/ns/docbook"><para>By default, the driver will generate an index name based on the index's field(s) and ordering or type. For example, a compound index <literal>array("x" => 1, "y" => -1)</literal> would be named <literal>"x_1_y_-1"</literal> and a geospatial index <literal>array("loc" => "2dsphere")</literal> would be named <literal>"loc_2dsphere"</literal>. For indexes with many fields, it is possible that the generated name might exceed MongoDB's <link xlink:href="&url.mongodb.docs.limits;#Index-Name-Length" xmlns:xlink="http://www.w3.org/1999/xlink">limit for index names</link>. The <literal>"name"</literal> option may be used in that case to supply a shorter name.</para></note></listitem>'>
2874
+
<!ENTITY mongo.index.parameters.sparse '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"sparse"</literal></para><para>Specify &true; to create a sparse index, which only indexes documents containing a specified field. The default value is &false;.</para></listitem>'>
2875
+
<!ENTITY mongo.index.parameters.unique '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"unique"</literal></para><para>Specify &true; to create a unique index. The default value is &false;. This option applies only to ascending/descending indexes.</para><note xmlns="http://docbook.org/ns/docbook"><para>When MongoDB indexes a field, if a document does not have a value for the field, a &null; value is indexed. If multiple documents do not contain a field, a unique index will reject all but the first of those documents. The <literal>"sparse"</literal> option may be used to overcome this, since it will prevent documents without the field from being indexed.</para></note></listitem>'>
2876
+
<!ENTITY mongo.listcollections.note '<note xmlns="http://docbook.org/ns/docbook"><simpara>This method will use the <link xlink:href="&url.mongodb.docs.command;listCollections" xmlns:xlink="http://www.w3.org/1999/xlink">listCollections</link> database command when communicating with MongoDB 2.8+. For previous database versions, the method will query the special <literal>system.namespaces</literal> collection.</simpara></note>'>
2877
+
<!ENTITY mongo.listcollections.parameters.filter '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"filter"</literal></para><para>Optional query criteria. If provided, this criteria will be used to filter the collections included in the result.</para><para>Relevant fields that may be queried include <literal>"name"</literal> (collection name as a string, without the database name prefix) and <literal>"options" (object containing options used to create the collection).</literal>.</para><note><simpara>MongoDB 2.6 and earlier versions require the <literal>"name"</literal> criteria, if specified, to be a string value (i.e. equality match). This is because the driver must prefix the value with the database name in order to query the <literal>system.namespaces</literal> collection. Later versions of MongoDB do not have this limitation, as the driver will use the listCollections command.</simpara></note></listitem>'>
2878
+
<!ENTITY mongo.listcollections.parameters.includesystemcollections '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"includeSystemCollections"</literal></para><para>Boolean, defaults to &false;. Determines whether system collections should be included in the result.</para></listitem>'>
2879
+
<!ENTITY mongo.writes.parameters.writeconcern '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"w"</literal></para><para>See <link linkend="mongo.writeconcerns">Write Concerns</link>. The default value for <classname>MongoClient</classname> is <literal>1</literal>.</para></listitem>'>
2880
+
<!ENTITY mongo.writes.parameters.writeconcerntimeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"wtimeout"</literal></para><para>Deprecated alias for <literal>"wTimeoutMS"</literal>.</para></listitem>'>
2881
+
<!ENTITY mongo.writes.parameters.writeconcerntimeoutms '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"wTimeoutMS"</literal></para><para>This option specifies the time limit, in milliseconds, for <link linkend="mongo.writeconcerns">write concern</link> acknowledgement. It is only applicable when <literal>"w"</literal> is greater than <literal>1</literal>, as the timeout pertains to replication. If the write concern is not satisfied within the time limit, a <classname>MongoCursorException</classname> will be thrown. A value of <literal>0</literal> may be specified to block indefinitely. The default value for <classname>MongoClient</classname> is <literal>10000</literal> (ten seconds).</para></listitem>'>
2882
+
<!ENTITY mongo.writes.parameters.fsync '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"fsync"</literal></para><para>Boolean, defaults to &false;. If journaling is enabled, it works exactly like <literal>"j"</literal>. If journaling is not enabled, the write operation blocks until it is synced to database files on disk. If &true;, an acknowledged insert is implied and this option will override setting <literal>"w"</literal> to <literal>0</literal>.</para><note><simpara>If journaling is enabled, users are strongly encouraged to use the <literal>"j"</literal> option instead of <literal>"fsync"</literal>. Do not use <literal>"fsync"</literal> and <literal>"j"</literal> simultaneously, as that will result in an error.</simpara></note></listitem>'>
2883
+
<!ENTITY mongo.writes.parameters.sockettimeoutms '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"socketTimeoutMS"</literal></para><para>This option specifies the time limit, in milliseconds, for socket communication. If the server does not respond within the timeout period, a <classname>MongoCursorTimeoutException</classname> will be thrown and there will be no way to determine if the server actually handled the write or not. A value of <literal>-1</literal> may be specified to block indefinitely. The default value for <classname>MongoClient</classname> is <literal>30000</literal> (30 seconds).</para></listitem>'>
2884
+
<!ENTITY mongo.writes.parameters.journal '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"j"</literal></para><para>Boolean, defaults to &false;. Forces the write operation to block until it is synced to the journal on disk. If &true;, an acknowledged write is implied and this option will override setting <literal>"w"</literal> to <literal>0</literal>.</para><note><simpara>If this option is used and journaling is disabled, MongoDB 2.6+ will raise an error and the write will fail; older server versions will simply ignore the option.</simpara></note></listitem>'>
2885
+
<!ENTITY mongo.writes.parameters.safe '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"safe"</literal></para><para>Deprecated. Please use the <link linkend="mongo.writeconcerns">write concern</link> <literal>"w"</literal> option.</para></listitem>'>
2886
+
<!ENTITY mongo.writes.parameters.timeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"timeout"</literal></para><para>Deprecated alias for <literal>"socketTimeoutMS"</literal>.</para></listitem>'>
2887
+
<!ENTITY mongo.errors.exceptions.writeconcern '<para xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoCursorException</classname> if the <literal>"w"</literal> option is set and the write fails.</para><para xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoCursorTimeoutException</classname> if the <literal>"w"</literal> option is set to a value greater than one and the operation takes longer than <varname>MongoCursor::$timeout</varname> milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout. The operation in <varname>MongoCollection::$wtimeout</varname> is milliseconds.</para>'>
1725
2888
<!ENTITY mongo.errors.deprecated '<para xmlns="http://docbook.org/ns/docbook">Issues <constant>E_DEPRECATED</constant> warning</para>'>
1726
2889
<!ENTITY mongo.gridfs.store.metadata.note '<note xmlns="http://docbook.org/ns/docbook"><para>These fields may also overwrite those that would be created automatically by the driver, as described in the MongoDB core documentation for the <link xlink:href="&url.mongodb.docs.gridfs;#the-files-collection" xmlns:xlink="http://www.w3.org/1999/xlink">files collection</link>. Some practical use cases for this behavior would be to specify a custom <literal>chunkSize</literal> or <literal>_id</literal> for the file.</para></note>'>
1727
-
<!ENTITY mongo.gridfs.store.return '<para xmlns="http://docbook.org/ns/docbook">Returns the <literal>_id</literal> of the saved file document. This will be a generated <classname>MongoId</classname> unless an <literal>_id</literal> was explicitly specified in the <parameter>extra</parameter> parameter.</para>'>
2890
+
<!ENTITY mongo.gridfs.store.return '<para xmlns="http://docbook.org/ns/docbook">Returns the <literal>_id</literal> of the saved file document. This will be a generated <classname>MongoId</classname> unless an <literal>_id</literal> was explicitly specified in the <parameter>metadata</parameter> parameter.</para>'>
2891
+
<!ENTITY mongo.mongowritebatch.writeoptions.description '<listitem xmlns="http://docbook.org/ns/docbook"><para>An array of Write Options.<informaltable><thead><row><entry>key</entry><entry>value meaning</entry></row></thead><tbody><row><entry>w (int|string)</entry><entry><link linkend="mongo.writeconcerns">Write concern</link> value</entry></row><row><entry>wtimeout (int)</entry><entry><link linkend="mongo.writeconcerns">Maximum time to wait for replication</link></entry></row><row><entry>ordered</entry><entry>Determines if MongoDB must apply this batch in order. Ordered writes execute serially (i.e. one at a time) and execution will stop after the first error. Unordered writes may execute in parallel and execution will not stop after the first error. Defaults to &true;</entry></row><row><entry>j (bool)</entry><entry>Wait for journaling on the primary. This value is discouraged, use WriteConcern instead</entry></row><row><entry>fsync (bool)</entry><entry>Wait for fsync on the primary. This value is discouraged, use WriteConcern instead</entry></row></tbody></informaltable></para></listitem>'>
2892
+
<!ENTITY mongo.mongowritebatch.collection.description '<listitem xmlns="http://docbook.org/ns/docbook"><para>The <classname>MongoCollection</classname> to execute the batch on. Its <link linkend="mongo.writeconcerns">write concern</link> will be copied and used as the default write concern if none is given as <parameter>$write_options</parameter> or during <methodname>MongoWriteBatch::execute</methodname>.</para></listitem>'>
2893
+
<!ENTITY mongo.context.server ' <varlistentry xmlns="http://docbook.org/ns/docbook"> <term> <parameter>server</parameter> </term> <listitem> <para> An array containing the basic information about the server that was picked. <informaltable> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>hash</entry> <entry>server hash, example: <literal>localhost:27017;-;X;56052</literal></entry> </row> <row> <entry>type</entry> <entry>Node type (primary/secondary/mongos/arbiter): <literal>2</literal></entry> </row> <row> <entry>max_bson_size</entry> <entry>The maximum BSON Size over the wire this node accepts: <literal>16777216</literal></entry> </row> <row> <entry>max_message_size</entry> <entry>The maximum Message Size over the wire this node accepts: <literal>48000000</literal></entry> </row> <row> <entry>request_id</entry> <entry>The request identifier for this message: <literal>42</literal></entry> </row> </tbody> </tgroup> </informaltable> </para> </listitem> </varlistentry>'>
2894
+
<!ENTITY mongo.context.writeoptions '<varlistentry xmlns="http://docbook.org/ns/docbook"> <term> <parameter>writeOptions</parameter> </term> <listitem> <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>ordered</entry> <entry>boolean, if the operation (in case of batch operation) must be executed sequentually (ordered=true)</entry> </row> <row> <entry>writeConcern</entry> <entry>An array of writeConcern options (see below)</entry> </row> </tbody> </tgroup> </informaltable> <table> <title>writeConcern array values</title> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>fsync</entry> <entry>boolean, force flushing to disk before returning</entry> </row> <row> <entry>j</entry> <entry>boolean, force journal write before returning</entry> </row> <row> <entry>wtimeout</entry> <entry>integer, milliseconds, maximum time the primary is allowed to wait to verify replication</entry> </row> <row> <entry>w</entry> <entry>integer=server count, or string=replication-tag</entry> </row> </tbody> </tgroup> </table> </para> </listitem> </varlistentry>'>
2895
+
<!ENTITY mongo.context.protocoloptions ' <varlistentry xmlns="http://docbook.org/ns/docbook"> <term> <parameter>protocolOptions</parameter> </term> <listitem> <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>message_length</entry> <entry>The total size (in bytes) of the encoded message being sent over the wire</entry> </row> <row> <entry>request_id</entry> <entry>The request identifier for this message: <literal>42</literal></entry> </row> <row> <entry>namespace</entry> <entry>The MongoDB namespace used for the protocol message <literal>dbname.collectionname</literal></entry> </row> </tbody> </tgroup> </informaltable> </para> </listitem> </varlistentry>'>
2896
+
<!ENTITY mongo.alternative.class.note '<para
2897
+
xmlns="http://docbook.org/ns/docbook">This extension that defines this class
2898
+
is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.
2899
+
Alternatives to this class include:</para>'>
2900
+
<!ENTITY mongo.noalternative.class.note '<para
2901
+
xmlns="http://docbook.org/ns/docbook">This extension that defines this class
2902
+
is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.
2903
+
There is no equivalent for this class in the new extension.</para>'>
2904
+
<!ENTITY mongo.alternative.method.note '<para
2905
+
xmlns="http://docbook.org/ns/docbook">This extension that defines this method
2906
+
is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.
2907
+
Alternatives to this method include:</para>'>
2908
+
<!ENTITY mongo.noalternative.method.note '<para
2909
+
xmlns="http://docbook.org/ns/docbook">This extension that defines this method
2910
+
is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.
2911
+
There is no equivalent for this method in the new extension.</para>'>
2912
+
<!ENTITY mongo.alternative.phplib.note '<para
2913
+
xmlns="http://docbook.org/ns/docbook">This extension that defines this method
2914
+
is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.
2915
+
There is no equivalent for this method in the new extension, but there is an
2916
+
alternative in the <link linkend="mongodb.overview">PHP library</link>:</para>'>
2917
+
2918
+
<!ENTITY mongo.deprecated.note '<para
2919
+
xmlns="http://docbook.org/ns/docbook">This extension is deprecated. Instead,
2920
+
the <link linkend="set.mongodb">MongoDB</link> extension should be
2921
+
used.</para>'>
2922
+
2923
+
<!-- mongodb -->
2924
+
<!ENTITY mongodb.changelog.tentative-return-types '
2925
+
<row xmlns="http://docbook.org/ns/docbook">
2926
+
<entry>PECL mongodb 1.15.0</entry>
2927
+
<entry>
2928
+
Return types for methods are declared as tentative on PHP 8.0 and newer,
2929
+
triggering deprecation notices in code that implements this interface
2930
+
without declaring the appropriate return types. The <code>#[ReturnTypeWillChange]</code>
2931
+
attribute can be added to silence the deprecation notice.
2932
+
</entry>
2933
+
</row>
2934
+
'>
2935
+
2936
+
<!ENTITY mongodb.option.collation '
2937
+
<row xmlns="http://docbook.org/ns/docbook">
2938
+
<entry>collation</entry>
2939
+
<entry><type class="union"><type>array</type><type>object</type></type></entry>
2940
+
<entry>
2941
+
<para>
2942
+
<link xlink:href="&url.mongodb.docs.collation;" xmlns:xlink="http://www.w3.org/1999/xlink">Collation</link> allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the <literal>"locale"</literal> field is mandatory; all other collation fields are optional. For descriptions of the fields, see <link xlink:href="&url.mongodb.docs.collation;#collation-document" xmlns:xlink="http://www.w3.org/1999/xlink">Collation Document</link>.
2943
+
</para>
2944
+
<para>
2945
+
If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons.
2946
+
</para>
2947
+
<para>
2948
+
This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
2949
+
</para>
2950
+
</entry>
2951
+
</row>
2952
+
'>
2953
+
<!ENTITY mongodb.option.let '
2954
+
<row xmlns="http://docbook.org/ns/docbook">
2955
+
<entry>let</entry>
2956
+
<entry><type class="union"><type>array</type><type>object</type></type></entry>
2957
+
<entry>
2958
+
<para>
2959
+
Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an aggregate expression context (e.g. <literal>$$var</literal>).
2960
+
</para>
2961
+
<para>
2962
+
This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.
2963
+
</para>
2964
+
</entry>
2965
+
</row>
2966
+
'>
2967
+
<!ENTITY mongodb.option.encryption.keyVaultClient '
2968
+
<row xmlns="http://docbook.org/ns/docbook">
2969
+
<entry>keyVaultClient</entry>
2970
+
<entry><classname>MongoDB\Driver\Manager</classname></entry>
2971
+
<entry>The Manager used to route data key queries to a separate MongoDB cluster. By default, the current Manager and cluster is used.</entry>
2972
+
</row>
2973
+
'>
2974
+
<!ENTITY mongodb.option.encryption.keyVaultNamespace '
2975
+
<row xmlns="http://docbook.org/ns/docbook">
2976
+
<entry>keyVaultNamespace</entry>
2977
+
<entry><type>string</type></entry>
2978
+
<entry>A fully qualified namespace (e.g. <literal>"databaseName.collectionName"</literal>) denoting the collection that contains all data keys used for encryption and decryption. This option is required.</entry>
2979
+
</row>
2980
+
'>
2981
+
<!ENTITY mongodb.option.encryption.kmsProviders '
2982
+
<row xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
2983
+
<entry>kmsProviders</entry>
2984
+
<entry><type>array</type></entry>
2985
+
<entry>
2986
+
<para>
2987
+
A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Supported providers include <literal>"aws"</literal>, <literal>"azure"</literal>, <literal>"gcp"</literal>, <literal>"kmip"</literal>, and <literal>"local"</literal> and at least one must be specified.
2988
+
</para>
2989
+
<para>
2990
+
If an empty document is specified for <literal>"aws"</literal>,
2991
+
<literal>"azure"</literal>, or <literal>"gcp"</literal>, the driver
2992
+
will attempt to configure the provider using
2993
+
<link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#automatic-credentials">Automatic Credentials</link>.
2994
+
</para>
2995
+
<para>
2996
+
The format for <literal>"aws"</literal> is as follows:
2997
+
</para>
2998
+
<programlisting role="javascript">
2999
+
<![CDATA[
3000
+
aws: {
3001
+
accessKeyId: <string>,
3002
+
secretAccessKey: <string>,
3003
+
sessionToken: <optional string>
3004
+
}
3005
+
]]>
3006
+
</programlisting>
3007
+
<para>
3008
+
The format for <literal>"azure"</literal> is as follows:
3009
+
</para>
3010
+
<programlisting role="javascript">
3011
+
<![CDATA[
3012
+
azure: {
3013
+
tenantId: <string>,
3014
+
clientId: <string>,
3015
+
clientSecret: <string>,
3016
+
identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
3017
+
}
3018
+
]]>
3019
+
</programlisting>
3020
+
<para>
3021
+
The format for <literal>"gcp"</literal> is as follows:
3022
+
</para>
3023
+
<programlisting role="javascript">
3024
+
<![CDATA[
3025
+
gcp: {
3026
+
email: <string>,
3027
+
privateKey: <base64 string>|<MongoDB\BSON\Binary>,
3028
+
endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
3029
+
}
3030
+
]]>
3031
+
</programlisting>
3032
+
<para>
3033
+
The format for <literal>"kmip"</literal> is as follows:
3034
+
</para>
3035
+
<programlisting role="javascript">
3036
+
<![CDATA[
3037
+
kmip: {
3038
+
endpoint: <string>
3039
+
}
3040
+
]]>
3041
+
</programlisting>
3042
+
<para>
3043
+
The format for <literal>"local"</literal> is as follows:
3044
+
</para>
3045
+
<programlisting role="javascript">
3046
+
<![CDATA[
3047
+
local: {
3048
+
// 96-byte master key used to encrypt/decrypt data keys
3049
+
key: <base64 string>|<MongoDB\BSON\Binary>
3050
+
}
3051
+
]]>
3052
+
</programlisting>
3053
+
</entry>
3054
+
</row>
3055
+
'>
3056
+
<!ENTITY mongodb.option.encryption.masterKey-options-by-provider '
3057
+
<para xmlns="http://docbook.org/ns/docbook">
3058
+
<table>
3059
+
<title><literal>"aws"</literal> provider options</title>
3060
+
<tgroup cols="3">
3061
+
<thead>
3062
+
<row>
3063
+
<entry>Option</entry>
3064
+
<entry>Type</entry>
3065
+
<entry>Description</entry>
3066
+
</row>
3067
+
</thead>
3068
+
<tbody>
3069
+
<row>
3070
+
<entry>region</entry>
3071
+
<entry>string</entry>
3072
+
<entry>Required.</entry>
3073
+
</row>
3074
+
<row>
3075
+
<entry>key</entry>
3076
+
<entry>string</entry>
3077
+
<entry>Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).</entry>
3078
+
</row>
3079
+
<row>
3080
+
<entry>endpoint</entry>
3081
+
<entry>string</entry>
3082
+
<entry>Optional. An alternate host identifier to send KMS requests to. May include port number.</entry>
3083
+
</row>
3084
+
</tbody>
3085
+
</tgroup>
3086
+
</table>
3087
+
</para>
3088
+
<para xmlns="http://docbook.org/ns/docbook">
3089
+
<table>
3090
+
<title><literal>"azure"</literal> provider options</title>
3091
+
<tgroup cols="3">
3092
+
<thead>
3093
+
<row>
3094
+
<entry>Option</entry>
3095
+
<entry>Type</entry>
3096
+
<entry>Description</entry>
3097
+
</row>
3098
+
</thead>
3099
+
<tbody>
3100
+
<row>
3101
+
<entry>keyVaultEndpoint</entry>
3102
+
<entry>string</entry>
3103
+
<entry>Required. Host with optional port (e.g. "example.vault.azure.net").</entry>
3104
+
</row>
3105
+
<row>
3106
+
<entry>keyName</entry>
3107
+
<entry>string</entry>
3108
+
<entry>Required.</entry>
3109
+
</row>
3110
+
<row>
3111
+
<entry>keyVersion</entry>
3112
+
<entry>string</entry>
3113
+
<entry>Optional. A specific version of the named key. Defaults to using the key's primary version.</entry>
3114
+
</row>
3115
+
</tbody>
3116
+
</tgroup>
3117
+
</table>
3118
+
</para>
3119
+
<para xmlns="http://docbook.org/ns/docbook">
3120
+
<table>
3121
+
<title><literal>"gcp"</literal> provider options</title>
3122
+
<tgroup cols="3">
3123
+
<thead>
3124
+
<row>
3125
+
<entry>Option</entry>
3126
+
<entry>Type</entry>
3127
+
<entry>Description</entry>
3128
+
</row>
3129
+
</thead>
3130
+
<tbody>
3131
+
<row>
3132
+
<entry>projectId</entry>
3133
+
<entry>string</entry>
3134
+
<entry>Required.</entry>
3135
+
</row>
3136
+
<row>
3137
+
<entry>location</entry>
3138
+
<entry>string</entry>
3139
+
<entry>Required.</entry>
3140
+
</row>
3141
+
<row>
3142
+
<entry>keyRing</entry>
3143
+
<entry>string</entry>
3144
+
<entry>Required.</entry>
3145
+
</row>
3146
+
<row>
3147
+
<entry>keyName</entry>
3148
+
<entry>string</entry>
3149
+
<entry>Required.</entry>
3150
+
</row>
3151
+
<row>
3152
+
<entry>keyVersion</entry>
3153
+
<entry>string</entry>
3154
+
<entry>Optional. A specific version of the named key. Defaults to using the key's primary version.</entry>
3155
+
</row>
3156
+
<row>
3157
+
<entry>endpoint</entry>
3158
+
<entry>string</entry>
3159
+
<entry>Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".</entry>
3160
+
</row>
3161
+
</tbody>
3162
+
</tgroup>
3163
+
</table>
3164
+
</para>
3165
+
<para xmlns="http://docbook.org/ns/docbook">
3166
+
<table>
3167
+
<title><literal>"kmip"</literal> provider options</title>
3168
+
<tgroup cols="3">
3169
+
<thead>
3170
+
<row>
3171
+
<entry>Option</entry>
3172
+
<entry>Type</entry>
3173
+
<entry>Description</entry>
3174
+
</row>
3175
+
</thead>
3176
+
<tbody>
3177
+
<row>
3178
+
<entry>keyId</entry>
3179
+
<entry>string</entry>
3180
+
<entry>Optional. Unique identifier to a 96-byte KMIP secret data managed object. If unspecified, the driver creates a random 96-byte KMIP secret data managed object.</entry>
3181
+
</row>
3182
+
<row>
3183
+
<entry>endpoint</entry>
3184
+
<entry>string</entry>
3185
+
<entry>Optional. Host with optional port.</entry>
3186
+
</row>
3187
+
</tbody>
3188
+
</tgroup>
3189
+
</table>
3190
+
</para>
3191
+
'>
3192
+
<!ENTITY mongodb.option.encryption.tlsOptions '
3193
+
<row xmlns="http://docbook.org/ns/docbook">
3194
+
<entry>tlsOptions</entry>
3195
+
<entry><type>array</type></entry>
3196
+
<entry>
3197
+
<para>
3198
+
A document containing the TLS configuration for one or more KMS providers. Supported providers include <literal>"aws"</literal>, <literal>"azure"</literal>, <literal>"gcp"</literal>, and <literal>"kmip"</literal>. All providers support the following options:
3199
+
</para>
3200
+
<programlisting role="javascript">
3201
+
<![CDATA[
3202
+
<provider>: {
3203
+
tlsCaFile: <optional string>,
3204
+
tlsCertificateKeyFile: <optional string>,
3205
+
tlsCertificateKeyFilePassword: <optional string>,
3206
+
tlsDisableOCSPEndpointCheck: <optional bool>
3207
+
}
3208
+
]]>
3209
+
</programlisting>
3210
+
</entry>
3211
+
</row>
3212
+
'>
3213
+
<!ENTITY mongodb.option.maxCommitTimeMS '
3214
+
<row xmlns="http://docbook.org/ns/docbook">
3215
+
<entry>maxCommitTimeMS</entry>
3216
+
<entry>integer</entry>
3217
+
<entry>
3218
+
<para>
3219
+
The maximum amount of time in milliseconds to allow a single
3220
+
<literal>commitTransaction</literal> command to run.
3221
+
</para>
3222
+
<para>
3223
+
If specified, <literal>maxCommitTimeMS</literal> must be a signed
3224
+
32-bit integer greater than or equal to zero.
3225
+
</para>
3226
+
</entry>
3227
+
</row>
3228
+
'>
3229
+
<!ENTITY mongodb.option.readConcern '
3230
+
<row xmlns="http://docbook.org/ns/docbook">
3231
+
<entry>readConcern</entry>
3232
+
<entry><classname>MongoDB\Driver\ReadConcern</classname></entry>
3233
+
<entry>
3234
+
<para>
3235
+
A read concern to apply to the operation.
3236
+
</para>
3237
+
<para>
3238
+
This option is available in MongoDB 3.2+ and will result in an
3239
+
exception at execution time if specified for an older server
3240
+
version.
3241
+
</para>
3242
+
</entry>
3243
+
</row>
3244
+
'>
3245
+
<!ENTITY mongodb.option.readPreference '
3246
+
<row xmlns="http://docbook.org/ns/docbook">
3247
+
<entry>readPreference</entry>
3248
+
<entry><classname>MongoDB\Driver\ReadPreference</classname></entry>
3249
+
<entry>
3250
+
<para>
3251
+
A read preference to use for selecting a server for the operation.
3252
+
</para>
3253
+
</entry>
3254
+
</row>
3255
+
'>
3256
+
<!ENTITY mongodb.option.session '
3257
+
<row xmlns="http://docbook.org/ns/docbook">
3258
+
<entry>session</entry>
3259
+
<entry><classname>MongoDB\Driver\Session</classname></entry>
3260
+
<entry>
3261
+
<para>
3262
+
A session to associate with the operation.
3263
+
</para>
3264
+
</entry>
3265
+
</row>
3266
+
'>
3267
+
<!ENTITY mongodb.option.transactionReadWriteConcern '
3268
+
<warning xmlns="http://docbook.org/ns/docbook">
3269
+
<para>
3270
+
If you are using a <literal>"session"</literal> which has a transaction
3271
+
in progress, you cannot specify a <literal>"readConcern"</literal> or
3272
+
<literal>"writeConcern"</literal> option. This will result in an
3273
+
<classname>MongoDB\Driver\Exception\InvalidArgumentException</classname>
3274
+
being thrown. Instead, you should set these two options when you create
3275
+
the transaction with
3276
+
<methodname>MongoDB\Driver\Session::startTransaction</methodname>.
3277
+
</para>
3278
+
</warning>
3279
+
'>
3280
+
<!ENTITY mongodb.option.writeConcern '
3281
+
<row xmlns="http://docbook.org/ns/docbook">
3282
+
<entry>writeConcern</entry>
3283
+
<entry><classname>MongoDB\Driver\WriteConcern</classname></entry>
3284
+
<entry>
3285
+
<para>
3286
+
A write concern to apply to the operation.
3287
+
</para>
3288
+
</entry>
3289
+
</row>
3290
+
'>
3291
+
<!ENTITY mongodb.parameter.namespace '
3292
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3293
+
<term><parameter>namespace</parameter> (<type>string</type>)</term>
3294
+
<listitem>
3295
+
<para>
3296
+
A fully qualified namespace (e.g. <literal>"databaseName.collectionName"</literal>).
3297
+
</para>
3298
+
</listitem>
3299
+
</varlistentry>
3300
+
'>
3301
+
<!ENTITY mongodb.parameter.db '
3302
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3303
+
<term><parameter>db</parameter> (<type>string</type>)</term>
3304
+
<listitem>
3305
+
<para>
3306
+
The name of the database on which to execute the command.
3307
+
</para>
3308
+
</listitem>
3309
+
</varlistentry>
3310
+
'>
3311
+
<!ENTITY mongodb.parameter.bulkwrite '
3312
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3313
+
<term><parameter>bulk</parameter> (<classname>MongoDB\Driver\BulkWrite</classname>)</term>
3314
+
<listitem>
3315
+
<para>
3316
+
The write(s) to execute.
3317
+
</para>
3318
+
</listitem>
3319
+
</varlistentry>
3320
+
'>
3321
+
<!ENTITY mongodb.parameter.command '
3322
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3323
+
<term><parameter>command</parameter> (<classname>MongoDB\Driver\Command</classname>)</term>
3324
+
<listitem>
3325
+
<para>
3326
+
The command to execute.
3327
+
</para>
3328
+
</listitem>
3329
+
</varlistentry>
3330
+
'>
3331
+
<!ENTITY mongodb.parameter.encryptOpts '
3332
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3333
+
<term><parameter>options</parameter></term>
3334
+
<listitem>
3335
+
<para>
3336
+
<table>
3337
+
<title>Encryption options</title>
3338
+
<tgroup cols="3">
3339
+
<thead>
3340
+
<row>
3341
+
<entry>Option</entry>
3342
+
<entry>Type</entry>
3343
+
<entry>Description</entry>
3344
+
</row>
3345
+
</thead>
3346
+
<tbody>
3347
+
<row>
3348
+
<entry>algorithm</entry>
3349
+
<entry><type>string</type></entry>
3350
+
<entry>
3351
+
<para>
3352
+
The encryption algorithm to be used. This option is required.
3353
+
Specify one of the following
3354
+
<link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
3355
+
</para>
3356
+
<simplelist>
3357
+
<member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC</constant></member>
3358
+
<member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM</constant></member>
3359
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant></member>
3360
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED</constant></member>
3361
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW</constant></member>
3362
+
</simplelist>
3363
+
</entry>
3364
+
</row>
3365
+
<row>
3366
+
<entry>contentionFactor</entry>
3367
+
<entry><type>int</type></entry>
3368
+
<entry>
3369
+
<para>
3370
+
The contention factor for evaluating queries with indexed, encrypted
3371
+
payloads.
3372
+
</para>
3373
+
<para>
3374
+
This option only applies and may only be specified when
3375
+
<literal>algorithm</literal> is
3376
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
3377
+
or
3378
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW</constant>.
3379
+
</para>
3380
+
</entry>
3381
+
</row>
3382
+
<row>
3383
+
<entry>keyAltName</entry>
3384
+
<entry><type>string</type></entry>
3385
+
<entry>
3386
+
<para>
3387
+
Identifies a key vault collection document by
3388
+
<literal>keyAltName</literal>. This option is mutually exclusive
3389
+
with <literal>keyId</literal> and exactly one is required.
3390
+
</para>
3391
+
</entry>
3392
+
</row>
3393
+
<row>
3394
+
<entry>keyId</entry>
3395
+
<entry><classname>MongoDB\BSON\Binary</classname></entry>
3396
+
<entry>
3397
+
<para>
3398
+
Identifies a data key by <literal>_id</literal>. The value is a UUID
3399
+
(binary subtype 4). This option is mutually exclusive with
3400
+
<literal>keyAltName</literal> and exactly one is required.
3401
+
</para>
3402
+
</entry>
3403
+
</row>
3404
+
<row>
3405
+
<entry>queryType</entry>
3406
+
<entry><type>string</type></entry>
3407
+
<entry>
3408
+
<para>
3409
+
The query type for evaluating queries with indexed, encrypted
3410
+
payloads. Specify one of the following
3411
+
<link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
3412
+
</para>
3413
+
<simplelist>
3414
+
<member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY</constant></member>
3415
+
<member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW</constant></member>
3416
+
</simplelist>
3417
+
<para>This option only applies and may only be specified when
3418
+
<literal>algorithm</literal> is
3419
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
3420
+
or <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW</constant>.
3421
+
</para>
3422
+
</entry>
3423
+
</row>
3424
+
<row>
3425
+
<entry>rangeOpts</entry>
3426
+
<entry><type>array</type></entry>
3427
+
<entry>
3428
+
<para>
3429
+
Index options for a queryable encryption field supporting
3430
+
"rangePreview" queries. The options below must match the values set
3431
+
in the <literal>encryptedFields</literal> of the target collection.
3432
+
For double and decimal128 BSON field types, <literal>min</literal>,
3433
+
<literal>max</literal>, and <literal>precision</literal> must all be
3434
+
set, or all be unset.
3435
+
</para>
3436
+
<para>
3437
+
<table>
3438
+
<title>Range index options</title>
3439
+
<tgroup cols="3">
3440
+
<thead>
3441
+
<row>
3442
+
<entry>Option</entry>
3443
+
<entry>Type</entry>
3444
+
<entry>Description</entry>
3445
+
</row>
3446
+
</thead>
3447
+
<tbody>
3448
+
<row>
3449
+
<entry>min</entry>
3450
+
<entry><type>mixed</type></entry>
3451
+
<entry>Required if <literal>precision</literal> is set.</entry>
3452
+
</row>
3453
+
<row>
3454
+
<entry>max</entry>
3455
+
<entry><type>mixed</type></entry>
3456
+
<entry>Required if <literal>precision</literal> is set.</entry>
3457
+
</row>
3458
+
<row>
3459
+
<entry>sparsity</entry>
3460
+
<entry><type>int</type></entry>
3461
+
<entry>Required.</entry>
3462
+
</row>
3463
+
<row>
3464
+
<entry>precision</entry>
3465
+
<entry><type>int</type></entry>
3466
+
<entry>Optional. May only be set for double or decimal128 BSON field types.</entry>
3467
+
</row>
3468
+
</tbody>
3469
+
</tgroup>
3470
+
</table>
3471
+
</para>
3472
+
</entry>
3473
+
</row>
3474
+
</tbody>
3475
+
</tgroup>
3476
+
</table>
3477
+
</para>
3478
+
</listitem>
3479
+
</varlistentry>
3480
+
'>
3481
+
<!ENTITY mongodb.parameter.query '
3482
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3483
+
<term><parameter>query</parameter> (<classname>MongoDB\Driver\Query</classname>)</term>
3484
+
<listitem>
3485
+
<para>
3486
+
The query to execute.
3487
+
</para>
3488
+
</listitem>
3489
+
</varlistentry>
3490
+
'>
3491
+
<!ENTITY mongodb.parameter.typeMap '
3492
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3493
+
<term><parameter>typeMap</parameter> (<type>array</type>)</term>
3494
+
<listitem>
3495
+
<para>
3496
+
<link linkend="mongodb.persistence.typemaps">Type map configuration</link>.
3497
+
</para>
3498
+
</listitem>
3499
+
</varlistentry>
3500
+
'>
3501
+
<!ENTITY mongodb.parameter.filter '
3502
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3503
+
<term><parameter>filter</parameter> (<type class="union"><type>array</type><type>object</type></type>)</term>
3504
+
<listitem>
3505
+
<para>
3506
+
The <link xlink:href="&url.mongodb.docs;tutorial/query-documents/" xmlns:xlink="http://www.w3.org/1999/xlink">query predicate</link>.
3507
+
An empty predicate will match all documents in the collection.
3508
+
</para>
3509
+
<note>
3510
+
<simpara>
3511
+
When evaluating query criteria, MongoDB compares types and values according to its own <link xlink:href="&url.mongodb.docs;reference/bson-type-comparison-order/" xmlns:xlink="http://www.w3.org/1999/xlink">comparison rules for BSON types</link>, which differs from PHP's <link linkend="types.comparisons">comparison</link> and <link linkend="language.types.type-juggling">type juggling</link> rules. When matching a special BSON type the query criteria should use the respective <link linkend="book.bson">BSON class</link> (e.g. use <classname>MongoDB\BSON\ObjectId</classname> to match an <link xlink:href="&url.mongodb.docs.objectid;" xmlns:xlink="http://www.w3.org/1999/xlink">ObjectId</link>).
3512
+
</simpara>
3513
+
</note>
3514
+
</listitem>
3515
+
</varlistentry>
3516
+
'>
3517
+
<!ENTITY mongodb.returns.cursor '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\Cursor</classname> on success.</para>'>
3518
+
<!ENTITY mongodb.returns.writeresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\WriteResult</classname> on success.</para>'>
3519
+
<!ENTITY mongodb.throws.std '&mongodb.throws.argumentparsing;&mongodb.throws.connection;&mongodb.throws.authentication;'>
3520
+
<!ENTITY mongodb.throws.session-readwriteconcern '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if the <literal>"session"</literal> option is used with an associated transaction in combination with a <literal>"readConcern"</literal> or <literal>"writeConcern"</literal> option.</member>'>
3521
+
<!ENTITY mongodb.throws.session-unacknowledged '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if the <literal>"session"</literal> option is used in combination with an unacknowledged write concern.</member>'>
3522
+
<!ENTITY mongodb.throws.bulkwriteexception '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\BulkWriteException</classname> on any write failure (e.g. write error, failure to apply a write concern)</member>'>
3523
+
<!ENTITY mongodb.throws.argumentparsing '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> on argument parsing errors.</member>'>
3524
+
<!ENTITY mongodb.throws.authentication '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\AuthenticationException</classname> if authentication is needed and fails.</member>'>
3525
+
<!ENTITY mongodb.throws.connection '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\ConnectionException</classname> if connection to the server fails (for reasons other than authentication).</member>'>
3526
+
<!ENTITY mongodb.throws.bson.unexpected '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname> if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected <link xlink:href="&url.mongodb.libbson;" xmlns:xlink="http://www.w3.org/1999/xlink">libbson</link> error.</member>'>
3527
+
3528
+
<!-- Not used in EN anymore -->
3529
+
<!ENTITY mongodb.note.queryable-encryption-preview ''>
3530
+
3531
+
<!ENTITY mongodb.note.decimal128 '
3532
+
<note xmlns="http://docbook.org/ns/docbook">
3533
+
<simpara>
3534
+
<classname>MongoDB\BSON\Decimal128</classname> is only compatible with
3535
+
MongoDB 3.4+. Attempting to use the BSON type with an earlier version of
3536
+
MongoDB will result in an error.
3537
+
</simpara>
3538
+
</note>
3539
+
'>
3540
+
<!ENTITY mongodb.note.extended-json '
3541
+
<note xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3542
+
<simpara>
3543
+
The output is consistent with the <function>MongoDB\BSON\toJSON</function>
3544
+
function, which uses the driver-specific legacy extended JSON format. This
3545
+
does not necessarily match the
3546
+
<link xlink:href="&url.mongodb.specs.extendedjson;#relaxed-extended-json-example">relaxed</link>
3547
+
or <link xlink:href="&url.mongodb.specs.extendedjson;#canonical-extended-json-example">canonical</link>
3548
+
extended JSON representations used by
3549
+
<function>MongoDB\BSON\toRelaxedExtendedJSON</function> and
3550
+
<function>MongoDB\BSON\toCanonicalExtendedJSON</function>, respectively.
3551
+
</simpara>
3552
+
</note>
3553
+
'>
3554
+
<!ENTITY mongodb.note.forking '
3555
+
<note xmlns="http://docbook.org/ns/docbook">
3556
+
<simpara>
3557
+
On Unix platforms, the MongoDB driver is sensitive to scripts that use the
3558
+
fork() system call without also calling exec(). Users are advised not to
3559
+
re-use <classname>MongoDB\Driver\Manager</classname> instances in a forked
3560
+
child process.
3561
+
</simpara>
3562
+
</note>
3563
+
'>
3564
+
3565
+
<!ENTITY mongodb.note.uint32 '
3566
+
<note xmlns="http://docbook.org/ns/docbook">
3567
+
<simpara>
3568
+
Because PHP's integer type is signed, some values returned by this
3569
+
method may appear as negative integers on 32-bit platforms. The
3570
+
<literal>"%u"</literal> formatter of <function>sprintf</function> may be
3571
+
used to obtain a string representation of the unsigned decimal value.
3572
+
</simpara>
3573
+
</note>
3574
+
'>
3575
+
3576
+
<!ENTITY mongodb.note.server.readpreference '
3577
+
<note xmlns="http://docbook.org/ns/docbook">
3578
+
<simpara>
3579
+
The <literal>"readPreference"</literal> option does not control the server
3580
+
to which the driver issues the operation; it will always be executed on
3581
+
this server object. Instead, it may be used when issuing the operation to a
3582
+
secondary (from a replica set connection, not standalone) or mongos node to
3583
+
ensure that the driver sets the wire protocol accordingly or adds the read
3584
+
preference to the operation, respectively.
3585
+
</simpara>
3586
+
</note>
3587
+
'>
3588
+
3589
+
<!ENTITY mongodb.note.server.write '
3590
+
<note xmlns="http://docbook.org/ns/docbook">
3591
+
<simpara>
3592
+
It is the caller's responsibility to ensure that the server is capable
3593
+
of executing the write operation. For example, executing a write operation
3594
+
on a secondary (excluding its "local" database) will fail.
3595
+
</simpara>
3596
+
</note>
3597
+
'>
3598
+
3599
+
<!ENTITY mongodb.warning.duplicate-keys '
3600
+
<warning xmlns="http://docbook.org/ns/docbook">
3601
+
<simpara>
3602
+
BSON documents can technically contain duplicate keys because documents are
3603
+
stored as a list of key-value pairs; however, applications should refrain
3604
+
from generating documents with duplicate keys as server and driver behavior
3605
+
may be undefined. Since PHP objects and arrays cannot have duplicate keys,
3606
+
data could also be lost when decoding a BSON document with duplicate keys.
3607
+
</simpara>
3608
+
</warning>
3609
+
'>
3610
+
3611
+
<!-- Radius -->
3612
+
<!ENTITY radius.request.required '<note xmlns="http://docbook.org/ns/docbook"><para>A request must be created via <function>radius_create_request</function> before this function can be called.</para></note>'>
3613
+
<!ENTITY radius.parameter.attribute-type '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>type</parameter></term><listitem><para>The attribute type.</para></listitem></varlistentry>'>
3614
+
<!ENTITY radius.parameter.handle '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>radius_handle</parameter></term><listitem><para>The RADIUS resource.</para></listitem></varlistentry>'>
3615
+
<!ENTITY radius.parameter.options '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>options</parameter></term><listitem><para>A bitmask of the attribute options. The available options include <link linkend="constant.radius-option-tagged"><constant>RADIUS_OPTION_TAGGED</constant></link> and <link linkend="constant.radius-option-salt"><constant>RADIUS_OPTION_SALT</constant></link>.</para></listitem></varlistentry>'>
3616
+
<!ENTITY radius.parameter.tag '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>tag</parameter></term><listitem><para>The attribute tag. This parameter is ignored unless the <link linkend="constant.radius-option-tagged"><constant>RADIUS_OPTION_TAGGED</constant></link> option is set.</para></listitem></varlistentry>'>
3617
+
<!ENTITY radius.parameter.vendor '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>vendor</parameter></term><listitem><para>The vendor ID.</para></listitem></varlistentry>'>
3618
+
3619
+
<!-- posix snippets -->
3620
+
<!ENTITY posix.parameter.fd '<varlistentry xmlns="http://docbook.org/ns/docbook">
3621
+
<term><parameter>file_descriptor</parameter></term>
3622
+
<listitem>
3623
+
<para>
3624
+
The file descriptor, which is expected to be either a file
3625
+
<type>resource</type> or an <type>int</type>. An <type>int</type>
3626
+
will be assumed to be a file descriptor that can be passed directly to
3627
+
the underlying system call.
3628
+
</para>
3629
+
</listitem>
3630
+
</varlistentry>'>
3631
+
3632
+
<!ENTITY posix.rlimits '
3633
+
<para xmlns="http://docbook.org/ns/docbook">
3634
+
Each resource has an associated soft and hard limit. The soft
3635
+
limit is the value that the kernel enforces for the corresponding
3636
+
resource. The hard limit acts as a ceiling for the soft limit.
3637
+
An unprivileged process may only set its soft limit to a value
3638
+
from 0 to the hard limit, and irreversibly lower its hard limit.
3639
+
</para>
3640
+
'>
3641
+
3642
+
<!-- strings snippets -->
3643
+
<!ENTITY strings.parameter.encoding '
3644
+
<para xmlns="http://docbook.org/ns/docbook">
3645
+
An optional argument defining the encoding used when converting characters.
3646
+
</para>
3647
+
3648
+
<para xmlns="http://docbook.org/ns/docbook">
3649
+
If omitted, <parameter>encoding</parameter> defaults to the value of the
3650
+
<link linkend="ini.default-charset">default_charset</link> configuration
3651
+
option.
3652
+
</para>
3653
+
3654
+
<para xmlns="http://docbook.org/ns/docbook">
3655
+
Although this argument is technically optional, you are highly encouraged to
3656
+
specify the correct value for your code
3657
+
if the <link linkend="ini.default-charset">default_charset</link>
3658
+
configuration option may be set incorrectly for the given input.
3659
+
</para>
3660
+
'>
3661
+
3662
+
<!ENTITY strings.parameter.format '
3663
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3664
+
<term><parameter>format</parameter></term>
3665
+
<listitem>
3666
+
<para>
3667
+
The format string is composed of zero or more directives:
3668
+
ordinary characters (excluding <literal>%</literal>) that are
3669
+
copied directly to the result and <emphasis>conversion
3670
+
specifications</emphasis>, each of which results in fetching its
3671
+
own parameter.
3672
+
</para>
3673
+
3674
+
<para>
3675
+
A conversion specification follows this prototype:
3676
+
<literal>%[argnum$][flags][width][.precision]specifier</literal>.
3677
+
</para>
3678
+
3679
+
<formalpara>
3680
+
<title>Argnum</title>
3681
+
<para>
3682
+
An integer followed by a dollar sign <literal>$</literal>,
3683
+
to specify which number argument to treat in the conversion.
3684
+
</para>
3685
+
</formalpara>
3686
+
3687
+
<para>
3688
+
<table>
3689
+
<title>Flags</title>
3690
+
<tgroup cols="2">
3691
+
<thead>
3692
+
<row>
3693
+
<entry>Flag</entry>
3694
+
<entry>&Description;</entry>
3695
+
</row>
3696
+
</thead>
3697
+
<tbody>
3698
+
<row>
3699
+
<entry><literal>-</literal></entry>
3700
+
<entry>
3701
+
Left-justify within the given field width;
3702
+
Right justification is the default
3703
+
</entry>
3704
+
</row>
3705
+
<row>
3706
+
<entry><literal>+</literal></entry>
3707
+
<entry>
3708
+
Prefix positive numbers with a plus sign
3709
+
<literal>+</literal>; Default only negative
3710
+
are prefixed with a negative sign.
3711
+
</entry>
3712
+
</row>
3713
+
<row>
3714
+
<entry><literal> </literal>(space)</entry>
3715
+
<entry>
3716
+
Pads the result with spaces.
3717
+
This is the default.
3718
+
</entry>
3719
+
</row>
3720
+
<row>
3721
+
<entry><literal>0</literal></entry>
3722
+
<entry>
3723
+
Only left-pads numbers with zeros.
3724
+
With <literal>s</literal> specifiers this can
3725
+
also right-pad with zeros.
3726
+
</entry>
3727
+
</row>
3728
+
<row>
3729
+
<entry><literal>'</literal>(char)</entry>
3730
+
<entry>
3731
+
Pads the result with the character (char).
3732
+
</entry>
3733
+
</row>
3734
+
</tbody>
3735
+
</tgroup>
3736
+
</table>
3737
+
</para>
3738
+
3739
+
<formalpara>
3740
+
<title>Width</title>
3741
+
<para>
3742
+
Either an integer that says how many characters (minimum)
3743
+
this conversion should result in, or <literal>*</literal>.
3744
+
If <literal>*</literal> is used, then the width is supplied
3745
+
as an additional integer value preceding the one formatted
3746
+
by the specifier.
3747
+
</para>
3748
+
</formalpara>
3749
+
3750
+
<formalpara>
3751
+
<title>Precision</title>
3752
+
<para>
3753
+
A period <literal>.</literal> optionally followed by
3754
+
either an integer or <literal>*</literal>,
3755
+
whose meaning depends on the specifier:
3756
+
<itemizedlist>
3757
+
<listitem>
3758
+
<simpara>
3759
+
For <literal>e</literal>, <literal>E</literal>,
3760
+
<literal>f</literal> and <literal>F</literal>
3761
+
specifiers: this is the number of digits to be printed
3762
+
after the decimal point (by default, this is 6).
3763
+
</simpara>
3764
+
</listitem>
3765
+
<listitem>
3766
+
<simpara>
3767
+
For <literal>g</literal>, <literal>G</literal>,
3768
+
<literal>h</literal> and <literal>H</literal>
3769
+
specifiers: this is the maximum number of significant
3770
+
digits to be printed.
3771
+
</simpara>
3772
+
</listitem>
3773
+
<listitem>
3774
+
<simpara>
3775
+
For <literal>s</literal> specifier: it acts as a cutoff point,
3776
+
setting a maximum character limit to the string.
3777
+
</simpara>
3778
+
</listitem>
3779
+
</itemizedlist>
3780
+
<note>
3781
+
<simpara>
3782
+
If the period is specified without an explicit value for precision,
3783
+
0 is assumed. If <literal>*</literal> is used, the precision is
3784
+
supplied as an additional integer value preceding the one formatted
3785
+
by the specifier.
3786
+
</simpara>
3787
+
</note>
3788
+
</para>
3789
+
</formalpara>
3790
+
3791
+
<para>
3792
+
<table>
3793
+
<title>Specifiers</title>
3794
+
<tgroup cols="2">
3795
+
<thead>
3796
+
<row>
3797
+
<entry>Specifier</entry>
3798
+
<entry>&Description;</entry>
3799
+
</row>
3800
+
</thead>
3801
+
<tbody>
3802
+
<row>
3803
+
<entry><literal>%</literal></entry>
3804
+
<entry>
3805
+
A literal percent character. No argument is required.
3806
+
</entry>
3807
+
</row>
3808
+
<row>
3809
+
<entry><literal>b</literal></entry>
3810
+
<entry>
3811
+
The argument is treated as an integer and presented
3812
+
as a binary number.
3813
+
</entry>
3814
+
</row>
3815
+
<row>
3816
+
<entry><literal>c</literal></entry>
3817
+
<entry>
3818
+
The argument is treated as an integer and presented
3819
+
as the character with that ASCII.
3820
+
</entry>
3821
+
</row>
3822
+
<row>
3823
+
<entry><literal>d</literal></entry>
3824
+
<entry>
3825
+
The argument is treated as an integer and presented
3826
+
as a (signed) decimal number.
3827
+
</entry>
3828
+
</row>
3829
+
<row>
3830
+
<entry><literal>e</literal></entry>
3831
+
<entry>
3832
+
The argument is treated as scientific notation (e.g. 1.2e+2).
3833
+
</entry>
3834
+
</row>
3835
+
<row>
3836
+
<entry><literal>E</literal></entry>
3837
+
<entry>
3838
+
Like the <literal>e</literal> specifier but uses
3839
+
uppercase letter (e.g. 1.2E+2).
3840
+
</entry>
3841
+
</row>
3842
+
<row>
3843
+
<entry><literal>f</literal></entry>
3844
+
<entry>
3845
+
The argument is treated as a float and presented
3846
+
as a floating-point number (locale aware).
3847
+
</entry>
3848
+
</row>
3849
+
<row>
3850
+
<entry><literal>F</literal></entry>
3851
+
<entry>
3852
+
The argument is treated as a float and presented
3853
+
as a floating-point number (non-locale aware).
3854
+
</entry>
3855
+
</row>
3856
+
<row>
3857
+
<entry><literal>g</literal></entry>
3858
+
<entry>
3859
+
<para>
3860
+
General format.
3861
+
</para>
3862
+
<para>
3863
+
Let P equal the precision if nonzero, 6 if the precision is omitted,
3864
+
or 1 if the precision is zero.
3865
+
Then, if a conversion with style E would have an exponent of X:
3866
+
</para>
3867
+
<para>
3868
+
If P > X ≥ −4, the conversion is with style f and precision P − (X + 1).
3869
+
Otherwise, the conversion is with style e and precision P − 1.
3870
+
</para>
3871
+
</entry>
3872
+
</row>
3873
+
<row>
3874
+
<entry><literal>G</literal></entry>
3875
+
<entry>
3876
+
Like the <literal>g</literal> specifier but uses
3877
+
<literal>E</literal> and <literal>f</literal>.
3878
+
</entry>
3879
+
</row>
3880
+
<row>
3881
+
<entry><literal>h</literal></entry>
3882
+
<entry>
3883
+
Like the <literal>g</literal> specifier but uses <literal>F</literal>.
3884
+
Available as of PHP 8.0.0.
3885
+
</entry>
3886
+
</row>
3887
+
<row>
3888
+
<entry><literal>H</literal></entry>
3889
+
<entry>
3890
+
Like the <literal>g</literal> specifier but uses
3891
+
<literal>E</literal> and <literal>F</literal>. Available as of PHP 8.0.0.
3892
+
</entry>
3893
+
</row>
3894
+
<row>
3895
+
<entry><literal>o</literal></entry>
3896
+
<entry>
3897
+
The argument is treated as an integer and presented
3898
+
as an octal number.
3899
+
</entry>
3900
+
</row>
3901
+
<row>
3902
+
<entry><literal>s</literal></entry>
3903
+
<entry>
3904
+
The argument is treated and presented as a string.
3905
+
</entry>
3906
+
</row>
3907
+
<row>
3908
+
<entry><literal>u</literal></entry>
3909
+
<entry>
3910
+
The argument is treated as an integer and presented
3911
+
as an unsigned decimal number.
3912
+
</entry>
3913
+
</row>
3914
+
<row>
3915
+
<entry><literal>x</literal></entry>
3916
+
<entry>
3917
+
The argument is treated as an integer and presented
3918
+
as a hexadecimal number (with lowercase letters).
3919
+
</entry>
3920
+
</row>
3921
+
<row>
3922
+
<entry><literal>X</literal></entry>
3923
+
<entry>
3924
+
The argument is treated as an integer and presented
3925
+
as a hexadecimal number (with uppercase letters).
3926
+
</entry>
3927
+
</row>
3928
+
</tbody>
3929
+
</tgroup>
3930
+
</table>
3931
+
</para>
3932
+
3933
+
<warning>
3934
+
<para>
3935
+
The <literal>c</literal> type specifier ignores padding and width
3936
+
</para>
3937
+
</warning>
3938
+
3939
+
<warning>
3940
+
<para>
3941
+
Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results
3942
+
</para>
3943
+
</warning>
3944
+
3945
+
<para>
3946
+
Variables will be co-erced to a suitable type for the specifier:
3947
+
<table>
3948
+
<title>Type Handling</title>
3949
+
<tgroup cols="2">
3950
+
<thead>
3951
+
<row>
3952
+
<entry>Type</entry>
3953
+
<entry>Specifiers</entry>
3954
+
</row>
3955
+
</thead>
3956
+
<tbody>
3957
+
<row>
3958
+
<entry><type>string</type></entry>
3959
+
<entry><literal>s</literal></entry>
3960
+
</row>
3961
+
<row>
3962
+
<entry><type>int</type></entry>
3963
+
<entry>
3964
+
<literal>d</literal>,
3965
+
<literal>u</literal>,
3966
+
<literal>c</literal>,
3967
+
<literal>o</literal>,
3968
+
<literal>x</literal>,
3969
+
<literal>X</literal>,
3970
+
<literal>b</literal>
3971
+
</entry>
3972
+
</row>
3973
+
<row>
3974
+
<entry><type>float</type></entry>
3975
+
<entry>
3976
+
<literal>e</literal>,
3977
+
<literal>E</literal>,
3978
+
<literal>f</literal>,
3979
+
<literal>F</literal>,
3980
+
<literal>g</literal>,
3981
+
<literal>G</literal>,
3982
+
<literal>h</literal>,
3983
+
<literal>H</literal>
3984
+
</entry>
3985
+
</row>
3986
+
</tbody>
3987
+
</tgroup>
3988
+
</table>
3989
+
</para>
3990
+
</listitem>
3991
+
</varlistentry>
3992
+
'>
3993
+
3994
+
<!ENTITY strings.scanf.parameter.format '
3995
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3996
+
<term><parameter>format</parameter></term>
3997
+
<listitem>
3998
+
<para>
3999
+
The interpreted format for <parameter>string</parameter>, which is
4000
+
described in the documentation for <function>sprintf</function> with
4001
+
following differences:
4002
+
<simplelist>
4003
+
<member>
4004
+
Function is not locale-aware.
4005
+
</member>
4006
+
<member>
4007
+
<literal>F</literal>, <literal>g</literal>, <literal>G</literal> and
4008
+
<literal>b</literal> are not supported.
4009
+
</member>
4010
+
<member>
4011
+
<literal>D</literal> stands for decimal number.
4012
+
</member>
4013
+
<member>
4014
+
<literal>i</literal> stands for integer with base detection.
4015
+
</member>
4016
+
<member>
4017
+
<literal>n</literal> stands for number of characters processed so far.
4018
+
</member>
4019
+
<member>
4020
+
<literal>s</literal> stops reading at any whitespace character.
4021
+
</member>
4022
+
<member>
4023
+
<literal>*</literal> instead of <literal>argnum$</literal> suppresses
4024
+
the assignment of this conversion specification.
4025
+
</member>
4026
+
</simplelist>
4027
+
</para>
4028
+
</listitem>
4029
+
</varlistentry>
4030
+
'>
4031
+
4032
+
<!ENTITY strings.parameter.needle.non-string '
4033
+
<para xmlns="http://docbook.org/ns/docbook">
4034
+
Prior to PHP 8.0.0, if <parameter>needle</parameter> is not a string, it is converted
4035
+
to an integer and applied as the ordinal value of a character.
4036
+
This behavior is deprecated as of PHP 7.3.0, and relying on it is highly
4037
+
discouraged. Depending on the intended behavior, the
4038
+
<parameter>needle</parameter> should either be explicitly cast to string,
4039
+
or an explicit call to <function>chr</function> should be performed.
4040
+
</para>
4041
+
'>
4042
+
4043
+
<!ENTITY strings.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
4044
+
<entry>8.0.0</entry>
4045
+
<entry>
4046
+
<parameter>needle</parameter> now accepts an empty string.
4047
+
</entry>
4048
+
</row>'>
4049
+
4050
+
<!ENTITY strings.changelog.encoding '
4051
+
<row xmlns="http://docbook.org/ns/docbook">
4052
+
<entry>5.6.0</entry>
4053
+
<entry>
4054
+
The default value for the <parameter>encoding</parameter> parameter was
4055
+
changed to be the value of the
4056
+
<link linkend="ini.default-charset">default_charset</link> configuration
4057
+
option.
4058
+
</entry>
4059
+
</row>
4060
+
'>
4061
+
4062
+
<!ENTITY strings.changelog.ascii-case-conversion '
4063
+
<row xmlns="http://docbook.org/ns/docbook">
4064
+
<entry>8.2.0</entry>
4065
+
<entry>
4066
+
Case conversion no longer depends on the locale set with
4067
+
<function>setlocale</function>. Only ASCII characters will be converted.
4068
+
</entry>
4069
+
</row>
4070
+
'>
4071
+
4072
+
<!ENTITY strings.changelog.ascii-case-folding '
4073
+
<row xmlns="http://docbook.org/ns/docbook">
4074
+
<entry>8.2.0</entry>
4075
+
<entry>
4076
+
Case folding no longer depends on the locale set with
4077
+
<function>setlocale</function>. Only ASCII case folding will be done.
4078
+
Non-ASCII bytes will be compared by their byte value.
4079
+
</entry>
4080
+
</row>
4081
+
'>
4082
+
4083
+
<!ENTITY strings.changelog.sprintf '
4084
+
<informaltable xmlns="http://docbook.org/ns/docbook">
4085
+
<tgroup cols="2">
4086
+
<thead>
4087
+
<row>
4088
+
<entry>&Version;</entry>
4089
+
<entry>&Description;</entry>
4090
+
</row>
4091
+
</thead>
4092
+
<tbody>
4093
+
<row>
4094
+
<entry>8.0.0</entry>
4095
+
<entry>
4096
+
This function no longer returns &false; on failure.
4097
+
</entry>
4098
+
</row>
4099
+
<row>
4100
+
<entry>8.0.0</entry>
4101
+
<entry>
4102
+
Throw a <classname>ValueError</classname> if the number of arguments is zero;
4103
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4104
+
</entry>
4105
+
</row>
4106
+
<row>
4107
+
<entry>8.0.0</entry>
4108
+
<entry>
4109
+
Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4110
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4111
+
</entry>
4112
+
</row>
4113
+
<row>
4114
+
<entry>8.0.0</entry>
4115
+
<entry>
4116
+
Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4117
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4118
+
</entry>
4119
+
</row>
4120
+
<row>
4121
+
<entry>8.0.0</entry>
4122
+
<entry>
4123
+
Throw a <classname>ArgumentCountError</classname> when less arguments are given than required;
4124
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4125
+
</entry>
4126
+
</row>
4127
+
</tbody>
4128
+
</tgroup>
4129
+
</informaltable>
4130
+
'>
4131
+
4132
+
<!ENTITY strings.changelog.vsprintf '
4133
+
<informaltable xmlns="http://docbook.org/ns/docbook">
4134
+
<tgroup cols="2">
4135
+
<thead>
4136
+
<row>
4137
+
<entry>&Version;</entry>
4138
+
<entry>&Description;</entry>
4139
+
</row>
4140
+
</thead>
4141
+
<tbody>
4142
+
<row>
4143
+
<entry>8.0.0</entry>
4144
+
<entry>
4145
+
This function no longer returns &false; on failure.
4146
+
</entry>
4147
+
</row>
4148
+
<row>
4149
+
<entry>8.0.0</entry>
4150
+
<entry>
4151
+
Throw a <classname>ValueError</classname> if the number of arguments is zero;
4152
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4153
+
</entry>
4154
+
</row>
4155
+
<row>
4156
+
<entry>8.0.0</entry>
4157
+
<entry>
4158
+
Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4159
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4160
+
</entry>
4161
+
</row>
4162
+
<row>
4163
+
<entry>8.0.0</entry>
4164
+
<entry>
4165
+
Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4166
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4167
+
</entry>
4168
+
</row>
4169
+
<row>
4170
+
<entry>8.0.0</entry>
4171
+
<entry>
4172
+
Throw a <classname>ValueError</classname> when less arguments are given than required;
4173
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4174
+
</entry>
4175
+
</row>
4176
+
</tbody>
4177
+
</tgroup>
4178
+
</informaltable>
4179
+
'>
4180
+
4181
+
<!ENTITY strings.errors.sprintf '
4182
+
<para xmlns="http://docbook.org/ns/docbook">
4183
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
4184
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4185
+
</para>
4186
+
<para xmlns="http://docbook.org/ns/docbook">
4187
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4188
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4189
+
</para>
4190
+
<para xmlns="http://docbook.org/ns/docbook">
4191
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4192
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4193
+
</para>
4194
+
<para xmlns="http://docbook.org/ns/docbook">
4195
+
As of PHP 8.0.0, a <classname>ArgumentCountError</classname> is thrown when less arguments are given than required.
4196
+
Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
4197
+
</para>
4198
+
'>
4199
+
4200
+
<!ENTITY strings.errors.vsprintf '
4201
+
<para xmlns="http://docbook.org/ns/docbook">
4202
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
4203
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4204
+
</para>
4205
+
<para xmlns="http://docbook.org/ns/docbook">
4206
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4207
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4208
+
</para>
4209
+
<para xmlns="http://docbook.org/ns/docbook">
4210
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4211
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4212
+
</para>
4213
+
<para xmlns="http://docbook.org/ns/docbook">
4214
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown when less arguments are given than required.
4215
+
Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
4216
+
</para>
4217
+
'>
4218
+
4219
+
<!-- filter snippets -->
4220
+
<!ENTITY filter.param.filter '
4221
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
4222
+
<term><parameter>filter</parameter></term>
4223
+
<listitem>
4224
+
<para>
4225
+
The ID of the filter to apply. The <xref linkend="filter.filters" />
4226
+
manual page lists the available filters.
4227
+
</para>
4228
+
<para>
4229
+
If omitted, <constant>FILTER_DEFAULT</constant> will be used, which is
4230
+
equivalent to
4231
+
<link linkend="filter.filters.sanitize"><constant>FILTER_UNSAFE_RAW</constant></link>.
4232
+
This will result in no filtering taking place by default.
4233
+
</para>
4234
+
</listitem>
4235
+
</varlistentry>
4236
+
'>
4237
+
4238
+
<!-- csprng snippets -->
4239
+
<!ENTITY csprng.sources '
4240
+
<para xmlns="http://docbook.org/ns/docbook">
4241
+
The sources of randomness in the order of priority are as follows:
4242
+
</para>
4243
+
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4244
+
<listitem>
4245
+
<para>
4246
+
Linux: <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4247
+
</para>
4248
+
</listitem>
4249
+
<listitem>
4250
+
<para>
4251
+
FreeBSD >= 12 (PHP >= 7.3): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4252
+
</para>
4253
+
</listitem>
4254
+
<listitem>
4255
+
<para>
4256
+
Windows (PHP >= 7.2): <link xlink:href="&url.csprng.cng-api;">CNG-API</link>
4257
+
</para>
4258
+
<para>
4259
+
Windows: <link xlink:href="&url.csprng.crypt-gen-random;">CryptGenRandom</link>
4260
+
</para>
4261
+
</listitem>
4262
+
<listitem>
4263
+
<para>
4264
+
macOS (PHP >= 8.2; >= 8.1.9; >= 8.0.22 if CCRandomGenerateBytes is available at compile time): CCRandomGenerateBytes()
4265
+
</para>
4266
+
<para>
4267
+
macOS (PHP >= 8.1; >= 8.0.2): arc4random_buf(), <filename>/dev/urandom</filename>
4268
+
</para>
4269
+
</listitem>
4270
+
<listitem>
4271
+
<para>
4272
+
NetBSD >= 7 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
4273
+
</para>
4274
+
</listitem>
4275
+
<listitem>
4276
+
<para>
4277
+
OpenBSD >= 5.5 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
4278
+
</para>
4279
+
</listitem>
4280
+
<listitem>
4281
+
<para>
4282
+
DragonflyBSD (PHP >= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4283
+
</para>
4284
+
</listitem>
4285
+
<listitem>
4286
+
<para>
4287
+
Solaris (PHP >= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4288
+
</para>
4289
+
</listitem>
4290
+
<listitem>
4291
+
<simpara>
4292
+
Any combination of operating system and PHP version not previously mentioned: <filename>/dev/urandom</filename>
4293
+
</simpara>
4294
+
</listitem>
4295
+
<listitem>
4296
+
<simpara>
4297
+
If none of the sources are available or they all fail to generate
4298
+
randomness, then a <classname>Random\RandomException</classname>
4299
+
will be thrown.
4300
+
</simpara>
4301
+
</listitem>
4302
+
</itemizedlist>
4303
+
'>
4304
+
<!ENTITY csprng.errors '
4305
+
<listitem xmlns="http://docbook.org/ns/docbook">
4306
+
<simpara>
4307
+
If an appropriate source of randomness cannot be found,
4308
+
a <classname>Random\RandomException</classname> will be thrown.
4309
+
</simpara>
4310
+
</listitem>
4311
+
'>
4312
+
<!ENTITY csprng.function.backport '
4313
+
<note xmlns="http://docbook.org/ns/docbook">
4314
+
<simpara>
4315
+
Although this function was added to PHP in PHP 7.0, a
4316
+
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.csprng.compat;">userland implementation</link>
4317
+
is available for PHP 5.2 to 5.6, inclusive.
4318
+
</simpara>
4319
+
</note>
4320
+
'>
4321
+
4322
+
<!-- Random snippets -->
4323
+
<!ENTITY random.engineErrors '
4324
+
<listitem xmlns="http://docbook.org/ns/docbook">
4325
+
<simpara>
4326
+
Any <classname>Throwable</classname>s thrown by the <methodname>Random\Engine::generate</methodname> method
4327
+
of the underlying <link linkend="random-randomizer.props.engine"><literal>Random\Randomizer::$engine</literal></link>.
4328
+
</simpara>
4329
+
</listitem>
4330
+
'>
4331
+
4332
+
<!-- UOPZ snippets -->
4333
+
4334
+
<!ENTITY uopz.warn.removed.function-5-0-0 '<warning
4335
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
4336
+
<emphasis>REMOVED</emphasis> in PECL uopz 5.0.0.</simpara></warning>'>
4337
+
4338
+
<!-- XML snippets -->
4339
+
<!ENTITY xml.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
4340
+
<term><parameter>parser</parameter></term>
4341
+
<listitem>
4342
+
<para>
4343
+
The XML parser.
4344
+
</para>
4345
+
</listitem>
4346
+
</varlistentry>'>
4347
+
4348
+
<!ENTITY xml.handler.description '<para xmlns="http://docbook.org/ns/docbook">
4349
+
If &null; or an empty string is passed, the handler is reset to its default state.
4350
+
</para>
4351
+
<para xmlns="http://docbook.org/ns/docbook">
4352
+
If <parameter>handler</parameter> is a <type>callable</type>,
4353
+
the callable is set as the handler.
4354
+
</para>
4355
+
<para xmlns="http://docbook.org/ns/docbook">
4356
+
If <parameter>handler</parameter> is a <type>string</type>,
4357
+
it can be the name of a method of an object set with
4358
+
<function>xml_set_object</function>.
4359
+
</para>'>
4360
+
4361
+
<!ENTITY xml.handler.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
4362
+
<term><parameter>parser</parameter></term>
4363
+
<listitem>
4364
+
<simpara>
4365
+
The XML parser calling the handler.
4366
+
</simpara>
4367
+
</listitem>
4368
+
</varlistentry>'>
4369
+
4370
+
<!ENTITY xml.changelog.parser-param '<row xmlns="http://docbook.org/ns/docbook">
4371
+
<entry>8.0.0</entry>
4372
+
<entry>
4373
+
<parameter>parser</parameter> expects an <classname>XMLParser</classname>
4374
+
instance now; previously, a valid <literal>xml</literal> <type>resource</type> was expected.
4375
+
</entry>
4376
+
</row>'>
4377
+
4378
+
<!-- Migration Guide snippets -->
4379
+
<!ENTITY migration56.openssl.peer-verification '
4380
+
<para xmlns="http://docbook.org/ns/docbook">
4381
+
All encrypted client streams now enable peer verification by default. By
4382
+
default, this will use OpenSSL's default CA bundle to verify the peer
4383
+
certificate. In most cases, no changes will need to be made to communicate
4384
+
with servers with valid SSL certificates, as distributors generally
4385
+
configure OpenSSL to use known good CA bundles.
4386
+
</para>
4387
+
4388
+
<para xmlns="http://docbook.org/ns/docbook">
4389
+
The default CA bundle may be overridden on a global basis by setting
4390
+
either the openssl.cafile or openssl.capath configuration setting, or on a
4391
+
per request basis by using the
4392
+
<link linkend="context.ssl.cafile"><parameter>cafile</parameter></link> or
4393
+
<link linkend="context.ssl.capath"><parameter>capath</parameter></link>
4394
+
context options.
4395
+
</para>
4396
+
4397
+
<para xmlns="http://docbook.org/ns/docbook">
4398
+
While not recommended in general, it is possible to disable peer
4399
+
certificate verification for a request by setting the
4400
+
<link linkend="context.ssl.verify-peer"><parameter>verify_peer</parameter></link>
4401
+
context option to &false;, and to disable peer name validation by setting
4402
+
the <link linkend="context.ssl.verify-peer-name"><parameter>verify_peer_name</parameter></link>
4403
+
context option to &false;.
4404
+
</para>
4405
+
'>
4406
+
4407
+
<!-- Keep this comment at the end of the file
4408
+
Local variables:
4409
+
mode: sgml
4410
+
sgml-omittag:t
4411
+
sgml-shorttag:t
4412
+
sgml-minimize-attributes:nil
4413
+
sgml-always-quote-attributes:t
4414
+
sgml-indent-step:1
4415
+
sgml-indent-data:t
4416
+
indent-tabs-mode:nil
4417
+
sgml-parent-document:nil
4418
+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
4419
+
sgml-exposed-tags:nil
4420
+
sgml-local-catalogs:nil
4421
+
sgml-local-ecat-files:nil
4422
+
End:
4423
+
vim600: fen fdm=syntax fdl=2 si
4424
+
vim: et tw=78
4425
+
vi: ts=1 sw=1
4426
+
-->
1728
4427