language-snippets.ent
cb6d65ebe2412bbaef6d1edd076911539f1aceda
cb6d65ebe2412bbaef6d1edd076911539f1aceda
...
...
@@ -1,22 +1,59 @@
1
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
'>
...
...
@@ -165,21 +233,14 @@ the names of its functions and any other documentation surrounding this
165
233
extension may change without notice in a future release of PHP.
166
234
This extension should be used at your own risk.</simpara></warning>'>
167
235
236
+
<!ENTITY deprecated.function 'Deprecated this function.'>
237
+
<!ENTITY removed.function 'Removed this function.'>
238
+
168
239
<!ENTITY warn.deprecated.feature-5-3-0 '<warning
169
240
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
170
241
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature
171
242
is highly discouraged.</simpara></warning>'>
172
243
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
244
<!ENTITY warn.deprecated.feature-5-3-0.removed-5-4-0 '<warning
184
245
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
185
246
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0 and <emphasis>REMOVED</emphasis>
...
...
@@ -199,6 +260,122 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
199
260
<emphasis>DEPRECATED</emphasis> as of PHP 5.6.0. Relying on this feature
200
261
is highly discouraged.</simpara></warning>'>
201
262
263
+
<!ENTITY warn.deprecated.feature-7-0-0 '<warning
264
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
265
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.0.0. Relying on this feature
266
+
is highly discouraged.</simpara></warning>'>
267
+
268
+
<!ENTITY warn.deprecated.feature-7-1-0 '<warning
269
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
270
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0. Relying on this feature
271
+
is highly discouraged.</simpara></warning>'>
272
+
273
+
<!ENTITY warn.deprecated.function-7-1-0 '<warning
274
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
275
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0. Relying on this function
276
+
is highly discouraged.</simpara></warning>'>
277
+
278
+
<!ENTITY warn.deprecated.function-7-0-0.removed-8-0-0 '<warning
279
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
280
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.0.0 and
281
+
<emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
282
+
is highly discouraged.</simpara></warning>'>
283
+
284
+
<!ENTITY warn.deprecated.function-7-1-0.removed-7-2-0 '<warning
285
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
286
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0 and
287
+
<emphasis>REMOVED</emphasis> as of PHP 7.2.0. Relying on this function
288
+
is highly discouraged.</simpara></warning>'>
289
+
290
+
<!ENTITY warn.deprecated.feature-7-2-0 '<warning
291
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
292
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0. Relying on this feature
293
+
is highly discouraged.</simpara></warning>'>
294
+
295
+
<!ENTITY warn.deprecated.feature-7-2-0.removed-8-0-0 '<warning
296
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
297
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this feature
298
+
is highly discouraged.</simpara></warning>'>
299
+
300
+
<!ENTITY warn.deprecated.function-7-2-0 '<warning
301
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
302
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0. Relying on this function
303
+
is highly discouraged.</simpara></warning>'>
304
+
305
+
<!ENTITY warn.deprecated.function-7-2-0.removed-8-0-0 '<warning
306
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
307
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
308
+
is highly discouraged.</simpara></warning>'>
309
+
310
+
<!ENTITY warn.deprecated.feature-7-3-0 '<warning
311
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
312
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0. Relying on this feature
313
+
is highly discouraged.</simpara></warning>'>
314
+
315
+
<!ENTITY warn.deprecated.function-7-3-0 '<warning
316
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
317
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0. Relying on this function
318
+
is highly discouraged.</simpara></warning>'>
319
+
320
+
<!ENTITY warn.deprecated.function-7-3-0.removed-8-0-0 '<warning
321
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
322
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
323
+
is highly discouraged.</simpara></warning>'>
324
+
325
+
<!ENTITY warn.deprecated.feature-7-4-0 '<warning
326
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
327
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0. Relying on this feature
328
+
is highly discouraged.</simpara></warning>'>
329
+
330
+
<!ENTITY warn.deprecated.function-7-4-0 '<warning
331
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
332
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0. Relying on this function
333
+
is highly discouraged.</simpara></warning>'>
334
+
335
+
<!ENTITY warn.deprecated.function-7-4-0.removed-8-0-0 '<warning
336
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
337
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
338
+
is highly discouraged.</simpara></warning>'>
339
+
340
+
<!ENTITY warn.feature.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook">
341
+
<simpara>This feature was <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara>
342
+
</warning>'>
343
+
344
+
<!ENTITY warn.deprecated.function-8-0-0 '<warning
345
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
346
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0. Relying on this function
347
+
is highly discouraged.</simpara></warning>'>
348
+
349
+
<!ENTITY warn.deprecated.function-8-1-0 '<warning
350
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
351
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
352
+
is highly discouraged.</simpara></warning>'>
353
+
354
+
<!ENTITY warn.deprecated.function-8-2-0 '<warning
355
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
356
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.2.0. Relying on this function
357
+
is highly discouraged.</simpara></warning>'>
358
+
359
+
<!ENTITY warn.deprecated.feature-8-3-0 '<warning
360
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
361
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this feature
362
+
is highly discouraged.</simpara></warning>'>
363
+
364
+
<!ENTITY warn.deprecated.function-8-3-0 '<warning
365
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
366
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this function
367
+
is highly discouraged.</simpara></warning>'>
368
+
369
+
<!ENTITY warn.deprecated.feature-8-4-0 '<warning
370
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
371
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.4.0. Relying on this feature
372
+
is highly discouraged.</simpara></warning>'>
373
+
374
+
<!ENTITY warn.deprecated.function-8-4-0 '<warning
375
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
376
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.4.0. Relying on this function
377
+
is highly discouraged.</simpara></warning>'>
378
+
202
379
<!ENTITY removed.php.future 'This deprecated feature <emphasis xmlns="http://docbook.org/ns/docbook">will</emphasis>
203
380
certainly be <emphasis xmlns="http://docbook.org/ns/docbook">removed</emphasis> in the future.'>
204
381
...
...
@@ -226,6 +403,50 @@ on this alias is highly discouraged.</simpara></warning>'>
226
403
<simpara>This function has been <emphasis>DEPRECATED</emphasis> as of PHP 5.5.0. Relying
227
404
on this function is highly discouraged.</simpara></warning>'>
228
405
406
+
<!ENTITY warn.deprecated.feature-5-5-0.removed-7-0-0 '<warning
407
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature was
408
+
<emphasis>DEPRECATED</emphasis> in PHP 5.5.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
409
+
410
+
<!ENTITY warn.deprecated.function-5-5-0.removed-7-0-0 '<warning
411
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
412
+
<emphasis>DEPRECATED</emphasis> in PHP 5.5.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
413
+
414
+
<!ENTITY warn.deprecated.function-4-1-0.removed-7-0-0 '<warning
415
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
416
+
<emphasis>DEPRECATED</emphasis> in PHP 4.1.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
417
+
418
+
<!ENTITY warn.deprecated.function-5-3-0.removed-7-0-0 '<warning
419
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
420
+
<emphasis>DEPRECATED</emphasis> in PHP 5.3.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
421
+
422
+
<!ENTITY warn.deprecated.alias-5-3-0.removed-7-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was
423
+
<emphasis>DEPRECATED</emphasis> in PHP 5.3.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
424
+
425
+
<!ENTITY warn.deprecated.feature-5-6-0.removed-7-0-0 '<warning
426
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature was
427
+
<emphasis>DEPRECATED</emphasis> in PHP 5.6.0, and
428
+
<emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
429
+
430
+
<!ENTITY warn.removed.function-7-0-0 '<warning
431
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
432
+
<emphasis>REMOVED</emphasis> in PHP 7.0.0.</simpara></warning>'>
433
+
434
+
<!ENTITY warn.removed.function-7-4-0 '<warning
435
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
436
+
<emphasis>REMOVED</emphasis> in PHP 7.4.0.</simpara></warning>'>
437
+
438
+
<!ENTITY warn.deprecated.alias-7-2-0.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was
439
+
<emphasis>DEPRECATED</emphasis> in PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
440
+
441
+
<!ENTITY warn.deprecated.alias-7-4-0.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was
442
+
<emphasis>DEPRECATED</emphasis> in PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
443
+
444
+
<!ENTITY warn.deprecated.alias-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias is
445
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
446
+
447
+
<!ENTITY warn.removed.alias-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias is
448
+
<emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
449
+
229
450
<!ENTITY warn.experimental.func '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function is
230
451
<emphasis>EXPERIMENTAL</emphasis>. The behaviour of this function, its name, and
231
452
surrounding documentation may change without notice in a future release of PHP.
...
...
@@ -233,9 +454,9 @@ This function should be used at your own risk.
233
454
</simpara></warning>'>
234
455
235
456
<!ENTITY warn.imaprecodeyaz '<warning xmlns="http://docbook.org/ns/docbook"><simpara>The <link
236
-
linkend="book.imap">IMAP</link>, <link linkend="book.recode">recode</link>,
237
-
<link linkend="book.yaz">YAZ</link> and <link linkend="book.cyrus">Cyrus</link>
238
-
extensions cannot be used in conjuction, because they
457
+
linkend="book.imap">IMAP</link>, <link linkend="book.recode">recode</link> and
458
+
<link linkend="book.yaz">YAZ</link>
459
+
extensions cannot be used in conjunction, because they
239
460
share the same internal symbols. Note: Yaz 2.0 and above does not suffer from this problem.</simpara></warning>'>
240
461
241
462
<!ENTITY warn.install.cgi '<warning xmlns="http://docbook.org/ns/docbook"><para>A server deployed in CGI mode is open
...
...
@@ -243,16 +464,16 @@ to several possible vulnerabilities. Please read our
243
464
<link linkend="security.cgi-bin">CGI security section</link> to learn how to
244
465
defend yourself from such attacks.</para></warning>'>
245
466
246
-
<!ENTITY note.magicquotes.gpc '<note xmlns="http://docbook.org/ns/docbook"><title>directive note: magic_quotes_gpc
247
-
</title><para>The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>
248
-
directive defaults to <literal>on</literal>. It essentially runs
249
-
<function>addslashes</function> on all GET, POST, and COOKIE data.
250
-
<function>stripslashes</function> may be used to remove them.</para></note>'>
251
-
252
-
<!ENTITY warn.no-win32-fopen-wrapper '<warning xmlns="http://docbook.org/ns/docbook"><para>Windows versions of PHP
253
-
prior to PHP 4.3.0 do not support access of remote files via this function,
254
-
even if <link linkend="ini.allow-url-fopen">allow_url_fopen</link> is enabled.
255
-
</para></warning>'>
467
+
<!ENTITY warn.passwordhashing '
468
+
<warning xmlns="http://docbook.org/ns/docbook">
469
+
<para>
470
+
It is not recommended to use this function to secure passwords,
471
+
due to the fast nature of this hashing algorithm. See the
472
+
<link linkend="faq.passwords.fasthash">Password Hashing FAQ</link>
473
+
for details and best practices.
474
+
</para>
475
+
</warning>
476
+
'>
256
477
257
478
<!ENTITY warn.ssl-non-standard '<warning xmlns="http://docbook.org/ns/docbook"><para>When using SSL, Microsoft IIS
258
479
will violate the protocol by closing the connection without sending a
...
...
@@ -260,31 +481,129 @@ will violate the protocol by closing the connection without sending a
260
481
Protocol Error" when you reach the end of the data. To work around this, the
261
482
value of <link linkend="ini.error-reporting">error_reporting</link> should be
262
483
lowered to a level that does not include warnings.
263
-
PHP 4.3.7 and higher can detect buggy IIS server software when you open
484
+
PHP can detect buggy IIS server software when you open
264
485
the stream using the <literal>https://</literal> wrapper and will suppress the
265
486
warning. When using <function>fsockopen</function> to create an
266
487
<literal>ssl://</literal> socket, the developer is responsible for detecting
267
488
and suppressing this warning.</para></warning>'>
268
489
490
+
<!ENTITY warn.undocumented.class '
491
+
<warning xmlns="http://docbook.org/ns/docbook">
492
+
<simpara>
493
+
This class is currently undocumented; only a list of its properties and
494
+
methods is available.
495
+
</simpara>
496
+
</warning>
497
+
'>
498
+
269
499
<!ENTITY warn.undocumented.func '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function is
270
500
currently not documented; only its argument list is available.
271
501
</simpara></warning>'>
272
502
273
503
504
+
<!-- Deprecation and removal warnings designed for use with a list of
505
+
alternatives. See en/reference/regex/functions/ereg.xml and
506
+
en/reference/regex/reference.xml for examples of these in action. -->
507
+
508
+
<!ENTITY warn.deprecated.function.4-1-0.removed.7-0-0.alternatives '
509
+
<para xmlns="http://docbook.org/ns/docbook">
510
+
This function was <emphasis>DEPRECATED</emphasis> in PHP 4.1.0, and
511
+
<emphasis>REMOVED</emphasis> in PHP 7.0.0.
512
+
</para>
513
+
<para xmlns="http://docbook.org/ns/docbook">
514
+
Alternatives to this function include:
515
+
</para>
516
+
'>
517
+
518
+
<!ENTITY warn.deprecated.feature.5-3-0.removed.7-0-0.alternatives '
519
+
<para xmlns="http://docbook.org/ns/docbook">
520
+
This feature was <emphasis>DEPRECATED</emphasis> in PHP 5.3.0, and
521
+
<emphasis>REMOVED</emphasis> in PHP 7.0.0.
522
+
</para>
523
+
<para xmlns="http://docbook.org/ns/docbook">
524
+
Alternatives to this feature include:
525
+
</para>
526
+
'>
527
+
528
+
<!ENTITY warn.deprecated.function.5-3-0.removed.7-0-0.alternatives '
529
+
<para xmlns="http://docbook.org/ns/docbook">
530
+
This function was <emphasis>DEPRECATED</emphasis> in PHP 5.3.0, and
531
+
<emphasis>REMOVED</emphasis> in PHP 7.0.0.
532
+
</para>
533
+
<para xmlns="http://docbook.org/ns/docbook">
534
+
Alternatives to this function include:
535
+
</para>
536
+
'>
537
+
538
+
<!ENTITY warn.deprecated.function.5-5-0.removed.7-0-0.alternatives '
539
+
<para xmlns="http://docbook.org/ns/docbook">
540
+
This function was <emphasis>DEPRECATED</emphasis> in PHP 5.5.0, and
541
+
<emphasis>REMOVED</emphasis> in PHP 7.0.0.
542
+
</para>
543
+
<para xmlns="http://docbook.org/ns/docbook">
544
+
Alternatives to this function include:
545
+
</para>
546
+
'>
547
+
548
+
<!ENTITY warn.removed.feature.7-0-0.alternatives '
549
+
<para xmlns="http://docbook.org/ns/docbook">
550
+
This feature was <emphasis>REMOVED</emphasis> in PHP 7.0.0.
551
+
</para>
552
+
<para xmlns="http://docbook.org/ns/docbook">
553
+
Alternatives to this feature include:
554
+
</para>
555
+
'>
556
+
557
+
<!ENTITY warn.removed.function.7-0-0.alternatives '
558
+
<para xmlns="http://docbook.org/ns/docbook">
559
+
This function was <emphasis>REMOVED</emphasis> in PHP 7.0.0.
560
+
</para>
561
+
<para xmlns="http://docbook.org/ns/docbook">
562
+
Alternatives to this function include:
563
+
</para>
564
+
'>
565
+
566
+
<!ENTITY warn.deprecated.feature.7-1-0.removed.7-2-0.alternatives '
567
+
<para xmlns="http://docbook.org/ns/docbook">
568
+
This feature was <emphasis>DEPRECATED</emphasis> in PHP 7.1.0, and
569
+
<emphasis>REMOVED</emphasis> in PHP 7.2.0.
570
+
</para>
571
+
<para xmlns="http://docbook.org/ns/docbook">
572
+
Alternatives to this feature include:
573
+
</para>
574
+
'>
575
+
576
+
<!ENTITY warn.deprecated.function.7-1-0.removed.7-2-0.alternatives '
577
+
<para xmlns="http://docbook.org/ns/docbook">
578
+
This function was <emphasis>DEPRECATED</emphasis> in PHP 7.1.0, and
579
+
<emphasis>REMOVED</emphasis> in PHP 7.2.0.
580
+
</para>
581
+
<para xmlns="http://docbook.org/ns/docbook">
582
+
Alternatives to this function include:
583
+
</para>
584
+
'>
585
+
586
+
<!ENTITY warn.deprecated.function-8-1-0.alternatives '<warning
587
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
588
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
589
+
is highly discouraged.</simpara></warning>
590
+
<para xmlns="http://docbook.org/ns/docbook">
591
+
Alternatives to this function include:
592
+
</para>
593
+
'>
594
+
274
595
<!-- Misc -->
275
596
276
597
<!ENTITY version.exists.asof 'This exists as of PHP '>
277
598
278
-
<!ENTITY version.trunk.after.53 '<emphasis xmlns="http://docbook.org/ns/docbook">This change
279
-
exists in the <link linkend="about.phpversions">development version</link> of PHP, and will
280
-
probably exist after 5.3.</emphasis>'>
281
-
282
599
<!ENTITY version.trunk.changelog 'Future'>
283
600
284
601
<!ENTITY no.function.parameters '<para xmlns="http://docbook.org/ns/docbook">This function has no parameters.</para>'>
285
602
286
603
<!ENTITY example.outputs '<para xmlns="http://docbook.org/ns/docbook">The above example will output:</para>'>
287
604
605
+
<!ENTITY example.outputs.5 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5:</para>'>
606
+
288
607
<!ENTITY example.outputs.53 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.3:</para>'>
289
608
290
609
<!ENTITY example.outputs.54 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.4:</para>'>
...
...
@@ -293,6 +612,36 @@ probably exist after 5.3.</emphasis>'>
293
612
294
613
<!ENTITY example.outputs.56 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.6:</para>'>
295
614
615
+
<!ENTITY example.outputs.7 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7:</para>'>
616
+
617
+
<!ENTITY example.outputs.70 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.0:</para>'>
618
+
619
+
<!ENTITY example.outputs.71 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.1:</para>'>
620
+
621
+
<!ENTITY example.outputs.72 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.2:</para>'>
622
+
623
+
<!ENTITY example.outputs.73 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.3:</para>'>
624
+
625
+
<!ENTITY example.outputs.8 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8:</para>'>
626
+
627
+
<!ENTITY example.outputs.8.similar '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8 is similar to:</para>'>
628
+
629
+
<!ENTITY example.outputs.80 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.0:</para>'>
630
+
631
+
<!ENTITY example.outputs.81 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.1:</para>'>
632
+
633
+
<!ENTITY example.outputs.82 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.2:</para>'>
634
+
635
+
<!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>'>
636
+
637
+
<!ENTITY example.outputs.83 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.3:</para>'>
638
+
639
+
<!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>'>
640
+
641
+
<!ENTITY example.outputs.84 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.4:</para>'>
642
+
643
+
<!ENTITY example.outputs.84.similar '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.4 is similar to:</para>'>
644
+
296
645
<!ENTITY example.outputs.32bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 32 bit machines:</para>'>
297
646
298
647
<!ENTITY example.outputs.64bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 64 bit machines:</para>'>
...
...
@@ -313,17 +662,110 @@ something similar to:</para>'>
313
662
<function>reset</function> the <type>array</type> pointer of the input array after
314
663
use.</simpara></note>'>
315
664
665
+
<!ENTITY array.changelog.by-ref '<row xmlns="http://docbook.org/ns/docbook">
666
+
<entry>8.0.0</entry>
667
+
<entry>
668
+
If <parameter>callback</parameter> expects a parameter to be passed
669
+
by reference, this function will now emit an <constant>E_WARNING</constant>.
670
+
</entry>
671
+
</row>'>
672
+
673
+
<!ENTITY array.changelog.require-only-one '<row xmlns="http://docbook.org/ns/docbook">
674
+
<entry>8.0.0</entry>
675
+
<entry>
676
+
This function can now be called with only one parameter.
677
+
Formerly, at least two parameters have been required.
678
+
</entry>
679
+
</row>'>
680
+
316
681
<!ENTITY seealso.array.sorting 'The <link xmlns="http://docbook.org/ns/docbook" linkend="array.sorting">comparison of array sorting functions</link>'>
317
682
318
-
<!ENTITY seealso.callback 'information about the <link xmlns="http://docbook.org/ns/docbook" linkend="language.types.callback">callback</link> type'>
683
+
<!ENTITY sort.flags.parameter '<varlistentry xmlns="http://docbook.org/ns/docbook">
684
+
<term><parameter>flags</parameter></term>
685
+
<listitem>
686
+
<para>
687
+
The optional second parameter <parameter>flags</parameter>
688
+
may be used to modify the sorting behavior using these values:
689
+
</para>
690
+
<para>
691
+
Sorting type flags:
692
+
<itemizedlist>
693
+
<listitem>
694
+
<simpara><constant>SORT_REGULAR</constant> - compare items normally;
695
+
the details are described in the <link linkend="language.operators.comparison">comparison operators</link> section</simpara>
696
+
</listitem>
697
+
<listitem>
698
+
<simpara><constant>SORT_NUMERIC</constant> - compare items numerically</simpara>
699
+
</listitem>
700
+
<listitem>
701
+
<simpara><constant>SORT_STRING</constant> - compare items as strings</simpara>
702
+
</listitem>
703
+
<listitem>
704
+
<simpara>
705
+
<constant>SORT_LOCALE_STRING</constant> - compare items as
706
+
strings, based on the current locale. It uses the locale,
707
+
which can be changed using <function>setlocale</function>
708
+
</simpara>
709
+
</listitem>
710
+
<listitem>
711
+
<simpara>
712
+
<constant>SORT_NATURAL</constant> - compare items as strings
713
+
using "natural ordering" like <function>natsort</function>
714
+
</simpara>
715
+
</listitem>
716
+
<listitem>
717
+
<simpara>
718
+
<constant>SORT_FLAG_CASE</constant> - can be combined
719
+
(bitwise OR) with
720
+
<constant>SORT_STRING</constant> or
721
+
<constant>SORT_NATURAL</constant> to sort strings case-insensitively
722
+
</simpara>
723
+
</listitem>
724
+
</itemizedlist>
725
+
</para>
726
+
</listitem>
727
+
</varlistentry>
728
+
'>
729
+
730
+
<!ENTITY sort.callback.description '<para xmlns="http://docbook.org/ns/docbook">
731
+
&return.callbacksort;
732
+
</para>
733
+
&callback.cmp;
734
+
<caution xmlns="http://docbook.org/ns/docbook">
735
+
<para>
736
+
Returning <emphasis>non-integer</emphasis> values from the comparison
737
+
function, such as <type>float</type>, will result in an internal cast to
738
+
<type>int</type> of the callback's return value. So values such as
739
+
<literal>0.99</literal> and <literal>0.1</literal> will both be cast to an
740
+
integer value of <literal>0</literal>, which will compare such values as equal.
741
+
</para>
742
+
</caution>'>
743
+
744
+
<!ENTITY sort.callback.description.presort '<caution xmlns="http://docbook.org/ns/docbook">
745
+
<para>
746
+
The sorting callback must handle any value from any array in any order,
747
+
regardless of the order they were originally provided.
748
+
This is because each individual array is first sorted before being compared against other arrays.
319
749
320
-
<!ENTITY avail.register-long-arrays 'As of PHP 5.0.0, the long PHP
321
-
<link xmlns="http://docbook.org/ns/docbook" linkend="language.variables.predefined">predefined variable</link>
322
-
arrays may be disabled with the
323
-
<link xmlns="http://docbook.org/ns/docbook" linkend="ini.register-long-arrays">register_long_arrays</link>
324
-
directive.'>
750
+
For example:
751
+
<programlisting role="php">
752
+
<![CDATA[
753
+
<?php
754
+
$arrayA = ["string", 1];
755
+
$arrayB = [["value" => 1]];
756
+
// $item1 and $item2 can be any of "string", 1 or ["value" => 1]
757
+
$compareFunc = static function ($item1, $item2) {
758
+
$value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);
759
+
$value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);
760
+
return $value1 <=> $value2;
761
+
};
762
+
?>
763
+
]]>
764
+
</programlisting>
765
+
</para>
766
+
</caution>'>
325
767
326
-
<!ENTITY ini.shorthandbytes '<simpara xmlns="http://docbook.org/ns/docbook">When an <type>integer</type> is used, the
768
+
<!ENTITY ini.shorthandbytes '<simpara xmlns="http://docbook.org/ns/docbook">When an <type>int</type> is used, the
327
769
value is measured in bytes. Shorthand notation, as described
328
770
in <link linkend="faq.using.shorthandbytes">this FAQ</link>, may also be used.
329
771
</simpara>'>
...
...
@@ -354,14 +796,10 @@ files from the PHP folder into the Windows system directory also works
354
796
355
797
<!ENTITY manual.migration.seealso 'See also the migration guides for PHP versions'>
356
798
357
-
<!ENTITY style.oop 'Object oriented style'>
799
+
<!ENTITY style.oop 'Object-oriented style'>
358
800
<!ENTITY style.procedural 'Procedural style'>
359
801
360
-
<!ENTITY resource '<link xmlns="http://docbook.org/ns/docbook" linkend="language.types.resource">resource</link>'>
361
-
362
-
<!ENTITY foreach '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.foreach">foreach</link>'>
363
-
364
-
<!ENTITY yield '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.yield">yield</link>'>
802
+
<!ENTITY match '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.match">match</link>'>
365
803
366
804
<!ENTITY parameter.context 'Refer to the <link xmlns="http://docbook.org/ns/docbook" linkend="context">context</link>
367
805
section of the manual for a description of <literal xmlns="http://docbook.org/ns/docbook">contexts</literal>.'>
...
...
@@ -371,13 +809,24 @@ searched for within the <link xmlns="http://docbook.org/ns/docbook" linkend="ini
371
809
372
810
<!-- Returns -->
373
811
812
+
<!ENTITY return.type.true '<row xmlns="http://docbook.org/ns/docbook">
813
+
<entry>8.2.0</entry>
814
+
<entry>
815
+
The return type is &true; now; previously, it was <type>bool</type>.
816
+
</entry>
817
+
</row>'>
818
+
374
819
<!ENTITY return.falseforfailure ' or &false; on failure'>
375
820
<!ENTITY return.falseforfailure.style.procedural '&style.procedural; returns &false; on failure.'>
376
821
377
822
<!ENTITY return.success 'Returns &true; on success&return.falseforfailure;.'>
378
823
824
+
<!ENTITY return.nullorfalse 'Returns &null; on success&return.falseforfailure;.'>
825
+
379
826
<!ENTITY return.void 'No value is returned.'>
380
827
828
+
<!ENTITY return.true.always 'Always returns &true;.'>
829
+
381
830
<!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.'>
382
831
383
832
<!ENTITY return.falseproblem '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function may
...
...
@@ -388,6 +837,44 @@ information. Use <link linkend="language.operators.comparison">the ===
388
837
operator</link> for testing the return value of this
389
838
function.</simpara></warning>'>
390
839
840
+
<!-- Standard -->
841
+
<!ENTITY standard.changelog.calling-on-objects '<row xmlns="http://docbook.org/ns/docbook">
842
+
<entry>8.1.0</entry>
843
+
<entry>
844
+
Calling this function on &object;s is deprecated.
845
+
Either convert the &object; to an &array; using <function>get_mangled_object_vars</function> first, or use the methods
846
+
provided by a class that implements <interfacename>Iterator</interfacename>, such as <classname>ArrayIterator</classname>, instead.
847
+
</entry>
848
+
</row>
849
+
<row xmlns="http://docbook.org/ns/docbook">
850
+
<entry>7.4.0</entry>
851
+
<entry>
852
+
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.
853
+
</entry>
854
+
</row>
855
+
'>
856
+
857
+
<!ENTITY standard.changelog.binary-safe-string-comparison '<row xmlns="http://docbook.org/ns/docbook">
858
+
<entry>8.2.0</entry>
859
+
<entry>
860
+
This function is no longer guaranteed to return
861
+
<code>strlen($string1) - strlen($string2)</code> when string lengths
862
+
are not equal, but may now return <literal>-1</literal> or
863
+
<literal>1</literal> instead.
864
+
</entry>
865
+
</row>
866
+
'>
867
+
868
+
<!-- FileInfo -->
869
+
<!ENTITY fileinfo.parameters.finfo '<para xmlns="http://docbook.org/ns/docbook">An <classname>finfo</classname> instance, returned by <function>finfo_open</function>.</para>'>
870
+
<!ENTITY fileinfo.changelog.finfo-object '<row xmlns="http://docbook.org/ns/docbook">
871
+
<entry>8.1.0</entry>
872
+
<entry>
873
+
The <parameter>finfo</parameter> parameter expects an <classname>finfo</classname>
874
+
instance now; previously, a &resource; was expected.
875
+
</entry>
876
+
</row>'>
877
+
391
878
<!-- OpenSSL -->
392
879
<!ENTITY openssl.param.x509 '<varlistentry xmlns="http://docbook.org/ns/docbook">
393
880
<term><parameter>x509</parameter></term>
...
...
@@ -398,41 +885,105 @@ function.</simpara></warning>'>
398
885
</listitem>
399
886
</varlistentry>'>
400
887
401
-
<!-- Image (GD) Notes -->
402
-
<!ENTITY note.config.t1lib '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available
403
-
if PHP is compiled using <option role="configure">--with-t1lib[=DIR]</option>.
404
-
</simpara></note>'>
405
-
406
-
<!ENTITY note.config.jpeg '<note xmlns="http://docbook.org/ns/docbook"><simpara>JPEG support is only available if
407
-
PHP was compiled against GD-1.8 or later.</simpara></note>'>
408
-
409
-
<!ENTITY note.config.wbmp '<note xmlns="http://docbook.org/ns/docbook"><simpara>WBMP support is only available if
410
-
PHP was compiled against GD-1.8 or later.</simpara></note>'>
888
+
<!ENTITY openssl.param.csr '<varlistentry xmlns="http://docbook.org/ns/docbook">
889
+
<term><parameter>csr</parameter></term>
890
+
<listitem>
891
+
<para>
892
+
See <link linkend="openssl.certparams">CSR parameters</link> for a list of valid values.
893
+
</para>
894
+
</listitem>
895
+
</varlistentry>'>
411
896
412
-
<!ENTITY note.bundled.gd '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available if
413
-
PHP is compiled with the bundled version of the GD library.</simpara></note>'>
897
+
<!ENTITY openssl.param.key '<varlistentry xmlns="http://docbook.org/ns/docbook">
898
+
<term><parameter>key</parameter></term>
899
+
<listitem>
900
+
<para>
901
+
See <link linkend="openssl.certparams">Public/Private Key parameters</link> for a list of valid values.
902
+
</para>
903
+
</listitem>
904
+
</varlistentry>'>
905
+
906
+
<!-- Image (GD) Notes -->
907
+
<!ENTITY note.config.t1lib '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available
908
+
if PHP is compiled using <option role="configure">--with-t1lib[=DIR]</option>.
909
+
</simpara></note>'>
414
910
415
911
<!ENTITY note.freetype '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available if
416
912
PHP is compiled with freetype support (<option role="configure">--with-freetype-dir=DIR</option>)
417
913
</simpara></note>'>
418
914
419
-
<!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>'>
420
-
421
915
<!ENTITY note.gd.notrequired '<note xmlns="http://docbook.org/ns/docbook"><para>This function does not require the GD image library.</para></note>'>
422
916
423
917
<!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>'>
424
918
425
-
<!ENTITY gd.image.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
426
-
image</parameter></term><listitem><para>An image resource, returned by one of the image creation functions,
919
+
<!ENTITY gd.image.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
920
+
<parameter>image</parameter></term><listitem><para>A <classname>GdImage</classname> object, returned by one of the image creation functions,
427
921
such as <function>imagecreatetruecolor</function>.</para></listitem></varlistentry>'>
428
922
429
-
<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
430
-
font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in
431
-
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or any of your
432
-
own font identifiers registered with <function>imageloadfont</function>.
433
-
</para></listitem></varlistentry>'>
923
+
<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
924
+
<parameter>font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in
925
+
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or <classname>GdFont</classname> instance,
926
+
returned by <function>imageloadfont</function>.</para></listitem></varlistentry>'>
434
927
435
-
<!ENTITY gd.return.identifier 'Returns an image resource identifier on success, &false; on errors.'>
928
+
<!ENTITY gd.changelog.gdfont-instance '<row xmlns="http://docbook.org/ns/docbook">
929
+
<entry>8.1.0</entry>
930
+
<entry>
931
+
The <parameter>font</parameter> parameter now accepts both an <classname>GdFont</classname> instance
932
+
and an &integer;; previously only &integer; was accepted.
933
+
</entry>
934
+
</row>'>
935
+
936
+
<!ENTITY gd.ttf.fontfile "
937
+
<varlistentry xmlns='http://docbook.org/ns/docbook'>
938
+
<term><parameter>fontfile</parameter></term>
939
+
<listitem>
940
+
<para>
941
+
The path to the TrueType font you wish to use.
942
+
</para>
943
+
<para>
944
+
Depending on which version of the GD library PHP is using, <emphasis>when
945
+
<parameter>fontfile</parameter> does not begin with a leading
946
+
<literal>/</literal> then <literal>.ttf</literal> will be appended</emphasis>
947
+
to the filename and the library will attempt to search for that
948
+
filename along a library-defined font path.
949
+
</para>
950
+
<para>
951
+
When using versions of the GD library lower than 2.0.18, a <literal>space</literal> character,
952
+
rather than a semicolon, was used as the 'path separator' for different font files.
953
+
Unintentional use of this feature will result in the warning message:
954
+
<literal>Warning: Could not find/open font</literal>. For these affected versions, the
955
+
only solution is moving the font to a path which does not contain spaces.
956
+
</para>
957
+
<para>
958
+
In many cases where a font resides in the same directory as the script using it
959
+
the following trick will alleviate any include problems.
960
+
<programlisting role='php'>
961
+
<![CDATA[
962
+
<?php
963
+
// Set the environment variable for GD
964
+
putenv('GDFONTPATH=' . realpath('.'));
965
+
966
+
// Name the font to be used (note the lack of the .ttf extension)
967
+
$font = 'SomeFont';
968
+
?>
969
+
]]>
970
+
</programlisting>
971
+
</para>
972
+
<note>
973
+
<para>
974
+
Note that <link linkend='ini.open-basedir'>open_basedir</link> does
975
+
<emphasis>not</emphasis> apply to <parameter>fontfile</parameter>.
976
+
</para>
977
+
</note>
978
+
</listitem>
979
+
</varlistentry>
980
+
">
981
+
982
+
<!ENTITY gd.return.identifier 'Returns an image object on success, &false; on errors.'>
983
+
984
+
<!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>'>
985
+
986
+
<!ENTITY gd.identifier.color "A color identifier created with <function xmlns='http://docbook.org/ns/docbook'>imagecolorallocate</function>.">
436
987
437
988
<!ENTITY gd.value.red 'Value of red component.'>
438
989
...
...
@@ -444,24 +995,98 @@ own font identifiers registered with <function>imageloadfont</function>.
444
995
445
996
<!ENTITY gd.source.width 'Source width.'>
446
997
447
-
<!ENTITY gd.image.path 'The path to save the file to. If not set or &null;, the raw image stream will be outputted directly.'>
998
+
<!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.'>
448
999
449
1000
<!ENTITY gd.image.new 'Create a new image from file or URL'>
450
1001
451
-
<!ENTITY gd.image.source 'Source image link resource.'>
1002
+
<!ENTITY gd.image.source 'Source image resource.'>
452
1003
453
-
<!ENTITY gd.image.destination 'Destination image link resource.'>
1004
+
<!ENTITY gd.image.destination 'Destination image resource.'>
454
1005
455
1006
<!ENTITY gd.image.output 'Output image to browser or file'>
456
1007
457
1008
<!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.'>
458
1009
459
-
<!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).'>
1010
+
<!ENTITY gd.font.size 'The font size in points.'>
1011
+
1012
+
<!ENTITY gd.constants.types '<simpara xmlns="http://docbook.org/ns/docbook">
1013
+
Used as a return value by <function>imagetypes</function>
1014
+
</simpara>'>
1015
+
1016
+
<!ENTITY gd.constants.color '<simpara xmlns="http://docbook.org/ns/docbook">
1017
+
Special color option which can be used instead of a color allocated with
1018
+
<function>imagecolorallocate</function> or
1019
+
<function>imagecolorallocatealpha</function>.
1020
+
</simpara>'>
1021
+
1022
+
<!ENTITY gd.constants.affine '<simpara xmlns="http://docbook.org/ns/docbook">
1023
+
An affine transformation type constant used by the <function>imageaffinematrixget</function> function.
1024
+
</simpara>'>
1025
+
1026
+
<!ENTITY gd.constants.arc '<simpara xmlns="http://docbook.org/ns/docbook">
1027
+
A style constant used by the <function>imagefilledarc</function> function.
1028
+
</simpara>'>
1029
+
1030
+
<!ENTITY gd.constants.gd2 '<simpara xmlns="http://docbook.org/ns/docbook">
1031
+
A type constant used by the <function>imagegd2</function> function.
1032
+
</simpara>'>
1033
+
1034
+
<!ENTITY gd.constants.effect '<simpara xmlns="http://docbook.org/ns/docbook">
1035
+
Alpha blending effect used by the <function>imagelayereffect</function> function.
1036
+
</simpara>'>
1037
+
1038
+
<!ENTITY gd.constants.filter '<simpara xmlns="http://docbook.org/ns/docbook">
1039
+
Special GD filter used by the <function>imagefilter</function> function.
1040
+
</simpara>'>
1041
+
1042
+
<!ENTITY gd.constants.type '<simpara xmlns="http://docbook.org/ns/docbook">
1043
+
Image type constant used by the <function>image_type_to_mime_type</function>
1044
+
and <function>image_type_to_extension</function> functions.
1045
+
</simpara>'>
1046
+
1047
+
<!ENTITY gd.constants.png-filter '<simpara xmlns="http://docbook.org/ns/docbook">
1048
+
A special PNG filter, used by the <function>imagepng</function> function.
1049
+
</simpara>'>
1050
+
1051
+
<!ENTITY gd.constants.flip '<simpara xmlns="http://docbook.org/ns/docbook">
1052
+
Used together with <function>imageflip</function>, available as of PHP 5.5.0.
1053
+
</simpara>'>
1054
+
1055
+
<!ENTITY gd.constants.interpolation '<simpara xmlns="http://docbook.org/ns/docbook">
1056
+
Used together with <function>imagesetinterpolation</function>, available as of PHP 5.5.0.
1057
+
</simpara>'>
1058
+
1059
+
<!ENTITY gd.changlog.t1lib '<row xmlns="http://docbook.org/ns/docbook">
1060
+
<entry>7.0.0</entry><entry>T1Lib support was removed from PHP, thus this function was removed.</entry>
1061
+
</row>'>
1062
+
1063
+
<!ENTITY gd.deprecated.gd-formats '<warning xmlns="http://docbook.org/ns/docbook"><simpara>The GD
1064
+
and GD2 image formats are proprietary image formats of libgd. They have to be regarded
1065
+
<emphasis>obsolete</emphasis>, and should only be used for development and testing
1066
+
purposes.</simpara></warning>'>
1067
+
1068
+
<!ENTITY gd.changelog.image-param '<row xmlns="http://docbook.org/ns/docbook">
1069
+
<entry>8.0.0</entry>
1070
+
<entry>
1071
+
<parameter>image</parameter> expects a <classname>GdImage</classname>
1072
+
instance now; previously, a valid <literal>gd</literal> <type>resource</type> was expected.
1073
+
</entry>
1074
+
</row>'>
1075
+
1076
+
<!-- CSV -->
1077
+
<!ENTITY warning.csv.escape-parameter '<warning xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"><simpara>
1078
+
When <parameter>escape</parameter> is set to anything other than an empty string
1079
+
(<literal>""</literal>) it can result in CSV that is not compliant with
1080
+
<link xlink:href="&url.rfc;4180">RFC 4180</link> or unable to survive a roundtrip
1081
+
through the PHP CSV functions. The default for <parameter>escape</parameter> is
1082
+
<literal>"\\"</literal> so it is recommended to set it to the empty string explicitly.
1083
+
The default value will change in a future version of PHP, no earlier than PHP 9.0.
1084
+
</simpara></warning>'>
460
1085
461
1086
<!-- DBM notes -->
462
1087
463
-
<!ENTITY dbm.dbm-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
464
-
dbm_identifier</parameter></term><listitem><para>The DBM link identifier,
1088
+
<!ENTITY dbm.dbm-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1089
+
<parameter>dbm_identifier</parameter></term><listitem><para>The DBM link identifier,
465
1090
returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
466
1091
467
1092
<!-- JSON notes -->
...
...
@@ -470,35 +1095,143 @@ returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
470
1095
<note xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
471
1096
<para>
472
1097
PHP implements a superset of JSON as specified in the original
473
-
<link xlink:href="&url.rfc;4627">RFC 4627</link> - it will also encode and
474
-
decode scalar types and &null;. RFC 4627 only supports these values when
475
-
they are nested inside an array or an object.
476
-
</para>
477
-
<para>
478
-
Although this superset is consistent with the expanded definition of "JSON
479
-
text" in the newer <link xlink:href="&url.rfc;7159">RFC 7159</link> (which
480
-
aims to supersede RFC 4627) and
481
-
<link xlink:href="&url.json.ecma;">ECMA-404</link>, this may cause
482
-
interoperability issues with older JSON parsers that adhere strictly to RFC
483
-
4627 when encoding a single scalar value.
1098
+
<link xlink:href="&url.rfc;7159">RFC 7159</link>.
484
1099
</para>
485
1100
</note>
486
1101
'>
487
1102
488
1103
<!-- cURL notes -->
489
1104
490
-
<!ENTITY curl.ch.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>ch</parameter>
1105
+
<!ENTITY curl.ch.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>handle</parameter>
491
1106
</term><listitem><para>A cURL handle returned by
492
1107
<function>curl_init</function>.</para></listitem></varlistentry>'>
493
1108
494
-
<!ENTITY curl.mh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>mh</parameter>
1109
+
<!ENTITY curl.mh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>multi_handle</parameter>
495
1110
</term><listitem><para>A cURL multi handle returned by
496
1111
<function>curl_multi_init</function>.</para></listitem></varlistentry>'>
497
1112
1113
+
<!ENTITY curl.sh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>share_handle</parameter>
1114
+
</term><listitem><para>A cURL share handle returned by
1115
+
<function>curl_share_init</function>.</para></listitem></varlistentry>'>
1116
+
1117
+
<!ENTITY curl.changelog.handle-param '<row xmlns="http://docbook.org/ns/docbook">
1118
+
<entry>8.0.0</entry>
1119
+
<entry>
1120
+
<parameter>handle</parameter> expects a <classname>CurlHandle</classname>
1121
+
instance now; previously, a <type>resource</type> was expected.
1122
+
</entry>
1123
+
</row>'>
1124
+
1125
+
<!ENTITY curl.changelog.multi-handle-param '<row xmlns="http://docbook.org/ns/docbook">
1126
+
<entry>8.0.0</entry>
1127
+
<entry>
1128
+
<parameter>multi_handle</parameter> expects a <classname>CurlMultiHandle</classname>
1129
+
instance now; previously, a <type>resource</type> was expected.
1130
+
</entry>
1131
+
</row>'>
1132
+
1133
+
<!ENTITY curl.changelog.share-handle-param '<row xmlns="http://docbook.org/ns/docbook">
1134
+
<entry>8.0.0</entry>
1135
+
<entry>
1136
+
<parameter>share_handle</parameter> expects a <classname>CurlShareHandle</classname>
1137
+
instance now; previously, a <type>resource</type> was expected.
1138
+
</entry>
1139
+
</row>'>
1140
+
1141
+
<!-- dba notes -->
1142
+
<!ENTITY dba.parameter.dba 'A <classname xmlns="http://docbook.org/ns/docbook">Dba\Connection</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">dba_open</function> or <function xmlns="http://docbook.org/ns/docbook">dba_popen</function>.'>
1143
+
<!ENTITY dba.changelog.dba-object '<row xmlns="http://docbook.org/ns/docbook">
1144
+
<entry>8.4.0</entry>
1145
+
<entry>
1146
+
The <parameter>dba</parameter> parameter expects a <classname>Dba\Connection</classname>
1147
+
instance now; previously, a valid <literal>dba</literal> &resource; was expected.
1148
+
</entry>
1149
+
</row>'>
1150
+
1151
+
<!-- dbase notes -->
1152
+
1153
+
<!ENTITY dbase.type-conversion '<para xmlns="http://docbook.org/ns/docbook">
1154
+
Each field is converted to the appropriate PHP type, except:
1155
+
<itemizedlist>
1156
+
<listitem>
1157
+
<simpara>
1158
+
Dates are left as strings.
1159
+
</simpara>
1160
+
</listitem>
1161
+
<listitem>
1162
+
<simpara>
1163
+
DateTime values are converted to strings.
1164
+
</simpara>
1165
+
</listitem>
1166
+
<listitem>
1167
+
<simpara>
1168
+
Integers outside the range
1169
+
<constant>PHP_INT_MIN</constant>..<constant>PHP_INT_MAX</constant> are
1170
+
returned as strings.
1171
+
</simpara>
1172
+
</listitem>
1173
+
<listitem>
1174
+
<simpara>
1175
+
Before dbase 7.0.0, booleans (<literal>L</literal>) were converted to <literal>1</literal> or
1176
+
<literal>0</literal>.
1177
+
</simpara>
1178
+
</listitem>
1179
+
</itemizedlist>
1180
+
</para>'>
1181
+
1182
+
<!-- enchant entities -->
1183
+
1184
+
<!ENTITY enchant.param.broker '<varlistentry xmlns="http://docbook.org/ns/docbook">
1185
+
<term><parameter>broker</parameter></term>
1186
+
<listitem>
1187
+
<para>
1188
+
An Enchant broker returned by <function>enchant_broker_init</function>.
1189
+
</para>
1190
+
</listitem>
1191
+
</varlistentry>'>
1192
+
1193
+
<!ENTITY enchant.param.dictionary '<varlistentry xmlns="http://docbook.org/ns/docbook">
1194
+
<term><parameter>dictionary</parameter></term>
1195
+
<listitem>
1196
+
<para>
1197
+
An Enchant dictionary returned by <function>enchant_broker_request_dict</function>
1198
+
or <function>enchant_broker_request_pwl_dict</function>.
1199
+
</para>
1200
+
</listitem>
1201
+
</varlistentry>'>
1202
+
1203
+
<!ENTITY enchant.changelog.broker-param '<row xmlns="http://docbook.org/ns/docbook">
1204
+
<entry>8.0.0</entry>
1205
+
<entry>
1206
+
<parameter>broker</parameter> expects an <classname>EnchantBroker</classname> instance now;
1207
+
previoulsy, a &resource; was expected.
1208
+
</entry>
1209
+
</row>'>
1210
+
1211
+
<!ENTITY enchant.changelog.dictionary-param '<row xmlns="http://docbook.org/ns/docbook">
1212
+
<entry>8.0.0</entry>
1213
+
<entry>
1214
+
<parameter>dictionary</parameter> expects an <classname>EnchantDictionary</classname> instance now;
1215
+
previoulsy, a &resource; was expected.
1216
+
</entry>
1217
+
</row>'>
1218
+
498
1219
<!-- IMAP notes -->
499
1220
500
-
<!ENTITY imap.imap-stream.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
501
-
imap_stream</parameter></term><listitem><para>An IMAP stream returned by
1221
+
<!ENTITY imap.changelog.imap-param '<row xmlns="http://docbook.org/ns/docbook">
1222
+
<entry>8.1.0</entry>
1223
+
<entry>
1224
+
The <parameter>imap</parameter> parameter expects an <classname>IMAP\Connection</classname>
1225
+
instance now; previously, a valid <literal>imap</literal> &resource; was expected.
1226
+
</entry>
1227
+
</row>'>
1228
+
1229
+
<!ENTITY imap.imap-parameter.imap '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1230
+
<parameter>imap</parameter></term><listitem><para>An <classname>IMAP\Connection</classname> instance.</para></listitem></varlistentry>'>
1231
+
1232
+
<!-- Deprecated -->
1233
+
<!ENTITY imap.imap-stream.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1234
+
<parameter>imap</parameter></term><listitem><para>An IMAP stream returned by
502
1235
<function>imap_open</function>.</para></listitem></varlistentry>'>
503
1236
504
1237
<!ENTITY imap.pattern '<para xmlns="http://docbook.org/ns/docbook">Specifies where in the mailbox hierarchy
...
...
@@ -514,6 +1247,102 @@ means to return the current level only.
514
1247
parameter will return only the top level
515
1248
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>'>
516
1249
1250
+
<!ENTITY imap.mailboxname.insecure '<warning xmlns="http://docbook.org/ns/docbook"><simpara>
1251
+
Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unless
1252
+
<link linkend="ini.imap.enable-insecure-rsh">imap.enable_insecure_rsh</link> is disabled.
1253
+
</simpara></warning>'>
1254
+
1255
+
<!-- intl notes -->
1256
+
1257
+
<!ENTITY intl.parameter.intl-calendar '<para xmlns="http://docbook.org/ns/docbook">An <classname>IntlCalendar</classname> instance.</para>'>
1258
+
1259
+
<!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>'>
1260
+
1261
+
<!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>'>
1262
+
1263
+
<!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>'>
1264
+
1265
+
<!ENTITY intl.codepoint.example 'Testing different code points'>
1266
+
1267
+
<!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>'>
1268
+
1269
+
<!ENTITY intl.property.parameter '<para xmlns="http://docbook.org/ns/docbook">The Unicode property to lookup (see the <literal>IntlChar::PROPERTY_*</literal> constants).</para>'>
1270
+
1271
+
<!ENTITY intl.property.example 'Testing different properties'>
1272
+
1273
+
<!-- LDAP notes -->
1274
+
1275
+
<!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>.'>
1276
+
1277
+
<!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>.'>
1278
+
1279
+
<!ENTITY ldap.parameter.entry 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\ResultEntry</classname> instance.'>
1280
+
1281
+
<!ENTITY ldap.warn.control-paged '<warning xmlns="http://docbook.org/ns/docbook">
1282
+
<simpara>
1283
+
This function has been <emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.
1284
+
Instead the <parameter>controls</parameter> parameter of <function>ldap_search</function> should be used.
1285
+
See also <link linkend="ldap.controls">LDAP Controls</link> for details.
1286
+
</simpara>
1287
+
</warning>'>
1288
+
1289
+
<!ENTITY ldap.changelog.controls-nullable '<row xmlns="http://docbook.org/ns/docbook">
1290
+
<entry>8.0.0</entry>
1291
+
<entry>
1292
+
<parameter>controls</parameter> is nullable now; previously, it defaulted to <literal>[]</literal>.
1293
+
</entry>
1294
+
</row>'>
1295
+
1296
+
<!ENTITY ldap.changelog.ldap-object '<row xmlns="http://docbook.org/ns/docbook">
1297
+
<entry>8.1.0</entry>
1298
+
<entry>
1299
+
The <parameter>ldap</parameter> parameter expects an <classname>LDAP\Connection</classname>
1300
+
instance now; previously, a valid <literal>ldap link</literal> &resource; was expected.
1301
+
</entry>
1302
+
</row>'>
1303
+
1304
+
<!ENTITY ldap.changelog.entry-object '<row xmlns="http://docbook.org/ns/docbook">
1305
+
<entry>8.1.0</entry>
1306
+
<entry>
1307
+
The <parameter>entry</parameter> parameter expects an <classname>LDAP\ResultEntry</classname>
1308
+
instance now; previously, a valid <literal>ldap result entry</literal> &resource; was expected.
1309
+
</entry>
1310
+
</row>'>
1311
+
1312
+
<!ENTITY ldap.changelog.result-object '<row xmlns="http://docbook.org/ns/docbook">
1313
+
<entry>8.1.0</entry>
1314
+
<entry>
1315
+
The <parameter>result</parameter> parameter expects an <classname>LDAP\Result</classname>
1316
+
instance now; previously, a valid <literal>ldap result</literal> &resource; was expected.
1317
+
</entry>
1318
+
</row>'>
1319
+
1320
+
<!ENTITY ldap.changelog.return-result-object '<row xmlns="http://docbook.org/ns/docbook">
1321
+
<entry>8.1.0</entry>
1322
+
<entry>
1323
+
Returns an <classname>LDAP\Result</classname> instance now;
1324
+
previously, a &resource; was returned.
1325
+
</entry>
1326
+
</row>'>
1327
+
1328
+
<!ENTITY ldap.changelog.return-result-entry-object '<row xmlns="http://docbook.org/ns/docbook">
1329
+
<entry>8.1.0</entry>
1330
+
<entry>
1331
+
Returns an <classname>LDAP\ResultEntry</classname> instance now;
1332
+
previously, a &resource; was returned.
1333
+
</entry>
1334
+
</row>'>
1335
+
1336
+
<!ENTITY ldap.return-result 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance,&return.falseforfailure;.'>
1337
+
<!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;.'>
1338
+
1339
+
<!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
1340
+
<classname>LDAP\Connection</classname> instances, rather than a single one.
1341
+
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.
1342
+
These arrays must be of the same size as the <classname>LDAP\Connection</classname> instances array,
1343
+
since the first entries of the arrays are used for one search, the second entries are used for another, and so on.
1344
+
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>'>
1345
+
517
1346
<!-- mbstring notes -->
518
1347
519
1348
<!ENTITY note.mbstring.encoding.internal '<note xmlns="http://docbook.org/ns/docbook"><para>The internal encoding or the
...
...
@@ -525,11 +1354,25 @@ character encoding specified by <function>mb_regex_encoding</function>
525
1354
will be used as the character encoding for this function by default.</para></note>'>
526
1355
527
1356
<!ENTITY mbstring.encoding.parameter '<para xmlns="http://docbook.org/ns/docbook">The <parameter>encoding</parameter>
528
-
parameter is the character encoding. If it is omitted, the internal character
1357
+
parameter is the character encoding. If it is omitted or &null;, the internal character
529
1358
encoding value will be used.</para>'>
530
1359
531
1360
<!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>'>
532
1361
1362
+
<!ENTITY mbstring.changelog.encoding-nullable '<row xmlns="http://docbook.org/ns/docbook">
1363
+
<entry>8.0.0</entry>
1364
+
<entry>
1365
+
<parameter>encoding</parameter> is nullable now.
1366
+
</entry>
1367
+
</row>'>
1368
+
1369
+
<!ENTITY mbstring.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
1370
+
<entry>8.0.0</entry>
1371
+
<entry>
1372
+
<parameter>needle</parameter> now accepts an empty string.
1373
+
</entry>
1374
+
</row>'>
1375
+
533
1376
<!-- mcrypt notes -->
534
1377
535
1378
<!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>'>
...
...
@@ -542,12 +1385,20 @@ encoding value will be used.</para>'>
542
1385
543
1386
<!-- MCVE notes -->
544
1387
545
-
<!ENTITY mcve.conn.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
546
-
conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
1388
+
<!ENTITY mcve.conn.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1389
+
<parameter>conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
547
1390
<function>m_initengine</function>.</para></listitem></varlistentry>'>
548
1391
549
1392
<!-- memcached notes -->
550
1393
1394
+
<!ENTITY memcached.note.delete-time '<note xmlns="http://docbook.org/ns/docbook"><simpara>
1395
+
As of memcached 1.3.0 (released 2009) this feature is no longer
1396
+
supported. Passing a non-zero <parameter>time</parameter> will cause
1397
+
the deletion to fail. <methodname>Memcached::getResultCode</methodname>
1398
+
will return <constant>MEMCACHED_INVALID_ARGUMENTS</constant>.
1399
+
</simpara></note>
1400
+
'>
1401
+
551
1402
<!ENTITY memcached.parameter.expiration 'The expiration time, defaults to 0. See <link
552
1403
linkend="memcached.expiration" xmlns="http://docbook.org/ns/docbook">Expiration Times</link> for more info.'>
553
1404
...
...
@@ -561,6 +1412,19 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
561
1412
562
1413
<!ENTITY memcached.result.getresultcode 'Use <methodname xmlns="http://docbook.org/ns/docbook">Memcached::getResultCode</methodname> if necessary.'>
563
1414
1415
+
<!ENTITY memcached.result.delete-multi '<para xmlns="http://docbook.org/ns/docbook">
1416
+
Returns an array indexed by <parameter>keys</parameter>. Each element
1417
+
is &true; if the corresponding key was deleted, or one of the
1418
+
<constant>Memcached::RES_<replaceable>*</replaceable></constant> constants if the corresponding deletion
1419
+
failed.
1420
+
</para>
1421
+
<para xmlns="http://docbook.org/ns/docbook">
1422
+
The <methodname>Memcached::getResultCode</methodname> will return
1423
+
the result code for the last executed delete operation, that is, the delete
1424
+
operation for the last element of <parameter>keys</parameter>.
1425
+
</para>
1426
+
'>
1427
+
564
1428
<!-- password notes -->
565
1429
566
1430
<!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.'>
...
...
@@ -571,6 +1435,54 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
571
1435
572
1436
<!ENTITY password.parameter.password 'The user's password.'>
573
1437
1438
+
<!-- pspell notes -->
1439
+
1440
+
<!ENTITY pspell.changelog.pspell-dictionary '<row xmlns="http://docbook.org/ns/docbook">
1441
+
<entry>8.1.0</entry>
1442
+
<entry>
1443
+
The <parameter>dictionary</parameter> parameter expects an <classname>PSpell\Dictionary</classname>
1444
+
instance now; previously, a &resource; was expected.
1445
+
</entry>
1446
+
</row>'>
1447
+
1448
+
<!ENTITY pspell.changelog.pspell-config '<row xmlns="http://docbook.org/ns/docbook">
1449
+
<entry>8.1.0</entry>
1450
+
<entry>
1451
+
The <parameter>config</parameter> parameter expects an <classname>PSpell\Config</classname>
1452
+
instance now; previously, a &resource; was expected.
1453
+
</entry>
1454
+
</row>'>
1455
+
1456
+
<!ENTITY pspell.parameter.pspell-dictionary '<para xmlns="http://docbook.org/ns/docbook">An <classname>PSpell\Dictionary</classname> instance.</para>'>
1457
+
1458
+
<!ENTITY pspell.parameter.pspell-config '<para xmlns="http://docbook.org/ns/docbook">An <classname>PSpell\Config</classname> instance.</para>'>
1459
+
1460
+
<!-- RNP -->
1461
+
1462
+
<!ENTITY rnp.parameter.ffi-description 'The FFI object returned by <function xmlns="http://docbook.org/ns/docbook">rnp_ffi_create</function>.'>
1463
+
1464
+
<!ENTITY rnp.parameter.key-format 'The key format of the data (GPG, KBX, G10).'>
1465
+
1466
+
<!ENTITY rnp.parameter.loadsave-flags 'See <constant xmlns="http://docbook.org/ns/docbook">RNP_LOAD_SAVE_<replaceable>*</replaceable></constant> flags description.'>
1467
+
1468
+
<!-- socket entities -->
1469
+
1470
+
<!ENTITY sockets.changelog.socket-param '<row xmlns="http://docbook.org/ns/docbook">
1471
+
<entry>8.0.0</entry>
1472
+
<entry>
1473
+
<parameter>socket</parameter> is a <classname>Socket</classname> instance now;
1474
+
previously, it was a <type>resource</type>.
1475
+
</entry>
1476
+
</row>'>
1477
+
1478
+
<!ENTITY sockets.changelog.address-param '<row xmlns="http://docbook.org/ns/docbook">
1479
+
<entry>8.0.0</entry>
1480
+
<entry>
1481
+
<parameter>address</parameter> is an <classname>AddressInfo</classname> instance now;
1482
+
previously, it was a <type>resource</type>.
1483
+
</entry>
1484
+
</row>'>
1485
+
574
1486
<!-- geaman notes -->
575
1487
576
1488
<!ENTITY gearman.parameter.host 'The job server host name.'>
...
...
@@ -589,18 +1501,63 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
589
1501
590
1502
<!ENTITY gearman.parameter.jobhandle 'The job handle assigned by the Gearman server'>
591
1503
1504
+
<!ENTITY gearman.parameter.callback '<varlistentry xmlns="http://docbook.org/ns/docbook">
1505
+
<term><parameter>callback</parameter></term>
1506
+
<listitem>
1507
+
<para>
1508
+
A function or method to call.
1509
+
It should return a valid <link linkend="gearman.constants">Gearman return value</link>.
1510
+
</para>
1511
+
<para>
1512
+
If no return statement is present, it defaults to <constant>GEARMAN_SUCCESS</constant>.
1513
+
</para>
1514
+
<methodsynopsis>
1515
+
<type>int</type><methodname><replaceable>callback</replaceable></methodname>
1516
+
<methodparam><type>GearmanTask</type><parameter>task</parameter></methodparam>
1517
+
<methodparam><type>mixed</type><parameter>context</parameter></methodparam>
1518
+
</methodsynopsis>
1519
+
<variablelist>
1520
+
<varlistentry>
1521
+
<term><parameter>task</parameter></term>
1522
+
<listitem>
1523
+
<para>
1524
+
The task this callback is called for.
1525
+
</para>
1526
+
</listitem>
1527
+
</varlistentry>
1528
+
<varlistentry>
1529
+
<term><parameter>context</parameter></term>
1530
+
<listitem>
1531
+
<para>
1532
+
Whatever has been passed to <methodname>GearmanClient::addTask</methodname> (or equivalent method) as <parameter>context</parameter>.
1533
+
</para>
1534
+
</listitem>
1535
+
</varlistentry>
1536
+
</variablelist>
1537
+
</listitem>
1538
+
</varlistentry>'>
1539
+
1540
+
<!ENTITY gearman.note.callback '<note xmlns="http://docbook.org/ns/docbook">
1541
+
<para>
1542
+
The callback will only be triggered for tasks that are added (e.g. by calling <methodname>GearmanClient::addTask</methodname>)
1543
+
after calling this method.
1544
+
</para>
1545
+
</note>'>
1546
+
592
1547
<!-- Date and time entities -->
593
1548
<!ENTITY date.timezone.intro.title '<title xmlns="http://docbook.org/ns/docbook">List of Supported Timezones</title>'>
594
1549
595
1550
<!ENTITY date.timezone.intro "<para xmlns='http://docbook.org/ns/docbook'>
596
1551
Here you'll find the complete list of timezones supported by PHP, which are
597
1552
meant to be used with e.g. <function>date_default_timezone_set</function>.
1553
+
<caution><simpara>The behavior of timezones not listed here is undefined.</simpara></caution>
598
1554
</para><note xmlns='http://docbook.org/ns/docbook'><simpara>The latest version of the timezone database can be
599
1555
installed via PECL's <link xlink:href='&url.pecl.package.get;timezonedb' xmlns:xlink='http://www.w3.org/1999/xlink'>timezonedb</link>.
600
1556
</simpara></note>">
601
1557
602
1558
<!ENTITY date.timezone.bc '<simpara xmlns="http://docbook.org/ns/docbook">Please do not use any of the timezones
603
-
listed here (besides UTC), they only exist for backward compatible reasons.
1559
+
listed here (besides UTC), they only exist for backward compatible reasons, and may expose erroneous behavior.
1560
+
Furthermore, these timezones may be removed from the IANA timezone database at any time.
604
1561
</simpara>'>
605
1562
606
1563
<!ENTITY date.timezone.posix-signs '<simpara xmlns="http://docbook.org/ns/docbook">
...
...
@@ -621,12 +1578,15 @@ listed here (besides UTC), they only exist for backward compatible reasons.
621
1578
<literal>Australia/Perth</literal> for the above examples.
622
1579
</simpara>'>
623
1580
1581
+
<!ENTITY date.timezone.abbrev-volatile '<simpara xmlns="http://docbook.org/ns/docbook">
1582
+
These timezone abbreviations have to be regarded as highly volatile, i.e. they
1583
+
might be different for each timezonedb release, and should not be relied upon.
1584
+
It is strongly recommended to avoid timezone abbreviations.
1585
+
</simpara>'>
1586
+
624
1587
<!ENTITY date.timezone.errors.description '<para xmlns="http://docbook.org/ns/docbook">
625
-
Every call to a date/time function will generate a <constant>E_NOTICE</constant>
626
-
if the time zone is not valid, and/or a <constant>E_STRICT</constant>
627
-
or <constant>E_WARNING</constant> message
628
-
if using the system settings or the <varname>TZ</varname> environment
629
-
variable. See also <function>date_default_timezone_set</function></para>'>
1588
+
Every call to a date/time function will generate a <constant>E_WARNING</constant>
1589
+
if the time zone is not valid. See also <function>date_default_timezone_set</function></para>'>
630
1590
631
1591
<!ENTITY date.timezone.errors.changelog '<row xmlns="http://docbook.org/ns/docbook"><entry>5.1.0</entry><entry><para>
632
1592
Now issues the <constant>E_STRICT</constant> and <constant>E_NOTICE</constant>
...
...
@@ -635,8 +1595,8 @@ time zone errors.</para></entry></row>'>
635
1595
<!ENTITY date.timestamp.description '
636
1596
<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>timestamp</parameter></term><listitem><para>
637
1597
The optional <parameter>timestamp</parameter> parameter is an
638
-
<type>integer</type> Unix timestamp that defaults to the current
639
-
local time if a <parameter>timestamp</parameter> is not given. In other
1598
+
<type>int</type> Unix timestamp that defaults to the current
1599
+
local time if <parameter>timestamp</parameter> is omitted or &null;. In other
640
1600
words, it defaults to the value of <function>time</function>.
641
1601
</para></listitem></varlistentry>'>
642
1602
...
...
@@ -649,14 +1609,14 @@ returned by <function>date_create</function></para></listitem></varlistentry>'>
649
1609
returned by <function>date_create</function>.
650
1610
The function modifies this object.</para></listitem></varlistentry>'>
651
1611
652
-
<!ENTITY date.datetimezone.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
653
-
object</parameter></term><listitem><para>Procedural style only: A <classname>DateTimeZone</classname> object
1612
+
<!ENTITY date.datetimezone.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1613
+
<parameter>object</parameter></term><listitem><para>Procedural style only: A <classname>DateTimeZone</classname> object
654
1614
returned by <function>timezone_open</function></para></listitem></varlistentry>'>
655
1615
656
-
<!ENTITY date.datetime.retval.changelog '<row xmlns="http://docbook.org/ns/docbook"><entry>5.3.0</entry><entry>Changed the
657
-
return value on success from &null; to <classname>DateTime</classname>.</entry></row>'>
658
-
659
-
<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining&return.falseforfailure;.'>
1616
+
<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the modified <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining&return.falseforfailure;.'>
1617
+
<!ENTITY date.datetime.return.modifiedobject 'Returns the modified <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining.'>
1618
+
<!ENTITY date.datetimeimmutable.return.modifiedobjectorfalseforfailure 'Returns a new <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object with the modified data &return.falseforfailure;.'>
1619
+
<!ENTITY date.datetimeimmutable.return.modifiedobject 'Returns a new <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object with the modified data.'>
660
1620
661
1621
<!ENTITY date.timezone.dbversion 'This list is based upon the timezone database version'>
662
1622
...
...
@@ -671,21 +1631,75 @@ return value on success from &null; to <classname>DateTime</classname>.</entry><
671
1631
<!ENTITY date.timezone.indian 'Indian'>
672
1632
<!ENTITY date.timezone.pacific 'Pacific'>
673
1633
<!ENTITY date.timezone.others 'Others'>
1634
+
<!ENTITY date.timezone.abbreviations 'Abbreviations'>
674
1635
675
1636
<!ENTITY date.formats 'Valid formats are explained in <link xmlns="http://docbook.org/ns/docbook" linkend="datetime.formats">Date and Time Formats</link>.'>
676
1637
<!ENTITY date.formats.parameter 'A date/time string. &date.formats;'>
677
1638
678
-
<!-- DomXml Notes -->
679
-
<!ENTITY node.inserted 'This node will not show up in the document unless it
680
-
is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">domnode_append_child</function>.'>
681
-
682
-
683
1639
<!-- Dom Notes -->
684
1640
<!ENTITY dom.node.inserted 'This node will not show up in the document unless
685
1641
it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNode::appendChild</function>.'>
686
1642
687
-
<!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>'>
688
1643
<!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>'>
1644
+
<!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>'>
1645
+
<!ENTITY dom.note.modern.utf8 '<note xmlns="http://docbook.org/ns/docbook">
1646
+
<simpara>
1647
+
The DOM extension uses UTF-8 encoding when working with methods or properties.
1648
+
The parser methods auto-detect the encoding or allow the caller to specify an encoding.
1649
+
</simpara>
1650
+
</note>'>
1651
+
<!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>'>
1652
+
<!ENTITY dom.domdocument.html5 '<warning xmlns="http://docbook.org/ns/docbook">
1653
+
<simpara>
1654
+
Use <classname>Dom\HTMLDocument</classname> to parse and process modern HTML
1655
+
instead of <classname>DOMDocument</classname>.
1656
+
</simpara>
1657
+
<simpara>
1658
+
This function parses the input using an HTML 4 parser. The parsing rules
1659
+
of HTML 5, which is what modern web browsers use, are different. Depending
1660
+
on the input this might result in a different DOM structure. Therefore
1661
+
this function cannot be safely used for sanitizing HTML.
1662
+
</simpara>
1663
+
<simpara>
1664
+
The behavior when parsing HTML can depend on the version of
1665
+
<literal>libxml</literal> that is being used, particularly with regards to
1666
+
edge conditions and error handling.
1667
+
For parsing that conforms to the HTML5 specification,
1668
+
use <methodname>Dom\HTMLDocument::createFromString</methodname> or
1669
+
<methodname>Dom\HTMLDocument::createFromFile</methodname>, added in PHP 8.4.
1670
+
</simpara>
1671
+
<simpara>
1672
+
As an example, some HTML elements will implicitly close a parent element
1673
+
when encountered. The rules for automatically closing parent elements
1674
+
differ between HTML 4 and HTML 5 and thus the resulting DOM structure that
1675
+
<classname>DOMDocument</classname> sees might be different from the DOM
1676
+
structure a web browser sees, possibly allowing an attacker to break the
1677
+
resulting HTML.
1678
+
</simpara>
1679
+
</warning>'>
1680
+
<!ENTITY dom.tokenlist.errors '<itemizedlist xmlns="http://docbook.org/ns/docbook">
1681
+
<listitem>
1682
+
<simpara>
1683
+
Throws a <exceptionname>ValueError</exceptionname> if
1684
+
a token contains any null bytes.
1685
+
</simpara>
1686
+
</listitem>
1687
+
<listitem>
1688
+
<simpara>
1689
+
Throws a <exceptionname>Dom\DOMException</exceptionname> with code
1690
+
<constant>Dom\SYNTAX_ERR</constant> if a token is the empty string.
1691
+
</simpara>
1692
+
</listitem>
1693
+
<listitem>
1694
+
<simpara>
1695
+
Throws a <exceptionname>Dom\DOMException</exceptionname> with code
1696
+
<constant>Dom\INVALID_CHARACTER_ERR</constant> if a token contains any
1697
+
ASCII whitespace.
1698
+
</simpara>
1699
+
</listitem>
1700
+
</itemizedlist>'>
1701
+
1702
+
689
1703
690
1704
<!-- Dom Examples -->
691
1705
<!ENTITY dom.book.example '<para xmlns="http://docbook.org/ns/docbook">The following examples use <filename>book.xml</filename> which contains the following:</para>
...
...
@@ -721,6 +1735,128 @@ it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNo
721
1735
</books>
722
1736
]]></programlisting>'>
723
1737
1738
+
<!-- Dom entities -->
1739
+
<!ENTITY dom.parameter.options '<para xmlns="http://docbook.org/ns/docbook">
1740
+
<link linkend="language.operators.bitwise">Bitwise <literal>OR</literal></link>
1741
+
of the <link linkend="libxml.constants">libxml option constants</link>.
1742
+
</para>'>
1743
+
1744
+
<!ENTITY dom.parameter.compliant.options '&dom.parameter.options;
1745
+
<simpara xmlns="http://docbook.org/ns/docbook">
1746
+
It is also possible to pass <constant>Dom\HTML_NO_DEFAULT_NS</constant>
1747
+
to disable the use of the HTML namespace and the template element.
1748
+
This should only be used if the implications are properly understood.
1749
+
</simpara>'>
1750
+
1751
+
<!ENTITY dom.parameter.compliant.encoding '<simpara xmlns="http://docbook.org/ns/docbook">
1752
+
The encoding that the document was created in.
1753
+
If not provided, it will attempt to determine the encoding that is most likely used.
1754
+
</simpara>'>
1755
+
1756
+
<!ENTITY dom.parser.compliant.note.whitespace '<refsect1 role="notes" xmlns="http://docbook.org/ns/docbook">
1757
+
&reftitle.notes;
1758
+
<note>
1759
+
<simpara>
1760
+
Whitespace in the <literal>html</literal> and <literal>head</literal> tags
1761
+
is not considered significant and may lose formatting.
1762
+
</simpara>
1763
+
</note>
1764
+
</refsect1>'>
1765
+
1766
+
<!ENTITY dom.parameters.register_node_ns '<varlistentry xmlns="http://docbook.org/ns/docbook">
1767
+
<term><parameter>registerNodeNS</parameter></term>
1768
+
<listitem>
1769
+
<para>
1770
+
Whether to automatically register the in-scope namespace prefixes of the context node to the <classname>DOMXPath</classname> object.
1771
+
This can be used to avoid needing to call <methodname>DOMXPath::registerNamespace</methodname> manually for each in-scope namespaces.
1772
+
When a namespace prefix conflict exists, only the nearest descendant namespace prefix is registered.
1773
+
</para>
1774
+
</listitem>
1775
+
</varlistentry>'>
1776
+
1777
+
<!ENTITY dom.parameters.serialize.options '<simpara xmlns="http://docbook.org/ns/docbook">
1778
+
Additional Options.
1779
+
The <constant>LIBXML_NOEMPTYTAG</constant>
1780
+
and <constant>LIBXML_NOXMLDECL</constant> options are supported.
1781
+
Prior to PHP 8.3.0, only the <constant>LIBXML_NOEMPTYTAG</constant>
1782
+
option is supported.
1783
+
</simpara>'>
1784
+
1785
+
<!ENTITY dom.errors.hierarchy.parent '<varlistentry xmlns="http://docbook.org/ns/docbook">
1786
+
<term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
1787
+
<listitem>
1788
+
<para>
1789
+
Raised if the parent is of a type that does not allow children of the
1790
+
type of one of the passed <parameter>nodes</parameter>, or if the node to
1791
+
put in is one of this node's ancestors or this node itself.
1792
+
</para>
1793
+
</listitem>
1794
+
</varlistentry>'>
1795
+
1796
+
<!ENTITY dom.errors.hierarchy.self '<varlistentry xmlns="http://docbook.org/ns/docbook">
1797
+
<term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
1798
+
<listitem>
1799
+
<para>
1800
+
Raised if this node is of a type that does not allow children of the
1801
+
type of one of the passed <parameter>nodes</parameter>, or if the node to
1802
+
put in is one of this node's ancestors or this node itself.
1803
+
</para>
1804
+
</listitem>
1805
+
</varlistentry>'>
1806
+
1807
+
<!ENTITY dom.errors.wrong_document '<varlistentry xmlns="http://docbook.org/ns/docbook">
1808
+
<term><constant>DOM_WRONG_DOCUMENT_ERR</constant></term>
1809
+
<listitem>
1810
+
<para>
1811
+
Raised if one of the passed <parameter>nodes</parameter> was created from a different
1812
+
document than the one that created this node.
1813
+
</para>
1814
+
</listitem>
1815
+
</varlistentry>'>
1816
+
1817
+
<!ENTITY dom.errors.compliant.wrong_document '<listitem xmlns="http://docbook.org/ns/docbook">
1818
+
<simpara>
1819
+
Throws a <exceptionname>Dom\DOMException</exceptionname> with code
1820
+
<constant>Dom\WRONG_DOCUMENT_ERR</constant> if <parameter>node</parameter>
1821
+
is from another document.
1822
+
</simpara>
1823
+
</listitem>'>
1824
+
1825
+
<!ENTITY dom.errors.compliant.common '<listitem xmlns="http://docbook.org/ns/docbook">
1826
+
<simpara>
1827
+
Throws a <exceptionname>ValueError</exceptionname> if
1828
+
<parameter>options</parameter> contains an invalid option.
1829
+
</simpara>
1830
+
</listitem>
1831
+
<listitem>
1832
+
<simpara>
1833
+
Throws a <exceptionname>ValueError</exceptionname> if
1834
+
<parameter>overrideEncoding</parameter> is an unknown encoding.
1835
+
</simpara>
1836
+
</listitem>'>
1837
+
1838
+
<!ENTITY dom.changelog.previous_hierarchy_exception 'Previously this threw a
1839
+
<classname xmlns="http://docbook.org/ns/docbook">DOMException</classname> with code
1840
+
<constant xmlns="http://docbook.org/ns/docbook">DOM_HIERARCHY_REQUEST_ERR</constant>.'>
1841
+
1842
+
<!ENTITY dom.c14n.xpath_array '<listitem xmlns="http://docbook.org/ns/docbook">
1843
+
<para>
1844
+
An array of XPaths to filter the nodes by.
1845
+
Each entry in this array is an associative array with:
1846
+
<itemizedlist>
1847
+
<listitem>
1848
+
<simpara>
1849
+
A required <literal>query</literal> key containing the XPath expression as a string.
1850
+
</simpara>
1851
+
</listitem>
1852
+
<listitem>
1853
+
<simpara>
1854
+
An optional <literal>namespaces</literal> key containing an array that maps namespace prefixes (keys) to namespace URIs (values).
1855
+
</simpara>
1856
+
</listitem>
1857
+
</itemizedlist>
1858
+
</para>
1859
+
</listitem>'>
724
1860
725
1861
<!-- FileSystem entities -->
726
1862
<!ENTITY fs.emits.warning.on.failure '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -741,6 +1877,15 @@ that is typically created using <function>fopen</function>.</para>'>
741
1877
are larger than 2GB.
742
1878
</simpara></note>'>
743
1879
1880
+
<!ENTITY ini.scanner.typed '<para xmlns="http://docbook.org/ns/docbook">
1881
+
As of PHP 5.6.1 can also be specified as <constant>INI_SCANNER_TYPED</constant>.
1882
+
In this mode boolean, null and integer types are preserved when possible.
1883
+
String values <literal>"true"</literal>, <literal>"on"</literal> and <literal>"yes"</literal>
1884
+
are converted to &true;. <literal>"false"</literal>, <literal>"off"</literal>, <literal>"no"</literal>
1885
+
and <literal>"none"</literal> are considered &false;. <literal>"null"</literal> is converted to &null;
1886
+
in typed mode. Also, all numeric strings are converted to integer type if it is possible.
1887
+
</para>'>
1888
+
744
1889
<!-- GNUPG -->
745
1890
<!ENTITY gnupg.identifier '<para xmlns="http://docbook.org/ns/docbook">The gnupg identifier, from a call to
746
1891
<function>gnupg_init</function> or <classname>gnupg</classname>.</para>'>
...
...
@@ -751,11 +1896,84 @@ that is typically created using <function>fopen</function>.</para>'>
751
1896
<!ENTITY haru.error '<para xmlns="http://docbook.org/ns/docbook">Throws a <classname>HaruException</classname> on error.</para>'>
752
1897
753
1898
<!-- ODBC -->
754
-
<!ENTITY odbc.connection.id '<para xmlns="http://docbook.org/ns/docbook">The ODBC connection identifier,
1899
+
<!ENTITY odbc.connection.id '<para xmlns="http://docbook.org/ns/docbook">The ODBC connection object,
755
1900
see <function>odbc_connect</function> for details.</para>'>
756
1901
1902
+
<!ENTITY odbc.result.object 'The ODBC result object'>
1903
+
1904
+
<!ENTITY odbc.result.object-return 'Returns an ODBC result object'>
1905
+
1906
+
<!ENTITY odbc.result.object-return-falseforfailure '&odbc.result.object-return;&return.falseforfailure;.'>
1907
+
1908
+
<!ENTITY odbc.parameter.catalog 'The catalog ('qualifier' in ODBC 2 parlance).'>
1909
+
1910
+
<!ENTITY odbc.parameter.schema 'The schema ('owner' in ODBC 2 parlance).'>
1911
+
757
1912
<!ENTITY odbc.parameter.search 'This parameter accepts the following search patterns:
758
-
"%" to match zero or more characters, and "_" to match a single character.'>
1913
+
<literal xmlns="http://docbook.org/ns/docbook">%</literal> to match zero or more characters,
1914
+
and <literal xmlns="http://docbook.org/ns/docbook">_</literal> to match a single character.'>
1915
+
1916
+
<!ENTITY odbc.result.driver-specific 'Drivers can report additional columns.'>
1917
+
1918
+
<!ENTITY odbc.changelog.connection-param '<row xmlns="http://docbook.org/ns/docbook">
1919
+
<entry>8.4.0</entry>
1920
+
<entry>
1921
+
<parameter>odbc</parameter> expects an <classname>Odbc\Connection</classname>
1922
+
instance now; previously, a <type>resource</type> was expected.
1923
+
</entry>
1924
+
</row>'>
1925
+
1926
+
<!ENTITY odbc.changelog.connection-return '&odbc.changelog.connection-param;
1927
+
<row xmlns="http://docbook.org/ns/docbook">
1928
+
<entry>8.4.0</entry>
1929
+
<entry>
1930
+
This function returns a <classname>Odbc\Connection</classname> instance now;
1931
+
previously, a <type>resource</type> was returned.
1932
+
</entry>
1933
+
</row>'>
1934
+
1935
+
<!ENTITY odbc.changelog.credential-params '<row xmlns="http://docbook.org/ns/docbook">
1936
+
<entry>8.4.0</entry>
1937
+
<entry>
1938
+
<parameter>user</parameter> and <parameter>password</parameter> are now nullable,
1939
+
they are now also optional and default to &null;.
1940
+
</entry>
1941
+
</row>
1942
+
<row xmlns="http://docbook.org/ns/docbook">
1943
+
<entry>8.4.0</entry>
1944
+
<entry>
1945
+
Previously, using an empty string for <parameter>password</parameter> would not include
1946
+
<literal>pwd</literal> in the generated connection string for <parameter>dsn</parameter>.
1947
+
It is now generated to include a <literal>pwd</literal> which has an empty string as its value.
1948
+
To restore the previous behaviour <parameter>password</parameter> can now be set to &null;.
1949
+
</entry>
1950
+
</row>
1951
+
<row xmlns="http://docbook.org/ns/docbook">
1952
+
<entry>8.4.0</entry>
1953
+
<entry>
1954
+
Previously, if <parameter>dsn</parameter> contained <literal>uid</literal> or <literal>pwd</literal>
1955
+
both <parameter>user</parameter> and <parameter>password</parameter> parameters were ignored.
1956
+
Now <parameter>user</parameter> is only ignored if <parameter>dsn</parameter> contains
1957
+
<literal>uid</literal>, and <parameter>password</parameter> is only ignored if
1958
+
<parameter>dsn</parameter> contains <literal>pwd</literal>.
1959
+
</entry>
1960
+
</row>'>
1961
+
1962
+
<!ENTITY odbc.changelog.result-param '<row xmlns="http://docbook.org/ns/docbook">
1963
+
<entry>8.4.0</entry>
1964
+
<entry>
1965
+
<parameter>statement</parameter> expects an <classname>Odbc\Result</classname>
1966
+
instance now; previously, a <type>resource</type> was expected.
1967
+
</entry>
1968
+
</row>'>
1969
+
1970
+
<!ENTITY odbc.changelog.result-return '<row xmlns="http://docbook.org/ns/docbook">
1971
+
<entry>8.4.0</entry>
1972
+
<entry>
1973
+
This function returns an <classname>Odbc\Result</classname>
1974
+
instance now; previously, a <type>resource</type> was returned.
1975
+
</entry>
1976
+
</row>'>
759
1977
760
1978
<!-- OAUTH -->
761
1979
<!ENTITY oauth.callback.error 'Emits an <constant xmlns="http://docbook.org/ns/docbook">E_ERROR</constant> level
...
...
@@ -771,7 +1989,7 @@ string</link>, or a Connect Name from
771
1989
the <filename>tnsnames.ora</filename> file, or the name of a local
772
1990
Oracle instance.
773
1991
</para>
774
-
<para xmlns='http://docbook.org/ns/docbook'>If not specified, PHP uses
1992
+
<para xmlns='http://docbook.org/ns/docbook'>If not specified or &null;, PHP uses
775
1993
environment variables such as <constant>TWO_TASK</constant> (on Linux)
776
1994
or <constant>LOCAL</constant> (on Windows)
777
1995
and <constant>ORACLE_SID</constant> to determine the
...
...
@@ -784,18 +2002,18 @@ To use the Easy Connect naming method, PHP must be linked with Oracle
784
2002
<emphasis>[//]host_name[:port][/service_name]</emphasis>. From Oracle
785
2003
11<emphasis>g</emphasis>, the syntax is:
786
2004
<emphasis>[//]host_name[:port][/service_name][:server_type][/instance_name]</emphasis>.
787
-
Service names can be found by running the Oracle
788
-
utility <literal>lsnrctl status</literal> on the database server
2005
+
Further options were introduced with Oracle 19c, including timeout and keep-alive
2006
+
settings. Refer to Oracle documentation. Service names can be found by running
2007
+
the Oracle utility <literal>lsnrctl status</literal> on the database server
789
2008
machine.
790
2009
</para>
791
2010
<para xmlns='http://docbook.org/ns/docbook'>
792
-
The <filename>tnsnames.ora</filename> file can be in the Oracle Net
793
-
search path, which
794
-
includes <filename>$ORACLE_HOME/network/admin</filename>
795
-
and <filename>/etc</filename>. Alternatively
796
-
set <literal>TNS_ADMIN</literal> so
797
-
that <filename>$TNS_ADMIN/tnsnames.ora</filename> is read. Make sure
798
-
the web daemon has read access to the file.
2011
+
The <filename>tnsnames.ora</filename> file can be in the Oracle Net search path,
2012
+
which
2013
+
includes <filename>/your/path/to/instantclient/network/admin</filename>, <filename>$ORACLE_HOME/network/admin</filename>
2014
+
and <filename>/etc</filename>. Alternatively set <literal>TNS_ADMIN</literal>
2015
+
so that <filename>$TNS_ADMIN/tnsnames.ora</filename> is read. Make sure the web
2016
+
daemon has read access to the file.
799
2017
</para>">
800
2018
801
2019
<!ENTITY oci.charset "<para xmlns='http://docbook.org/ns/docbook'>Determines
...
...
@@ -860,8 +2078,8 @@ OCI8 or the Oracle Database, the client information can be set using the Oracle
860
2078
<literal>DBMS_APPLICATION_INFO</literal> package. This is less efficient than
861
2079
using <function>oci_set_client_info</function>.</para></tip>'>
862
2080
863
-
<!ENTITY oci.roundtrip.caution '<caution xmlns="http://docbook.org/ns/docbook"><title>Roundtrip Gotcha</title>
864
-
<para>Some but not all OCI8 functions cause roundtrips. Roundtrips to the
2081
+
<!ENTITY oci.roundtrip.caution '<caution xmlns="http://docbook.org/ns/docbook"><title>Round-trip Gotcha</title>
2082
+
<para>Some but not all OCI8 functions cause round-trips. Round-trips to the
865
2083
database may not occur with queries when result caching is enabled.
866
2084
</para></caution>'>
867
2085
...
...
@@ -889,67 +2107,16 @@ call to <function>pcntl_waitpid</function>.</para>'>
889
2107
is printed or viewed but it will show up if the document is converted to
890
2108
pdf by either Acrobat Distiller™ or Ghostview.</para>'>
891
2109
892
-
<!-- XSLT Notes -->
893
-
<!ENTITY note.xslt.windows '<note xmlns="http://docbook.org/ns/docbook"><para>Please note that
894
-
<literal>file://</literal> is needed in front of the path when using Windows.
895
-
</para></note>'>
896
-
897
-
<!ENTITY xslt.parameter.processor '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
898
-
processor</parameter></term><listitem><para>The <acronym>XSLT</acronym> processor
899
-
link identifier, created with <function>xslt_create</function>.</para></listitem>
900
-
</varlistentry>'>
901
-
902
-
<!ENTITY xslt.parameter.xh '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
903
-
xh</parameter></term><listitem><para>The <acronym>XSLT</acronym> processor
904
-
link identifier, created with <function>xslt_create</function>.</para></listitem>
905
-
</varlistentry>'>
906
-
907
-
908
-
<!-- Notes for safe-mode limited functions: -->
909
-
<!ENTITY note.sm.disabled '<note xmlns="http://docbook.org/ns/docbook"><simpara>&sm.disabled;</simpara></note>'>
910
-
911
-
<!ENTITY note.sm.uidcheck '<note xmlns="http://docbook.org/ns/docbook"><simpara>When <link
912
-
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether
913
-
the files or directories being operated upon have the same UID (owner) as the
914
-
script that is being executed.</simpara></note>'>
915
-
916
-
<!ENTITY note.sm.uidcheck.dir '<note xmlns="http://docbook.org/ns/docbook"><simpara>When <link
917
-
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether
918
-
the directory in which the script is operating has the same UID (owner) as the
919
-
script that is being executed.</simpara></note>'>
920
-
921
2110
<!ENTITY note.open-basedir.func '<note xmlns="http://docbook.org/ns/docbook"><para>This function is affected by <link
922
2111
linkend="ini.open-basedir">open_basedir</link>.</para></note>'>
923
2112
924
2113
925
2114
<!ENTITY note.language-construct '<note xmlns="http://docbook.org/ns/docbook"><simpara>Because this is a
926
2115
language construct and not a function, it cannot be called using
927
-
<link linkend="functions.variable-functions">variable functions</link>.</simpara>
2116
+
<link linkend="functions.variable-functions">variable functions</link>,
2117
+
or <link linkend="functions.named-arguments">named arguments</link>.</simpara>
928
2118
</note>'>
929
2119
930
-
<!-- Common pieces in features/safe-mode.xml
931
-
Jade doesn't allow in-line entities, so I put them here... Though they
932
-
should have been inline in safe-mode.xml -->
933
-
<!ENTITY sm.uidcheck 'Checks whether the files or directories being operated
934
-
upon have the same UID (owner) as the script that is being executed.'>
935
-
936
-
<!ENTITY warn.sm.exec '<warning xmlns="http://docbook.org/ns/docbook"><simpara>With <link linkend="features.safe-mode">safe mode</link> enabled,
937
-
the command string is escaped with <function>escapeshellcmd</function>. Thus,
938
-
<literal>echo y | echo x</literal> becomes <literal>echo y \| echo x</literal>.</simpara></warning>'>
939
-
940
-
<!ENTITY note.exec-path '<note xmlns="http://docbook.org/ns/docbook"><simpara>When
941
-
<link linkend="features.safe-mode">safe mode</link> is enabled, you can only
942
-
execute files within the <link linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
943
-
For practical reasons, it is currently not allowed to have <literal>..</literal>
944
-
components in the path to the executable.</simpara></note>'>
945
-
946
-
<!ENTITY sm.uidcheck.dir 'Checks whether the directory in which
947
-
the script is operating has the same UID (owner) as the script that is being
948
-
executed.'>
949
-
950
-
<!ENTITY sm.disabled 'This function is disabled when PHP is running in <link xmlns="http://docbook.org/ns/docbook"
951
-
linkend="features.safe-mode">safe mode</link>.'>
952
-
953
2120
<!-- Common pieces in partintro-sections -->
954
2121
<!ENTITY no.config '<para xmlns="http://docbook.org/ns/docbook">This extension has no configuration directives defined in &php.ini;.</para>'>
955
2122
<!ENTITY no.resource '<para xmlns="http://docbook.org/ns/docbook">This extension has no resource types defined.</para>'>
...
...
@@ -970,7 +2137,7 @@ The behaviour of these functions is affected by settings in &php.ini;.
970
2137
</simpara>'>
971
2138
972
2139
<!ENTITY ini.php.constants 'For further details and definitions of the
973
-
PHP_INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>
2140
+
INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>
974
2141
975
2142
<!-- Used in reference/$extname/constants.xml -->
976
2143
<!ENTITY extension.constants '<simpara xmlns="http://docbook.org/ns/docbook">
...
...
@@ -991,9 +2158,6 @@ will only be available when the extension has either
991
2158
been compiled into PHP or dynamically loaded at runtime.
992
2159
</simpara>'>
993
2160
994
-
<!ENTITY note.extension.php5 '<note xmlns="http://docbook.org/ns/docbook"><simpara>
995
-
This extension requires PHP 5.</simpara></note>'>
996
-
997
2161
<!-- PDO entities -->
998
2162
<!ENTITY pdo.driver-constants '<simpara xmlns="http://docbook.org/ns/docbook">The constants below are defined by
999
2163
this driver, and will only be available when the extension has been either
...
...
@@ -1001,15 +2165,26 @@ compiled into PHP or dynamically loaded at runtime. In addition, these
1001
2165
driver-specific constants should only be used if you are using this driver.
1002
2166
Using driver-specific attributes with another driver may result in
1003
2167
unexpected behaviour. <function>PDO::getAttribute</function> may be used to
1004
-
obtain the <constant>PDO_ATTR_DRIVER_NAME</constant> attribute to check the
2168
+
obtain the <constant>PDO::ATTR_DRIVER_NAME</constant> attribute to check the
1005
2169
driver, if your code can run against multiple drivers.</simpara>'>
1006
2170
2171
+
<!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>'>
2172
+
2173
+
<!-- PDO errors -->
2174
+
2175
+
<!ENTITY pdo.errors '<para xmlns="http://docbook.org/ns/docbook">
2176
+
Emits an error with level <constant>E_WARNING</constant> if the attribute <constant>PDO::ATTR_ERRMODE</constant> is set
2177
+
to <constant>PDO::ERRMODE_WARNING</constant>.
2178
+
</para>
2179
+
<para xmlns="http://docbook.org/ns/docbook">
2180
+
Throws a <classname>PDOException</classname> if the attribute <constant>PDO::ATTR_ERRMODE</constant>
2181
+
is set to <constant>PDO::ERRMODE_EXCEPTION</constant>.
2182
+
</para>'>
2183
+
1007
2184
<!-- PECL entities -->
1008
-
<!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
1009
-
is not bundled with PHP.'>
2185
+
<!ENTITY pecl.moved 'This &link.pecl; extension is not bundled with PHP.'>
1010
2186
1011
-
<!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
1012
-
is bundled with PHP.'>
2187
+
<!ENTITY pecl.bundled 'This &link.pecl; extension is bundled with PHP.'>
1013
2188
1014
2189
<!ENTITY pecl.info 'Information for installing this PECL extension may be
1015
2190
found in the manual chapter titled <link xmlns="http://docbook.org/ns/docbook" linkend="install.pecl">Installation
...
...
@@ -1021,30 +2196,95 @@ located here: '>
1021
2196
this extension is still available within <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym>
1022
2197
<acronym xmlns="http://docbook.org/ns/docbook">SVN</acronym> here: '>
1023
2198
1024
-
<!ENTITY pecl.source.4 'In PHP 4 this <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extensions
1025
-
source can be found in the <filename xmlns="http://docbook.org/ns/docbook">ext/</filename> directory within the
1026
-
PHP source or at the <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> link above.'>
1027
-
1028
-
<!ENTITY pecl.windows.4 'In PHP 4 this <acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> resides in
1029
-
the <filename xmlns="http://docbook.org/ns/docbook">extensions/</filename> directory within the PHP Windows
1030
-
binaries download.'>
2199
+
<!ENTITY pecl.info.dead.git 'This extension is considered unmaintained and dead. However, the source code for
2200
+
this extension is still available within <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym>
2201
+
<acronym xmlns="http://docbook.org/ns/docbook">GIT</acronym> here: '>
1031
2202
1032
2203
<!ENTITY pecl.windows.download 'A <acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> for this
1033
2204
<acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension is currently unavailable. See also the
1034
2205
<link xmlns="http://docbook.org/ns/docbook" linkend="install.windows.building">building on Windows</link>
1035
2206
section.'>
1036
2207
2208
+
<!ENTITY pecl.windows.download.avail 'Windows binaries (<acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> files)
2209
+
for this <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension are available from the PECL website.'>
2210
+
1037
2211
<!ENTITY pecl.windows.download.unbundled '&pecl.windows.download;'>
1038
2212
1039
-
<!ENTITY pecl.moved-ver 'This extension has been moved to the
1040
-
<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
1041
-
PHP as of PHP '>
2213
+
<!ENTITY pecl.moved-ver 'This extension has been moved to the &link.pecl;
2214
+
repository and is no longer bundled with PHP as of PHP '>
1042
2215
1043
-
<!-- kept for BC -->
1044
-
<!ENTITY note.pecl-php5 '<note xmlns="http://docbook.org/ns/docbook"><simpara>
1045
-
This extension has been removed as of PHP 5 and moved to the
1046
-
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> repository.
1047
-
</simpara></note>'>
2216
+
<!ENTITY pecl.moving.to.pie '<note xmlns="http://docbook.org/ns/docbook">
2217
+
<simpara>
2218
+
PHP Installer for Extensions (<acronym>PIE</acronym>) is a new tool that will deprecate PECL.
2219
+
We recommend using PIE to install extensions.
2220
+
Find out more at <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/php/pie">https://github.com/php/pie</link>
2221
+
</simpara>
2222
+
</note>'>
2223
+
2224
+
<!ENTITY warn.pecl.unmaintained '<warning xmlns="http://docbook.org/ns/docbook">
2225
+
<simpara>This extension is <emphasis>unmaintained</emphasis>.</simpara>
2226
+
</warning>'>
2227
+
2228
+
<!-- PGSQL entities -->
2229
+
2230
+
<!ENTITY pgsql.parameter.connection '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.</para>'>
2231
+
2232
+
<!ENTITY pgsql.parameter.connection-with-unspecified-default '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.
2233
+
When <parameter>connection</parameter> is unspecified, the default connection is used.
2234
+
The default connection is the last connection made by <function>pg_connect</function>
2235
+
or <function>pg_pconnect</function>.
2236
+
<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>
2237
+
2238
+
<!ENTITY pgsql.parameter.connection-with-nullable-default '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.
2239
+
When <parameter>connection</parameter> is &null;, the default connection is used.
2240
+
The default connection is the last connection made by <function>pg_connect</function>
2241
+
or <function>pg_pconnect</function>.
2242
+
<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>
2243
+
2244
+
<!ENTITY pgsql.parameter.result '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Result</classname> instance, returned by <function>pg_query</function>,
2245
+
<function>pg_query_params</function> or <function>pg_execute</function>(among others).</para>'>
2246
+
2247
+
<!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>'>
2248
+
2249
+
<!ENTITY pgsql.parameter.mode '<para xmlns="http://docbook.org/ns/docbook">
2250
+
An optional parameter that controls how the returned <type>array</type> is indexed.
2251
+
<parameter>mode</parameter> is a constant and can take the following values:
2252
+
<constant>PGSQL_ASSOC</constant>, <constant>PGSQL_NUM</constant> and <constant>PGSQL_BOTH</constant>.
2253
+
Using <constant>PGSQL_NUM</constant>, the function will return an array with numerical indices,
2254
+
using <constant>PGSQL_ASSOC</constant> it will return only associative indices
2255
+
while <constant>PGSQL_BOTH</constant> will return both numerical and associative indices.</para>'>
2256
+
2257
+
<!ENTITY pgsql.changelog.connection-object '<row xmlns="http://docbook.org/ns/docbook">
2258
+
<entry>8.1.0</entry>
2259
+
<entry>
2260
+
The <parameter>connection</parameter> parameter expects an <classname>PgSql\Connection</classname>
2261
+
instance now; previously, a &resource; was expected.
2262
+
</entry>
2263
+
</row>'>
2264
+
2265
+
<!ENTITY pgsql.changelog.result-object '<row xmlns="http://docbook.org/ns/docbook">
2266
+
<entry>8.1.0</entry>
2267
+
<entry>
2268
+
The <parameter>result</parameter> parameter expects an <classname>PgSql\Result</classname>
2269
+
instance now; previously, a &resource; was expected.
2270
+
</entry>
2271
+
</row>'>
2272
+
2273
+
<!ENTITY pgsql.changelog.lob-object '<row xmlns="http://docbook.org/ns/docbook">
2274
+
<entry>8.1.0</entry>
2275
+
<entry>
2276
+
The <parameter>lob</parameter> parameter expects an <classname>PgSql\Lob</classname>
2277
+
instance now; previously, a &resource; was expected.
2278
+
</entry>
2279
+
</row>'>
2280
+
2281
+
<!ENTITY pgsql.changelog.return-result-object '<row xmlns="http://docbook.org/ns/docbook">
2282
+
<entry>8.1.0</entry>
2283
+
<entry>
2284
+
Returns an <classname>PgSql\Result</classname> instance now;
2285
+
previously, a &resource; was returned.
2286
+
</entry>
2287
+
</row>'>
1048
2288
1049
2289
<!-- Common pieces for reference part END -->
1050
2290
...
...
@@ -1058,58 +2298,51 @@ extensions in order to use these functions.</simpara>'>
1058
2298
1059
2299
<!ENTITY sqlsafemode '<link xmlns="http://docbook.org/ns/docbook" linkend="ini.sql.safe-mode">SQL safe mode</link>'>
1060
2300
1061
-
<!-- APD Notes -->
1062
-
<!ENTITY apd.debug-level.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1063
-
debug_level</parameter></term><listitem><para>An integer which is formed by adding
1064
-
together the <literal>XXX_TRACE</literal> constants.</para><para>It is not recommended
1065
-
to use <constant>MEMORY_TRACE</constant>. It is very slow and does not appear to be accurate.
1066
-
<constant>ASSIGNMENT_TRACE</constant> is not implemented yet.</para><para>To turn on all
1067
-
functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the value 99</para>
1068
-
</listitem></varlistentry>'>
1069
-
1070
-
<!-- BCMath Notes -->
1071
-
<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1072
-
scale</parameter></term><listitem><para>This optional parameter is used to set the number
1073
-
of digits after the decimal place in the result. You can also set the global default scale
1074
-
for all functions by using <function>bcscale</function>.</para></listitem></varlistentry>'>
1075
-
1076
2301
<!-- CTYPE Notes -->
1077
2302
<!ENTITY note.ctype.parameter.integer '<note xmlns="http://docbook.org/ns/docbook"><para>
1078
-
If an <type>integer</type> between -128 and 255 inclusive is provided, it is interpreted as
2303
+
If an <type>int</type> between -128 and 255 inclusive is provided, it is interpreted as
1079
2304
the ASCII value of a single character (negative values have 256 added in order to allow
1080
2305
characters in the Extended ASCII range). Any other integer is interpreted as a string
1081
2306
containing the decimal digits of the integer.</para></note>'>
1082
2307
1083
-
<!-- FBSQL Notes -->
1084
-
<!ENTITY fbsql.link-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1085
-
link_identifier</parameter></term><listitem><para>A FrontBase link identifier
1086
-
returned by <function>fbsql_connect</function> or
1087
-
<function>fbsql_pconnect</function>.</para><para>If optional and not specified,
1088
-
the function will try to find an open link to the FrontBase server and if no
1089
-
such link is found it will try to create one as if
1090
-
<function>fbsql_connect</function> was called with no arguments.</para>
1091
-
</listitem></varlistentry>'>
1092
-
1093
-
<!ENTITY fbsql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1094
-
result</parameter></term><listitem><para>A result identifier
1095
-
returned by <function>fbsql_query</function> or
1096
-
<function>fbsql_db_query</function>.</para></listitem></varlistentry>'>
2308
+
<!ENTITY note.ctype.parameter.non-string '<warning xmlns="http://docbook.org/ns/docbook"><para>
2309
+
As of PHP 8.1.0, passing a non-string argument is deprecated.
2310
+
In the future, the argument will be interpreted as a string instead of an ASCII codepoint.
2311
+
Depending on the intended behavior, the argument should either be cast to &string;
2312
+
or an explicit call to <function>chr</function> should be made.</para></warning>'>
2313
+
2314
+
<!ENTITY ctype.result.empty-string 'When called with an empty string the result will always be &false;.'>
2315
+
2316
+
<!-- FTP Notes -->
2317
+
<!ENTITY ftp.changelog.ftp-param '<row xmlns="http://docbook.org/ns/docbook">
2318
+
<entry>8.1.0</entry>
2319
+
<entry>
2320
+
The <parameter>ftp</parameter> parameter expects an <classname>FTP\Connection</classname>
2321
+
instance now; previously, a &resource; was expected.
2322
+
</entry>
2323
+
</row>'>
2324
+
<!ENTITY ftp.parameter.ftp '<para xmlns="http://docbook.org/ns/docbook">An <classname>FTP\Connection</classname> instance.</para>'>
1097
2325
1098
2326
<!-- GMP Notes -->
1099
-
<!ENTITY gmp.return 'A GMP number <type xmlns="http://docbook.org/ns/docbook">resource</type> in PHP 5.5 and earlier, or a <classname xmlns="http://docbook.org/ns/docbook">GMP</classname> object in PHP 5.6 and later.'>
1100
-
<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">Either a GMP number <type>resource</type> in PHP 5.5 and earlier, a <classname>GMP</classname> object in PHP 5.6 and later, or a numeric string provided that it is possible to convert the latter to a number.</para>'>
2327
+
<!ENTITY gmp.return 'A <classname xmlns="http://docbook.org/ns/docbook">GMP</classname> object.'>
2328
+
<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">
2329
+
A <classname>GMP</classname> object, an &integer;,
2330
+
or a &string; that can be interpreted as a number following the same logic
2331
+
as if the string was used in <function>gmp_init</function> with automatic
2332
+
base detection (i.e. when <parameter>base</parameter> is equal to 0).
2333
+
</para>'>
1101
2334
1102
2335
<!-- MySQLi Notes -->
1103
-
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1104
-
result</parameter></term><listitem><para>Procedural style only: A result set
1105
-
identifier returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>
1106
-
or <function>mysqli_use_result</function>.</para></listitem></varlistentry>'>
1107
-
<!ENTITY mysqli.link.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1108
-
link</parameter></term><listitem><para>Procedural style only: A link identifier
2336
+
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2337
+
<parameter>result</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_result</classname>
2338
+
object returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>,
2339
+
<function>mysqli_use_result</function> or <function>mysqli_stmt_get_result</function>.</para></listitem></varlistentry>'>
2340
+
<!ENTITY mysqli.link.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2341
+
<parameter>mysql</parameter></term><listitem><para>Procedural style only: A <classname>mysqli</classname> object
1109
2342
returned by <function>mysqli_connect</function> or <function>mysqli_init</function>
1110
2343
</para></listitem></varlistentry>'>
1111
-
<!ENTITY mysqli.stmt.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1112
-
stmt</parameter></term><listitem><para>Procedural style only: A statement identifier
2344
+
<!ENTITY mysqli.stmt.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2345
+
<parameter>statement</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_stmt</classname> object
1113
2346
returned by <function>mysqli_stmt_init</function>.</para></listitem></varlistentry>'>
1114
2347
<!ENTITY mysqli.available.mysqlnd 'Available only with <link xmlns="http://docbook.org/ns/docbook"
1115
2348
linkend="book.mysqlnd">mysqlnd</link>.'>
...
...
@@ -1118,14 +2351,35 @@ linkend="book.mysqlnd">mysqlnd</link>.'>
1118
2351
hand-shake/authentication, which mysqlnd will use.</para><para>Libmysqlclient uses the default charset set in the
1119
2352
<filename>my.cnf</filename> or by an explicit call to <function>mysqli_options</function> prior to
1120
2353
calling <function>mysqli_real_connect</function>, but after <function>mysqli_init</function>.</para></note>'>
2354
+
<!ENTITY mysqli.integer.overflow.as.string.note '<note xmlns="http://docbook.org/ns/docbook">
2355
+
<para>If the number of rows is greater than <constant>PHP_INT_MAX</constant>,
2356
+
the number will be returned as a &string;.</para></note>'>
2357
+
<!ENTITY mysqli.sqlinjection.warning '<warning xmlns="http://docbook.org/ns/docbook">
2358
+
<title>Security warning: SQL injection</title><para>If the query contains any variable
2359
+
input then <link linkend="mysqli.quickstart.prepared-statements">parameterized
2360
+
prepared statements</link> should be used instead. Alternatively, the
2361
+
data must be properly formatted and all strings must be escaped using
2362
+
the <function>mysqli_real_escape_string</function>
2363
+
function.</para></warning>'>
2364
+
<!ENTITY mysqli.conditionalexception '<para xmlns="http://docbook.org/ns/docbook">
2365
+
If mysqli error reporting is enabled (<constant>MYSQLI_REPORT_ERROR</constant>) and the requested operation fails,
2366
+
a warning is generated. If, in addition, the mode is set to <constant>MYSQLI_REPORT_STRICT</constant>,
2367
+
a <classname>mysqli_sql_exception</classname> is thrown instead.</para>'>
2368
+
2369
+
<!-- Notes for PCRE -->
2370
+
<!ENTITY pcre.pattern.warning '<para xmlns="http://docbook.org/ns/docbook">
2371
+
If the regex pattern passed does not compile to a valid regex, an <constant>E_WARNING</constant> is emitted.
2372
+
</para>'>
1121
2373
1122
2374
<!-- Notes for SAPI/Apache -->
1123
-
<!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
1124
-
<link linkend="book.nsapi">NSAPI server module</link> in Netscape/iPlanet/SunONE
1125
-
webservers, too.</para>'>
2375
+
<!ENTITY apache.req.module '<simpara xmlns="http://docbook.org/ns/docbook">This function is supported when PHP
2376
+
is installed as an Apache module webserver.
2377
+
</simpara>'>
1126
2378
1127
-
<!ENTITY apache.req.module '<simpara xmlns="http://docbook.org/ns/docbook">This function is only supported when PHP
1128
-
is installed as an Apache module.</simpara>'>
2379
+
<!-- Notes for SAPI/FPM -->
2380
+
<!ENTITY fpm.intro '<para xmlns="http://docbook.org/ns/docbook">FPM (FastCGI Process Manager) is
2381
+
a primary PHP FastCGI implementation containing some features (mostly) useful for heavy-loaded sites.
2382
+
</para>'>
1129
2383
1130
2384
<!-- SimpleXML Notes -->
1131
2385
<!ENTITY simplexml.iteration '<note xmlns="http://docbook.org/ns/docbook"><simpara>SimpleXML has made a rule of adding
...
...
@@ -1169,94 +2423,72 @@ are <emphasis>case-sensitive</emphasis>.</simpara></note>'>
1169
2423
<!ENTITY database.fetch-null '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function sets NULL fields to
1170
2424
the PHP &null; value.</simpara></note>'>
1171
2425
1172
-
<!-- MSQL Notes -->
1173
-
<!-- The msql.*.description entities are used in the parameters refsect1 -->
1174
-
<!ENTITY msql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1175
-
link_identifier</parameter></term><listitem><para>The mSQL connection.
1176
-
If not specified, the last link opened by <function>msql_connect</function>
1177
-
is assumed. If no such link is found, the function will try to establish a
1178
-
link as if <function>msql_connect</function> was called, and use it.
1179
-
</para></listitem></varlistentry>'>
1180
-
1181
-
<!ENTITY msql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1182
-
result</parameter></term><listitem><para>The result <type>resource</type> that
1183
-
is being evaluated. This result comes from a call to
1184
-
<function>msql_query</function>.</para></listitem></varlistentry>'>
1185
-
1186
-
<!ENTITY msql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1187
-
field_offset</parameter></term><listitem><para>The numerical field offset. The
1188
-
<parameter>field_offset</parameter> starts at <literal>1</literal>.</para></listitem></varlistentry>'>
1189
-
1190
-
1191
2426
<!-- MySQL Notes -->
1192
2427
<!-- The mysql.*.description entities are used in the parameters refsect1 -->
1193
-
<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1194
-
link_identifier</parameter></term><listitem><para>The MySQL connection. If the
2428
+
<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2429
+
<parameter>link_identifier</parameter></term><listitem><para>The MySQL connection. If the
1195
2430
link identifier is not specified, the last link opened by
1196
2431
<function>mysql_connect</function> is assumed. If no such link is found, it
1197
-
will try to create one as if <function>mysql_connect</function> was called
2432
+
will try to create one as if <function>mysql_connect</function> had been called
1198
2433
with no arguments. If no connection is found or established, an
1199
2434
<constant>E_WARNING</constant> level error is generated.</para></listitem>
1200
2435
</varlistentry>'>
1201
2436
1202
2437
<!ENTITY mysql.linkid-noreopen.description '<varlistentry
1203
-
xmlns="http://docbook.org/ns/docbook"><term><parameter>
1204
-
link_identifier</parameter></term><listitem><para>The MySQL connection. If the
2438
+
xmlns="http://docbook.org/ns/docbook"><term>
2439
+
<parameter>link_identifier</parameter></term><listitem><para>The MySQL connection. If the
1205
2440
link identifier is not specified, the last link opened by
1206
2441
<function>mysql_connect</function> is assumed. If no connection is found or
1207
2442
established, an <constant>E_WARNING</constant> level error is
1208
2443
generated.</para></listitem></varlistentry>'>
1209
2444
1210
-
<!ENTITY mysql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1211
-
result</parameter></term><listitem><para>The result <type>resource</type> that
2445
+
<!ENTITY mysql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2446
+
<parameter>result</parameter></term><listitem><para>The result <type>resource</type> that
1212
2447
is being evaluated. This result comes from a call to
1213
2448
<function>mysql_query</function>.</para></listitem></varlistentry>'>
1214
2449
1215
-
<!ENTITY mysql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1216
-
field_offset</parameter></term><listitem><para>The numerical field offset. The
2450
+
<!ENTITY mysql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2451
+
<parameter>field_offset</parameter></term><listitem><para>The numerical field offset. The
1217
2452
<parameter>field_offset</parameter> starts at <literal>0</literal>. If
1218
2453
<parameter>field_offset</parameter> does not exist, an error of level
1219
2454
<constant>E_WARNING</constant> is also issued.</para></listitem></varlistentry>'>
1220
2455
1221
-
<!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.
2456
+
<!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.
1222
2457
Instead, the <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extension should be used.
1223
-
See also <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and
1224
-
<link linkend="faq.databases.mysql.deprecated">related FAQ</link> for more information.
2458
+
See also <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
1225
2459
Alternatives to this function include:</para>'>
1226
2460
1227
-
<!-- Sybase Notes -->
1228
-
<!ENTITY sybase.ct.only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when
1229
-
using the CT library interface to Sybase, and not with the DB library.
1230
-
</simpara></note>'>
1231
-
1232
-
<!ENTITY sybase.db.only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when
1233
-
using the DB library interface to Sybase, and not with the CT library.</simpara></note>'>
2461
+
<!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
2462
+
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
2463
+
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
2464
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
2465
+
Alternatives to this function include:</para>'>
1234
2466
1235
-
<!ENTITY sybase.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1236
-
link_identifier</parameter></term><listitem><para>The Sybase connection. If the
1237
-
link identifier is not specified, the last link opened by
1238
-
<function>sybase_connect</function> is assumed. If no such link is found, it
1239
-
will try to create one as if <function>sybase_connect</function> was called
1240
-
with no arguments. If no connection is found or established, an
1241
-
<constant>E_WARNING</constant> level error is generated.</para></listitem>
1242
-
</varlistentry>'>
2467
+
<!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
2468
+
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
2469
+
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
2470
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
2471
+
Alternatives to this function include:</para>'>
1243
2472
1244
-
<!-- CPDF Notes -->
1245
-
<!ENTITY cpdf.ul '<para xmlns="http://docbook.org/ns/docbook">The optional parameter <parameter>mode</parameter>
1246
-
determines the unit length. If it is <literal>0</literal> or omitted, the
1247
-
default unit as specified for the page is used. In other cases, the coordinates
1248
-
are measured in postscript points, disregarding the current unit.</para>'>
2473
+
<!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
2474
+
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
2475
+
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
2476
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
2477
+
Alternatives to this function include:</para>'>
1249
2478
1250
-
<!ENTITY cpdf.mode.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1251
-
mode</parameter></term><listitem><para>The optional parameter <parameter>mode</parameter>
1252
-
determines the unit length. If it is <literal>0</literal> or omitted, the
1253
-
default unit as specified for the page is used. In other cases, the coordinates
1254
-
are measured in postscript points, disregarding the current unit.</para>
1255
-
</listitem></varlistentry>'>
2479
+
<!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
2480
+
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
2481
+
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
2482
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
2483
+
Alternatives to this function include:</para>'>
1256
2484
1257
-
<!ENTITY cpdf.pdf-document.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1258
-
pdf_document</parameter></term><listitem><para>The document handle, returned by
1259
-
<function>cpdf_open</function>.</para></listitem></varlistentry>'>
2485
+
<!ENTITY mysql.close.connections.result.sets '<para xmlns="http://docbook.org/ns/docbook">
2486
+
Open non-persistent MySQL connections and result sets are automatically destroyed when a
2487
+
PHP script finishes its execution. So, while explicitly closing open
2488
+
connections and freeing result sets is optional, doing so is recommended.
2489
+
This will immediately return resources to PHP and MySQL, which can
2490
+
improve performance. For related information, see
2491
+
<link linkend="language.types.resource.self-destruct">freeing resources</link></para>'>
1260
2492
1261
2493
<!-- Xattr entities -->
1262
2494
<!ENTITY xattr.namespace '<para xmlns="http://docbook.org/ns/docbook">Extended attributes have two different namespaces: user
...
...
@@ -1270,23 +2502,9 @@ namespace by default, but this can be changed with the
1270
2502
(e.g. <literal>fe80::1</literal>), you must enclose the IP in square
1271
2503
brackets—for example, <literal>tcp://[fe80::1]:80</literal>.</simpara></note>'>
1272
2504
1273
-
<!ENTITY ipv6.php5 '<note xmlns="http://docbook.org/ns/docbook"><simpara>IPv6 Support was added in PHP 5.0.0.
1274
-
</simpara></note>'>
1275
-
1276
2505
<!-- Notes for tidy -->
1277
-
<!ENTITY note.tidy.ze2 '<note xmlns="http://docbook.org/ns/docbook"><simpara> This function is only available with
1278
-
Zend Engine 2 (PHP >= 5.0.0).</simpara></note>'>
1279
-
1280
2506
<!ENTITY tidy.object 'The <classname xmlns="http://docbook.org/ns/docbook">Tidy</classname> object.'>
1281
2507
1282
-
<!ENTITY note.tidy.1only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available in
1283
-
Tidy 1.0. It became obsolete in Tidy 2.0, and thus has been removed.
1284
-
</simpara></note>'>
1285
-
1286
-
<!ENTITY note.tidy.2only '<note xmlns="http://docbook.org/ns/docbook"><simpara>The optional parameters
1287
-
<parameter>config</parameter> and <parameter>encoding</parameter> were
1288
-
added in Tidy 2.0.</simpara></note>'>
1289
-
1290
2508
<!ENTITY tidy.conf-enc '<para xmlns="http://docbook.org/ns/docbook">The <parameter>config</parameter> parameter
1291
2509
can be passed either as an array or as a string. If a string is passed,
1292
2510
it is interpreted as the name of the configuration file, otherwise, it is
...
...
@@ -1308,6 +2526,15 @@ threaded MPM in production with Apache 2. Use the prefork MPM, which is
1308
2526
the default MPM with Apache 2.0 and 2.2.
1309
2527
For information on why, read the related FAQ entry on using
1310
2528
<link linkend="faq.installation.apache2">Apache2 with a threaded MPM</link></para></warning>'>
2529
+
<!ENTITY warn.install.third-party-support '<warning xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
2530
+
<para>
2531
+
Builds from third-parties are considered unofficial and not directly
2532
+
supported by the PHP project. Any bugs encountered should be reported to the
2533
+
provider of those unofficial builds unless they can be reproduced using the
2534
+
builds from <link xlink:href="&url.php.downloads;">the official download
2535
+
area</link>.
2536
+
</para>
2537
+
</warning>'>
1311
2538
1312
2539
<!ENTITY note.apache.slashes '<note xmlns="http://docbook.org/ns/docbook"><simpara>Remember that when adding
1313
2540
path values in the Apache configuration files on Windows, all backslashes
...
...
@@ -1318,10 +2545,9 @@ slash may also be necessary for directories.</simpara></note>'>
1318
2545
<!-- Snippets and titles for the contributors section -->
1319
2546
<!ENTITY Credit.Authors.and.Contributors 'Authors and Contributors'>
1320
2547
1321
-
<!ENTITY Credit.Introduction '<para xmlns="http://docbook.org/ns/docbook"> We highlight the currently most active
1322
-
people on front page of the manual, but there are many more contributors who
2548
+
<!ENTITY Credit.Introduction '<para xmlns="http://docbook.org/ns/docbook"> There is a large number of contributors who
1323
2549
currently help in our work or have provided a great amount of help to the project
1324
-
in the past. There are a lot of unnamed people who help out with user
2550
+
in the past. There are also a lot of unnamed people who help out with user
1325
2551
notes on manual pages, which continually get included in the references, the
1326
2552
work of whom we are also very thankful for. All of the lists provided below are in
1327
2553
alphabetical order.
...
...
@@ -1345,23 +2571,11 @@ into managing user notes:'>
1345
2571
1346
2572
<!ENTITY listendand ' and'>
1347
2573
1348
-
<!-- classkit and runkit entities -->
1349
-
<!ENTITY note.classkit.selfmanipulation '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function cannot
1350
-
be used to manipulate the currently running (or chained) method.</simpara>
1351
-
</note>'>
1352
-
2574
+
<!-- runkit entities -->
1353
2575
<!ENTITY note.runkit.selfmanipulation '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function cannot
1354
2576
be used to manipulate the currently running (or chained) method.</simpara>
1355
2577
</note>'>
1356
2578
1357
-
<!ENTITY note.runkit.sandbox '<note xmlns="http://docbook.org/ns/docbook"><simpara>Sandbox support (required for
1358
-
<function>runkit_lint</function>, <function>runkit_lint_file</function>,
1359
-
and the <classname>Runkit_Sandbox</classname> class) is only available as of
1360
-
PHP 5.1.0 or specially patched versions of PHP 5.0, and requires that thread
1361
-
safety be enabled.
1362
-
See the <filename>README</filename> file included in the runkit package for
1363
-
more information.</simpara></note>'>
1364
-
1365
2579
<!ENTITY note.runkit.internal-override '<note xmlns="http://docbook.org/ns/docbook"><simpara>By default, only
1366
2580
userspace functions may be removed, renamed, or modified. In order to
1367
2581
override internal functions, you must enable the
...
...
@@ -1375,48 +2589,21 @@ is used for managing public keys on a server to which the client is
1375
2589
using public key authentication, use the
1376
2590
<function>ssh2_auth_pubkey_file</function> function instead.</simpara></note>'>
1377
2591
1378
-
<!-- HTTP -->
1379
-
<!ENTITY see.http.request.options '<para xmlns="http://docbook.org/ns/docbook">See the full list of &link.http.request.options;.</para>'>
1380
-
<!ENTITY see.http.configuration.force_exit 'See the &link.http.configuration;
1381
-
<link xmlns="http://docbook.org/ns/docbook" linkend="http.configuration.force-exit">http.force_exit</link> for what "exits" means.'>
1382
-
1383
-
<!ENTITY link.http.configuration '<link xmlns="http://docbook.org/ns/docbook" linkend="http.configuration">INI setting</link>'>
1384
-
<!ENTITY link.http.request.option '<link xmlns="http://docbook.org/ns/docbook" linkend="http.request.options">request option</link>'>
1385
-
<!ENTITY link.http.request.options '<link xmlns="http://docbook.org/ns/docbook" linkend="http.request.options">request options</link>'>
1386
-
<!ENTITY link.http.request.info '<link xmlns="http://docbook.org/ns/docbook" linkend="http.request.info">Request/response information</link>'>
1387
-
<!ENTITY returns.http.response 'Returns the HTTP response(s) as string on
1388
-
success, or &false; on failure.'>
1389
-
<!ENTITY returns.http.false.orexits 'Returns &false; or <emphasis xmlns="http://docbook.org/ns/docbook">exits</emphasis> on success'>
2592
+
<!-- Session notes -->
1390
2593
<!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.'>
1391
-
<!ENTITY http.request.affects 'Affects the following request method(s) only:'>
1392
-
<!ENTITY http.request.affects.any 'Affects any request method.'>
1393
-
<!ENTITY http.response.class.php51 'the <link xmlns="http://docbook.org/ns/docbook" linkend="class.httpresponse">
1394
-
<classname>HttpResponse</classname></link> class if you are using PHP 5.1.0
1395
-
and above'>
1396
-
<!ENTITY http.maynotwork.SAPI 'This may not work as expected with the following SAPI(s):'>
1397
-
<!ENTITY http.content.disposition 'The <literal xmlns="http://docbook.org/ns/docbook">Content-Disposition</literal>
1398
-
header is very useful if the data actually being sent came from a file or
1399
-
something similar, that should be "saved" by the client/user (i.e. by
1400
-
the browser's "Save as..." popup window).'>
1401
-
<!ENTITY http.use.ob_start 'For use with <function xmlns="http://docbook.org/ns/docbook">ob_start</function>.'>
1402
-
1403
-
<!ENTITY note.http.response.recalculate.etag.lm '<note xmlns="http://docbook.org/ns/docbook"><simpara>Previously calculated or defined <literal>ETag</literal>
1404
-
and <literal>Last-Modified</literal> will be recalculated and redefined.</simpara></note>'>
1405
-
<!ENTITY note.http.throttling.yields.process '<note xmlns="http://docbook.org/ns/docbook"><simpara>Provides a basic throttling mechanism, which will yield
1406
-
the current process or thread until the entity has been completely sent.</simpara></note>'>
1407
-
<!ENTITY note.http.send.API '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function should be used in conjunction with
1408
-
<function>http_send_data</function>, <function>http_send_file</function> &listendand; <function>http_send_stream</function>.</simpara></note>'>
1409
-
<!ENTITY note.http.send.API.mayuse '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function may be used in conjunction with
1410
-
<function>http_send_data</function>, <function>http_send_file</function> &listendand; <function>http_send_stream</function>.</simpara></note>'>
1411
-
<!ENTITY note.http.request.encodecookies '<note xmlns="http://docbook.org/ns/docbook"><simpara>The &link.http.request.option; <literal>encodecookies</literal> controls
1412
-
whether the cookie values should be <function>urlencode</function>d.</simpara></note>'>
1413
-
<!ENTITY note.http.request.affects.any '<note xmlns="http://docbook.org/ns/docbook"><simpara>&http.request.affects.any;</simpara></note>'>
1414
-
<!ENTITY note.http.ob.once '<note xmlns="http://docbook.org/ns/docbook"><simpara>This output handler can only be used once.</simpara></note>'>
1415
2594
1416
2595
<!-- XMLWriter Notes -->
1417
-
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1418
-
xmlwriter</parameter></term><listitem><para>Only for procedural calls.
1419
-
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>'>
2596
+
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2597
+
<parameter>writer</parameter></term><listitem><para>Only for procedural calls.
2598
+
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>'>
2599
+
2600
+
<!ENTITY xmlwriter.changelog.writer-param '<row xmlns="http://docbook.org/ns/docbook">
2601
+
<entry>8.0.0</entry>
2602
+
<entry>
2603
+
<parameter>writer</parameter> expects an <classname>XMLWriter</classname>
2604
+
instance now; previously, a <type>resource</type> was expected.
2605
+
</entry>
2606
+
</row>'>
1420
2607
1421
2608
<!-- SOAP notes -->
1422
2609
<!ENTITY soap.wsdl.mode.only "<note xmlns='http://docbook.org/ns/docbook'><para>This function only works in WSDL mode.</para></note>">
...
...
@@ -1440,6 +2627,7 @@ The XMLWriter <type>resource</type> that is being modified. This resource comes
1440
2627
<!ENTITY fann.return.bool '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>
1441
2628
<!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>'>
1442
2629
<!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>'>
2630
+
<!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>'>
1443
2631
1444
2632
<!-- Imagick generic return types -->
1445
2633
<!ENTITY imagick.return.success 'Returns &true; on success.'>
...
...
@@ -1467,8 +2655,12 @@ The XMLWriter <type>resource</type> that is being modified. This resource comes
1467
2655
<!ENTITY imagick.method.available.0x653 'This method is available if Imagick has been compiled against ImageMagick version 6.5.3 or newer.'>
1468
2656
<!ENTITY imagick.method.available.0x657 'This method is available if Imagick has been compiled against ImageMagick version 6.5.7 or newer.'>
1469
2657
2658
+
<!ENTITY imagick.method.not.available.0x700 'This method is not available if Imagick has been compiled against ImageMagick version 7.0.0 or newer.'>
2659
+
1470
2660
<!ENTITY imagick.constant.available 'This constant is available if Imagick has been compiled against ImageMagick version'>
1471
2661
2662
+
<!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>'>
2663
+
1472
2664
<!-- Imagick default channel information -->
1473
2665
<!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>'>
1474
2666
...
...
@@ -1528,13 +2720,6 @@ The XMLWriter <type>resource</type> that is being modified. This resource comes
1528
2720
</para>
1529
2721
</note>
1530
2722
'>
1531
-
<!ENTITY com.use-oo-instead '<note xmlns="http://docbook.org/ns/docbook">
1532
-
<simpara>
1533
-
This function does not exist in PHP 5; instead, you should use the regular
1534
-
and more natural OO syntax to access properties or call methods.
1535
-
</simpara>
1536
-
</note>
1537
-
'>
1538
2723
1539
2724
<!-- phar -->
1540
2725
<!ENTITY phar.write '<note xmlns="http://docbook.org/ns/docbook"><para>This
...
...
@@ -1542,22 +2727,32 @@ method requires the &php.ini; setting <literal>phar.readonly</literal> to be
1542
2727
set to <literal>0</literal> in order to work for <classname>Phar</classname>
1543
2728
objects. Otherwise, a <classname>PharException</classname> will be thrown.</para></note>'>
1544
2729
1545
-
<!ENTITY phar.removed.pharcompress '<note xmlns="http://docbook.org/ns/docbook"><para>This
1546
-
method has been removed from the phar extension as of version 2.0.0. Alternative
1547
-
implementations are available using <function>Phar::compress</function>,
1548
-
<function>Phar::decompress</function>, <function>Phar::compressFiles</function> and
1549
-
<function>Phar::decompressFiles</function>.</para></note>'>
2730
+
<!ENTITY phar.note.performance '<note xmlns="http://docbook.org/ns/docbook">
2731
+
<simpara>
2732
+
<function>Phar::addFile</function>, <function>Phar::addFromString</function> and <function>Phar::offsetSet</function>
2733
+
save a new phar archive each time they are called. If performance is a concern,
2734
+
<function>Phar::buildFromDirectory</function> or <function>Phar::buildFromIterator</function>
2735
+
should be used instead.
2736
+
</simpara>
2737
+
</note>'>
1550
2738
1551
-
<!ENTITY phar.removed.pharfileinfocompress '<note xmlns="http://docbook.org/ns/docbook"><para>This
1552
-
method has been removed from the phar extension as of version 2.0.0. Alternative
1553
-
implementations are available using <function>PharFileInfo::isCompressed</function>,
1554
-
<function>PharFileInfo::decompress</function>, and <function>PharFileInfo::compress</function>.</para></note>'>
2739
+
<!ENTITY phardata.note.performance '<note xmlns="http://docbook.org/ns/docbook">
2740
+
<simpara>
2741
+
<function>PharData::addFile</function>, <function>PharData::addFromString</function> and <function>PharData::offsetSet</function>
2742
+
save a new phar archive each time they are called. If performance is a concern,
2743
+
<function>PharData::buildFromDirectory</function> or <function>PharData::buildFromIterator</function>
2744
+
should be used instead.
2745
+
</simpara>
2746
+
</note>'>
1555
2747
1556
2748
<!-- XML -->
1557
-
<!ENTITY libxml.required '<para xmlns="http://docbook.org/ns/docbook">This extension requires the
1558
-
<link linkend="book.libxml">libxml</link> PHP extension. This means that passing in
1559
-
<option role="configure">--enable-libxml</option> is also required, although this is implicitly accomplished
1560
-
because libxml is enabled by default.</para>'>
2749
+
<!ENTITY libxml.required '<para xmlns="http://docbook.org/ns/docbook">
2750
+
This extension requires the <link linkend="book.libxml">libxml</link> PHP extension.
2751
+
This means passing the <option role="configure">--with-libxml</option>,
2752
+
or prior to PHP 7.4 the <option role="configure">--enable-libxml</option>,
2753
+
configuration flag, although this is implicitly accomplished because libxml
2754
+
is enabled by default.
2755
+
</para>'>
1561
2756
1562
2757
<!-- XMLReader -->
1563
2758
<!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>'>
...
...
@@ -1574,6 +2769,9 @@ because libxml is enabled by default.</para>'>
1574
2769
<varname linkend="streamwrapper.props.context">streamWrapper::$context</varname>
1575
2770
property is updated if a valid context is passed to the caller function.</para></note>'>
1576
2771
2772
+
<!ENTITY stream.bucket.param '<parameter>bucket</parameter> expects a <classname>StreamBucket</classname> instance now; previously, an <classname>stdClass</classname> was expected.'>
2773
+
<!ENTITY stream.bucket.return 'This function returns a <classname>StreamBucket</classname> instance now; previously, an <classname>stdClass</classname> was returned.'>
2774
+
1577
2775
<!-- Gmagick -->
1578
2776
<!ENTITY gmagick.return.success 'Returns &true; on success.'>
1579
2777
<!ENTITY gmagick.gmagickexception.throw 'Throws an
...
...
@@ -1592,29 +2790,41 @@ to be references, then they must be references in the passed argument list.'>
1592
2790
1593
2791
<!ENTITY reflection.export.param.name 'The reflection to export.'>
1594
2792
1595
-
<!-- SPL -->
1596
-
<!ENTITY spl.datastructures.intro.title '<title xmlns="http://docbook.org/ns/docbook">Datastructures</title>'>
1597
-
1598
-
<!ENTITY spl.exceptions.intro.title '<title xmlns="http://docbook.org/ns/docbook">Exceptions</title>'>
1599
-
<!ENTITY spl.exceptions.intro '<para xmlns="http://docbook.org/ns/docbook">SPL provides a set of standard Exceptions.</para><para xmlns="http://docbook.org/ns/docbook">See also the <xref linkend="reserved.exceptions" /></para>'>
1600
-
1601
-
<!ENTITY spl.files.intro.title '<title xmlns="http://docbook.org/ns/docbook">File Handling</title>'>
1602
-
<!ENTITY spl.files.intro '<partintro xmlns="http://docbook.org/ns/docbook"><para>SPL provides a number of classes to work with files.</para></partintro>'>
1603
-
1604
-
<!ENTITY spl.interfaces.intro.title '<title xmlns="http://docbook.org/ns/docbook">Interfaces</title>'>
1605
-
<!ENTITY spl.interfaces.intro '<para xmlns="http://docbook.org/ns/docbook">SPL provides a set of interfaces.</para><para xmlns="http://docbook.org/ns/docbook">See also the <xref linkend="reserved.interfaces" /></para>'>
1606
-
<!ENTITY spl.interfaces.list '<title xmlns="http://docbook.org/ns/docbook">Interface list</title>'>
2793
+
<!ENTITY reflection.getattributes.param.name '<varlistentry xmlns="http://docbook.org/ns/docbook">
2794
+
<term><parameter>name</parameter></term>
2795
+
<listitem>
2796
+
<para>
2797
+
Filter the results to include only <classname>ReflectionAttribute</classname>
2798
+
instances for attributes matching this class name.
2799
+
</para>
2800
+
</listitem>
2801
+
</varlistentry>'>
1607
2802
1608
-
<!ENTITY spl.iterators.intro.title '<title xmlns="http://docbook.org/ns/docbook">Iterators</title>'>
1609
-
<!ENTITY spl.iterators.intro '<para xmlns="http://docbook.org/ns/docbook">SPL provides a set of iterators to traverse over objects.</para>'>
2803
+
<!ENTITY reflection.getattributes.param.flags '<varlistentry xmlns="http://docbook.org/ns/docbook">
2804
+
<term><parameter>flags</parameter></term>
2805
+
<listitem>
2806
+
<para>
2807
+
Flags for determining how to filter the results, if <parameter>name</parameter>
2808
+
is provided.
2809
+
</para>
2810
+
<para>
2811
+
Default is <literal>0</literal> which will only return results for attributes that
2812
+
are of the class <parameter>name</parameter>.
2813
+
</para>
2814
+
<para>
2815
+
The only other option available, is to use <constant>ReflectionAttribute::IS_INSTANCEOF</constant>,
2816
+
which will instead use <literal>instanceof</literal> for filtering.
2817
+
</para>
2818
+
</listitem>
2819
+
</varlistentry>'>
1610
2820
1611
-
<!ENTITY spl.misc.intro.title '<title xmlns="http://docbook.org/ns/docbook">Miscellaneous Classes and Interfaces</title>'>
1612
-
<!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>'>
2821
+
<!-- ZIP -->
2822
+
<!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>'>
1613
2823
1614
2824
<!-- Win32Service -->
1615
2825
<!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.'>
1616
2826
<!ENTITY win32service.success.false.error 'Returns &true; on success&win32service.false.error;'>
1617
-
<!ENTITY win32service.noerror.false.error 'Returns <constant xmlns="http://docbook.org/ns/docbook">WIN32_NO_ERROR</constant> on success&win32service.false.error;'>
2827
+
<!ENTITY win32service.noerror.false.error 'returned <constant xmlns="http://docbook.org/ns/docbook">WIN32_NO_ERROR</constant> on success&win32service.false.error;'>
1618
2828
1619
2829
<!-- SNMP -->
1620
2830
<!ENTITY snmp.set.type.values '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1713,7 +2923,7 @@ system call.</para></listitem>
1713
2923
</varlistentry>
1714
2924
<varlistentry xmlns="http://docbook.org/ns/docbook">
1715
2925
<term><parameter>req</parameter></term>
1716
-
<listitem><para>is optional request resource which can be used with functions like <function>eio_get_last_error</function></para></listitem>
2926
+
<listitem><para>is optional request resource which can be used with functions like <function>eio_get_last_error</function>.</para></listitem>
1717
2927
</varlistentry>
1718
2928
</variablelist>
1719
2929
</para>
...
...
@@ -1758,7 +2968,7 @@ paths</simpara></warning>
1758
2968
<!ENTITY trader.arg.fast.ma.type 'Type of Moving Average for fast MA. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
1759
2969
<!ENTITY trader.arg.slow.ma.type 'Type of Moving Average for slow MA. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
1760
2970
<!ENTITY trader.arg.fastd.ma.type 'Type of Moving Average for Fast-D. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
1761
-
<!ENTITY trader.arg.slowk.ma.type 'Type of Moving Average for Slow-K. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
2971
+
<!ENTITY trader.arg.fastk.ma.type 'Type of Moving Average for Fast-K. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
1762
2972
<!ENTITY trader.arg.slowd.ma.type 'Type of Moving Average for Slow-D. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
1763
2973
<!ENTITY trader.arg.slowk.ma.type 'Type of Moving Average for Slow-K. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
1764
2974
<!ENTITY trader.arg.signal.ma.type 'Type of Moving Average for signal line. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
...
...
@@ -1767,40 +2977,787 @@ paths</simpara></warning>
1767
2977
<!ENTITY trader.arg.fast.limit 'Upper limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.'>
1768
2978
<!ENTITY trader.arg.slow.limit 'Lower limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.'>
1769
2979
1770
-
<!-- Mongo -->
1771
-
<!ENTITY mongo.setreadpreference.parameters '<variablelist xmlns="http://docbook.org/ns/docbook"><varlistentry><term><parameter>read_preference</parameter></term><listitem><para>The read preference mode: <constant>MongoClient::RP_PRIMARY</constant>, <constant>MongoClient::RP_PRIMARY_PREFERRED</constant>, <constant>MongoClient::RP_SECONDARY</constant>, <constant>MongoClient::RP_SECONDARY_PREFERRED</constant>, or <constant>MongoClient::RP_NEAREST</constant>.</para></listitem></varlistentry><varlistentry><term><parameter>tags</parameter></term><listitem><para>An array of zero or more tag sets, where each tag set is itself an array of criteria used to match tags on replica set members.</para></listitem></varlistentry></variablelist>'>
1772
-
<!ENTITY mongo.setreadpreference.returnvalues '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>
1773
-
<!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>'>
1774
-
<!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>'>
1775
-
<!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>'>
1776
-
<!ENTITY mongo.setwriteconcern.returnvalues '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>
1777
-
<!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>'>
1778
-
<!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>'>
1779
-
<!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 (does not include idle time). If the operation is not completed within the timeout period, a <classname>MongoExecutionTimeoutException</classname> will be thrown.</para></listitem>'>
1780
-
<!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>'>
1781
-
<!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>'>
1782
-
<!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>'>
1783
-
<!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>'>
1784
-
<!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>'>
1785
-
<!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>'>
1786
-
<!ENTITY mongo.listcollections.note '<note xmlns="http://docbook.org/ns/docbook"><simpara>This method will use the <link xlink:href="&url.mongodb.dochub.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>'>
1787
-
<!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>'>
1788
-
<!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>'>
1789
-
<!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>'>
1790
-
<!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>'>
1791
-
<!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>'>
1792
-
<!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>'>
1793
-
<!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>'>
1794
-
<!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>'>
1795
-
<!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>'>
1796
-
<!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>'>
1797
-
<!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>'>
1798
-
<!ENTITY mongo.errors.deprecated '<para xmlns="http://docbook.org/ns/docbook">Issues <constant>E_DEPRECATED</constant> warning</para>'>
1799
-
<!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>'>
1800
-
<!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>'>
1801
-
<!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>Determins if MongoDB must apply this batch in order (sequentally, one item at a time) or can rearrange it. 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>'>
1802
-
<!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>'>
1803
-
<!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>'> <!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>'> <!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>'>
2980
+
<!-- mongodb -->
2981
+
<!ENTITY mongodb.changelog.class-removed '
2982
+
<row xmlns="http://docbook.org/ns/docbook">
2983
+
<entry>PECL mongodb 2.0.0</entry>
2984
+
<entry>
2985
+
This class was removed.
2986
+
</entry>
2987
+
</row>
2988
+
'>
2989
+
2990
+
<!ENTITY mongodb.changelog.function-removed '
2991
+
<row xmlns="http://docbook.org/ns/docbook">
2992
+
<entry>PECL mongodb 2.0.0</entry>
2993
+
<entry>
2994
+
This function was removed.
2995
+
</entry>
2996
+
</row>
2997
+
'>
2998
+
2999
+
<!ENTITY mongodb.changelog.method-removed '
3000
+
<row xmlns="http://docbook.org/ns/docbook">
3001
+
<entry>PECL mongodb 2.0.0</entry>
3002
+
<entry>
3003
+
This method was removed.
3004
+
</entry>
3005
+
</row>
3006
+
'>
3007
+
3008
+
<!ENTITY mongodb.changelog.serializable-interface-removed '
3009
+
<row xmlns="http://docbook.org/ns/docbook">
3010
+
<entry>PECL mongodb 2.0.0</entry>
3011
+
<entry>
3012
+
<para>
3013
+
This class no longer implements the
3014
+
<interfacename>Serializable</interfacename> interface.
3015
+
</para>
3016
+
</entry>
3017
+
</row>
3018
+
'>
3019
+
3020
+
<!ENTITY mongodb.changelog.tentative-return-types '
3021
+
<row xmlns="http://docbook.org/ns/docbook">
3022
+
<entry>PECL mongodb 1.15.0</entry>
3023
+
<entry>
3024
+
Return types for methods are declared as tentative on PHP 8.0 and newer,
3025
+
triggering deprecation notices in code that implements this interface
3026
+
without declaring the appropriate return types. The <code>#[ReturnTypeWillChange]</code>
3027
+
attribute can be added to silence the deprecation notice.
3028
+
</entry>
3029
+
</row>
3030
+
'>
3031
+
3032
+
<!ENTITY mongodb.changelog.tentative-return-types-enforced '
3033
+
<row xmlns="http://docbook.org/ns/docbook">
3034
+
<entry>PECL mongodb 2.0.0</entry>
3035
+
<entry>
3036
+
Return types previously declared as tentative are now enforced.
3037
+
</entry>
3038
+
</row>
3039
+
'>
3040
+
3041
+
<!ENTITY mongodb.changelog.throw-unacknowledged-write '
3042
+
<row xmlns="http://docbook.org/ns/docbook">
3043
+
<entry>PECL mongodb 2.0.0</entry>
3044
+
<entry>
3045
+
<para>
3046
+
This method now throws an exception when called for an unacknowledged write instead of returning &null;.
3047
+
</para>
3048
+
</entry>
3049
+
</row>
3050
+
'>
3051
+
3052
+
<!ENTITY mongodb.option.collation '
3053
+
<row xmlns="http://docbook.org/ns/docbook">
3054
+
<entry>collation</entry>
3055
+
<entry><type class="union"><type>array</type><type>object</type></type></entry>
3056
+
<entry>
3057
+
<para>
3058
+
<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>.
3059
+
</para>
3060
+
<para>
3061
+
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.
3062
+
</para>
3063
+
<para>
3064
+
This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
3065
+
</para>
3066
+
</entry>
3067
+
</row>
3068
+
'>
3069
+
<!ENTITY mongodb.option.let '
3070
+
<row xmlns="http://docbook.org/ns/docbook">
3071
+
<entry>let</entry>
3072
+
<entry><type class="union"><type>array</type><type>object</type></type></entry>
3073
+
<entry>
3074
+
<para>
3075
+
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>).
3076
+
</para>
3077
+
<para>
3078
+
This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.
3079
+
</para>
3080
+
</entry>
3081
+
</row>
3082
+
'>
3083
+
<!ENTITY mongodb.option.encryption.keyVaultClient '
3084
+
<row xmlns="http://docbook.org/ns/docbook">
3085
+
<entry>keyVaultClient</entry>
3086
+
<entry><classname>MongoDB\Driver\Manager</classname></entry>
3087
+
<entry>The Manager used to route data key queries to a separate MongoDB cluster. By default, the current Manager and cluster is used.</entry>
3088
+
</row>
3089
+
'>
3090
+
<!ENTITY mongodb.option.encryption.keyVaultNamespace '
3091
+
<row xmlns="http://docbook.org/ns/docbook">
3092
+
<entry>keyVaultNamespace</entry>
3093
+
<entry><type>string</type></entry>
3094
+
<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>
3095
+
</row>
3096
+
'>
3097
+
<!ENTITY mongodb.option.encryption.kmsProviders '
3098
+
<row xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3099
+
<entry>kmsProviders</entry>
3100
+
<entry><type>array</type></entry>
3101
+
<entry>
3102
+
<para>
3103
+
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.
3104
+
</para>
3105
+
<para>
3106
+
If an empty document is specified for <literal>"aws"</literal>,
3107
+
<literal>"azure"</literal>, or <literal>"gcp"</literal>, the driver
3108
+
will attempt to configure the provider using
3109
+
<link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#automatic-credentials">Automatic Credentials</link>.
3110
+
</para>
3111
+
<para>
3112
+
The format for <literal>"aws"</literal> is as follows:
3113
+
</para>
3114
+
<programlisting role="javascript">
3115
+
<![CDATA[
3116
+
aws: {
3117
+
accessKeyId: <string>,
3118
+
secretAccessKey: <string>,
3119
+
sessionToken: <optional string>
3120
+
}
3121
+
]]>
3122
+
</programlisting>
3123
+
<para>
3124
+
The format for <literal>"azure"</literal> is as follows:
3125
+
</para>
3126
+
<programlisting role="javascript">
3127
+
<![CDATA[
3128
+
azure: {
3129
+
tenantId: <string>,
3130
+
clientId: <string>,
3131
+
clientSecret: <string>,
3132
+
identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
3133
+
}
3134
+
]]>
3135
+
</programlisting>
3136
+
<para>
3137
+
The format for <literal>"gcp"</literal> is as follows:
3138
+
</para>
3139
+
<programlisting role="javascript">
3140
+
<![CDATA[
3141
+
gcp: {
3142
+
email: <string>,
3143
+
privateKey: <base64 string>|<MongoDB\BSON\Binary>,
3144
+
endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
3145
+
}
3146
+
]]>
3147
+
</programlisting>
3148
+
<para>
3149
+
The format for <literal>"kmip"</literal> is as follows:
3150
+
</para>
3151
+
<programlisting role="javascript">
3152
+
<![CDATA[
3153
+
kmip: {
3154
+
endpoint: <string>
3155
+
}
3156
+
]]>
3157
+
</programlisting>
3158
+
<para>
3159
+
The format for <literal>"local"</literal> is as follows:
3160
+
</para>
3161
+
<programlisting role="javascript">
3162
+
<![CDATA[
3163
+
local: {
3164
+
// 96-byte master key used to encrypt/decrypt data keys
3165
+
key: <base64 string>|<MongoDB\BSON\Binary>
3166
+
}
3167
+
]]>
3168
+
</programlisting>
3169
+
</entry>
3170
+
</row>
3171
+
'>
3172
+
<!ENTITY mongodb.option.encryption.masterKey-options-by-provider '
3173
+
<para xmlns="http://docbook.org/ns/docbook">
3174
+
<table>
3175
+
<title><literal>"aws"</literal> provider options</title>
3176
+
<tgroup cols="3">
3177
+
<thead>
3178
+
<row>
3179
+
<entry>Option</entry>
3180
+
<entry>Type</entry>
3181
+
<entry>Description</entry>
3182
+
</row>
3183
+
</thead>
3184
+
<tbody>
3185
+
<row>
3186
+
<entry>region</entry>
3187
+
<entry>string</entry>
3188
+
<entry>Required.</entry>
3189
+
</row>
3190
+
<row>
3191
+
<entry>key</entry>
3192
+
<entry>string</entry>
3193
+
<entry>Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).</entry>
3194
+
</row>
3195
+
<row>
3196
+
<entry>endpoint</entry>
3197
+
<entry>string</entry>
3198
+
<entry>Optional. An alternate host identifier to send KMS requests to. May include port number.</entry>
3199
+
</row>
3200
+
</tbody>
3201
+
</tgroup>
3202
+
</table>
3203
+
</para>
3204
+
<para xmlns="http://docbook.org/ns/docbook">
3205
+
<table>
3206
+
<title><literal>"azure"</literal> provider options</title>
3207
+
<tgroup cols="3">
3208
+
<thead>
3209
+
<row>
3210
+
<entry>Option</entry>
3211
+
<entry>Type</entry>
3212
+
<entry>Description</entry>
3213
+
</row>
3214
+
</thead>
3215
+
<tbody>
3216
+
<row>
3217
+
<entry>keyVaultEndpoint</entry>
3218
+
<entry>string</entry>
3219
+
<entry>Required. Host with optional port (e.g. "example.vault.azure.net").</entry>
3220
+
</row>
3221
+
<row>
3222
+
<entry>keyName</entry>
3223
+
<entry>string</entry>
3224
+
<entry>Required.</entry>
3225
+
</row>
3226
+
<row>
3227
+
<entry>keyVersion</entry>
3228
+
<entry>string</entry>
3229
+
<entry>Optional. A specific version of the named key. Defaults to using the key's primary version.</entry>
3230
+
</row>
3231
+
</tbody>
3232
+
</tgroup>
3233
+
</table>
3234
+
</para>
3235
+
<para xmlns="http://docbook.org/ns/docbook">
3236
+
<table>
3237
+
<title><literal>"gcp"</literal> provider options</title>
3238
+
<tgroup cols="3">
3239
+
<thead>
3240
+
<row>
3241
+
<entry>Option</entry>
3242
+
<entry>Type</entry>
3243
+
<entry>Description</entry>
3244
+
</row>
3245
+
</thead>
3246
+
<tbody>
3247
+
<row>
3248
+
<entry>projectId</entry>
3249
+
<entry>string</entry>
3250
+
<entry>Required.</entry>
3251
+
</row>
3252
+
<row>
3253
+
<entry>location</entry>
3254
+
<entry>string</entry>
3255
+
<entry>Required.</entry>
3256
+
</row>
3257
+
<row>
3258
+
<entry>keyRing</entry>
3259
+
<entry>string</entry>
3260
+
<entry>Required.</entry>
3261
+
</row>
3262
+
<row>
3263
+
<entry>keyName</entry>
3264
+
<entry>string</entry>
3265
+
<entry>Required.</entry>
3266
+
</row>
3267
+
<row>
3268
+
<entry>keyVersion</entry>
3269
+
<entry>string</entry>
3270
+
<entry>Optional. A specific version of the named key. Defaults to using the key's primary version.</entry>
3271
+
</row>
3272
+
<row>
3273
+
<entry>endpoint</entry>
3274
+
<entry>string</entry>
3275
+
<entry>Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".</entry>
3276
+
</row>
3277
+
</tbody>
3278
+
</tgroup>
3279
+
</table>
3280
+
</para>
3281
+
<para xmlns="http://docbook.org/ns/docbook">
3282
+
<table>
3283
+
<title><literal>"kmip"</literal> provider options</title>
3284
+
<tgroup cols="3">
3285
+
<thead>
3286
+
<row>
3287
+
<entry>Option</entry>
3288
+
<entry>Type</entry>
3289
+
<entry>Description</entry>
3290
+
</row>
3291
+
</thead>
3292
+
<tbody>
3293
+
<row>
3294
+
<entry>keyId</entry>
3295
+
<entry>string</entry>
3296
+
<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>
3297
+
</row>
3298
+
<row>
3299
+
<entry>endpoint</entry>
3300
+
<entry>string</entry>
3301
+
<entry>Optional. Host with optional port.</entry>
3302
+
</row>
3303
+
<row>
3304
+
<entry>delegated</entry>
3305
+
<entry>bool</entry>
3306
+
<entry>Optional. If true, this key should be decrypted by the KMIP server.</entry>
3307
+
</row>
3308
+
</tbody>
3309
+
</tgroup>
3310
+
</table>
3311
+
</para>
3312
+
'>
3313
+
<!ENTITY mongodb.option.encryption.tlsOptions '
3314
+
<row xmlns="http://docbook.org/ns/docbook">
3315
+
<entry>tlsOptions</entry>
3316
+
<entry><type>array</type></entry>
3317
+
<entry>
3318
+
<para>
3319
+
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:
3320
+
</para>
3321
+
<programlisting role="javascript">
3322
+
<![CDATA[
3323
+
<provider>: {
3324
+
tlsCaFile: <optional string>,
3325
+
tlsCertificateKeyFile: <optional string>,
3326
+
tlsCertificateKeyFilePassword: <optional string>,
3327
+
tlsDisableOCSPEndpointCheck: <optional bool>
3328
+
}
3329
+
]]>
3330
+
</programlisting>
3331
+
</entry>
3332
+
</row>
3333
+
'>
3334
+
<!ENTITY mongodb.option.maxCommitTimeMS '
3335
+
<row xmlns="http://docbook.org/ns/docbook">
3336
+
<entry>maxCommitTimeMS</entry>
3337
+
<entry>integer</entry>
3338
+
<entry>
3339
+
<para>
3340
+
The maximum amount of time in milliseconds to allow a single
3341
+
<literal>commitTransaction</literal> command to run.
3342
+
</para>
3343
+
<para>
3344
+
If specified, <literal>maxCommitTimeMS</literal> must be a signed
3345
+
32-bit integer greater than or equal to zero.
3346
+
</para>
3347
+
</entry>
3348
+
</row>
3349
+
'>
3350
+
<!ENTITY mongodb.option.readConcern '
3351
+
<row xmlns="http://docbook.org/ns/docbook">
3352
+
<entry>readConcern</entry>
3353
+
<entry><classname>MongoDB\Driver\ReadConcern</classname></entry>
3354
+
<entry>
3355
+
<para>
3356
+
A read concern to apply to the operation.
3357
+
</para>
3358
+
<para>
3359
+
This option is available in MongoDB 3.2+ and will result in an
3360
+
exception at execution time if specified for an older server
3361
+
version.
3362
+
</para>
3363
+
</entry>
3364
+
</row>
3365
+
'>
3366
+
<!ENTITY mongodb.option.readPreference '
3367
+
<row xmlns="http://docbook.org/ns/docbook">
3368
+
<entry>readPreference</entry>
3369
+
<entry><classname>MongoDB\Driver\ReadPreference</classname></entry>
3370
+
<entry>
3371
+
<para>
3372
+
A read preference to use for selecting a server for the operation.
3373
+
</para>
3374
+
</entry>
3375
+
</row>
3376
+
'>
3377
+
<!ENTITY mongodb.option.session '
3378
+
<row xmlns="http://docbook.org/ns/docbook">
3379
+
<entry>session</entry>
3380
+
<entry><classname>MongoDB\Driver\Session</classname></entry>
3381
+
<entry>
3382
+
<para>
3383
+
A session to associate with the operation.
3384
+
</para>
3385
+
</entry>
3386
+
</row>
3387
+
'>
3388
+
<!ENTITY mongodb.option.transactionReadWriteConcern '
3389
+
<warning xmlns="http://docbook.org/ns/docbook">
3390
+
<para>
3391
+
If you are using a <literal>"session"</literal> which has a transaction
3392
+
in progress, you cannot specify a <literal>"readConcern"</literal> or
3393
+
<literal>"writeConcern"</literal> option. This will result in an
3394
+
<classname>MongoDB\Driver\Exception\InvalidArgumentException</classname>
3395
+
being thrown. Instead, you should set these two options when you create
3396
+
the transaction with
3397
+
<methodname>MongoDB\Driver\Session::startTransaction</methodname>.
3398
+
</para>
3399
+
</warning>
3400
+
'>
3401
+
<!ENTITY mongodb.option.writeConcern '
3402
+
<row xmlns="http://docbook.org/ns/docbook">
3403
+
<entry>writeConcern</entry>
3404
+
<entry><classname>MongoDB\Driver\WriteConcern</classname></entry>
3405
+
<entry>
3406
+
<para>
3407
+
A write concern to apply to the operation.
3408
+
</para>
3409
+
</entry>
3410
+
</row>
3411
+
'>
3412
+
<!ENTITY mongodb.parameter.namespace '
3413
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3414
+
<term><parameter>namespace</parameter> (<type>string</type>)</term>
3415
+
<listitem>
3416
+
<para>
3417
+
A fully qualified namespace (e.g. <literal>"databaseName.collectionName"</literal>).
3418
+
</para>
3419
+
</listitem>
3420
+
</varlistentry>
3421
+
'>
3422
+
<!ENTITY mongodb.parameter.db '
3423
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3424
+
<term><parameter>db</parameter> (<type>string</type>)</term>
3425
+
<listitem>
3426
+
<para>
3427
+
The name of the database on which to execute the command.
3428
+
</para>
3429
+
</listitem>
3430
+
</varlistentry>
3431
+
'>
3432
+
<!ENTITY mongodb.parameter.bulkwrite '
3433
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3434
+
<term><parameter>bulk</parameter> (<classname>MongoDB\Driver\BulkWrite</classname>)</term>
3435
+
<listitem>
3436
+
<para>
3437
+
The write(s) to execute.
3438
+
</para>
3439
+
</listitem>
3440
+
</varlistentry>
3441
+
'>
3442
+
<!ENTITY mongodb.parameter.bulkwritecommand '
3443
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3444
+
<term><parameter>bulk</parameter> (<classname>MongoDB\Driver\BulkWriteCommand</classname>)</term>
3445
+
<listitem>
3446
+
<para>
3447
+
The write(s) to execute.
3448
+
</para>
3449
+
</listitem>
3450
+
</varlistentry>
3451
+
'>
3452
+
<!ENTITY mongodb.parameter.command '
3453
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3454
+
<term><parameter>command</parameter> (<classname>MongoDB\Driver\Command</classname>)</term>
3455
+
<listitem>
3456
+
<para>
3457
+
The command to execute.
3458
+
</para>
3459
+
</listitem>
3460
+
</varlistentry>
3461
+
'>
3462
+
<!ENTITY mongodb.parameter.encryptOpts '
3463
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3464
+
<term><parameter>options</parameter></term>
3465
+
<listitem>
3466
+
<para>
3467
+
<table>
3468
+
<title>Encryption options</title>
3469
+
<tgroup cols="3">
3470
+
<thead>
3471
+
<row>
3472
+
<entry>Option</entry>
3473
+
<entry>Type</entry>
3474
+
<entry>Description</entry>
3475
+
</row>
3476
+
</thead>
3477
+
<tbody>
3478
+
<row>
3479
+
<entry>algorithm</entry>
3480
+
<entry><type>string</type></entry>
3481
+
<entry>
3482
+
<para>
3483
+
The encryption algorithm to be used. This option is required.
3484
+
Specify one of the following
3485
+
<link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
3486
+
</para>
3487
+
<simplelist>
3488
+
<member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC</constant></member>
3489
+
<member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM</constant></member>
3490
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant></member>
3491
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED</constant></member>
3492
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant></member>
3493
+
</simplelist>
3494
+
</entry>
3495
+
</row>
3496
+
<row>
3497
+
<entry>contentionFactor</entry>
3498
+
<entry><type>int</type></entry>
3499
+
<entry>
3500
+
<para>
3501
+
The contention factor for evaluating queries with indexed, encrypted
3502
+
payloads.
3503
+
</para>
3504
+
<para>
3505
+
This option only applies and may only be specified when
3506
+
<literal>algorithm</literal> is
3507
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
3508
+
or
3509
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant>.
3510
+
</para>
3511
+
</entry>
3512
+
</row>
3513
+
<row>
3514
+
<entry>keyAltName</entry>
3515
+
<entry><type>string</type></entry>
3516
+
<entry>
3517
+
<para>
3518
+
Identifies a key vault collection document by
3519
+
<literal>keyAltName</literal>. This option is mutually exclusive
3520
+
with <literal>keyId</literal> and exactly one is required.
3521
+
</para>
3522
+
</entry>
3523
+
</row>
3524
+
<row>
3525
+
<entry>keyId</entry>
3526
+
<entry><classname>MongoDB\BSON\Binary</classname></entry>
3527
+
<entry>
3528
+
<para>
3529
+
Identifies a data key by <literal>_id</literal>. The value is a UUID
3530
+
(binary subtype 4). This option is mutually exclusive with
3531
+
<literal>keyAltName</literal> and exactly one is required.
3532
+
</para>
3533
+
</entry>
3534
+
</row>
3535
+
<row>
3536
+
<entry>queryType</entry>
3537
+
<entry><type>string</type></entry>
3538
+
<entry>
3539
+
<para>
3540
+
The query type for evaluating queries with indexed, encrypted
3541
+
payloads. Specify one of the following
3542
+
<link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
3543
+
</para>
3544
+
<simplelist>
3545
+
<member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY</constant></member>
3546
+
<member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE</constant></member>
3547
+
</simplelist>
3548
+
<para>
3549
+
This option only applies and may only be specified when
3550
+
<literal>algorithm</literal> is
3551
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
3552
+
or <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant>.
3553
+
</para>
3554
+
</entry>
3555
+
</row>
3556
+
<row>
3557
+
<entry>rangeOpts</entry>
3558
+
<entry><type>array</type></entry>
3559
+
<entry>
3560
+
<para>
3561
+
Index options for a queryable encryption field supporting "range"
3562
+
queries. The options below must match the values set in the
3563
+
<literal>encryptedFields</literal> of the target collection. For
3564
+
double and decimal128 BSON field types, <literal>min</literal>,
3565
+
<literal>max</literal>, and <literal>precision</literal> must all be
3566
+
set, or all be unset.
3567
+
</para>
3568
+
<para>
3569
+
<table>
3570
+
<title>Range index options</title>
3571
+
<tgroup cols="3">
3572
+
<thead>
3573
+
<row>
3574
+
<entry>Option</entry>
3575
+
<entry>Type</entry>
3576
+
<entry>Description</entry>
3577
+
</row>
3578
+
</thead>
3579
+
<tbody>
3580
+
<row>
3581
+
<entry>min</entry>
3582
+
<entry><type>mixed</type></entry>
3583
+
<entry>
3584
+
Required if <literal>precision</literal> is set. The minimum
3585
+
BSON value of the range.
3586
+
</entry>
3587
+
</row>
3588
+
<row>
3589
+
<entry>max</entry>
3590
+
<entry><type>mixed</type></entry>
3591
+
<entry>
3592
+
Required if <literal>precision</literal> is set. The maximum
3593
+
BSON value of the range.
3594
+
</entry>
3595
+
</row>
3596
+
<row>
3597
+
<entry>sparsity</entry>
3598
+
<entry><type>int</type></entry>
3599
+
<entry>Optional. Positive 64-bit integer.</entry>
3600
+
</row>
3601
+
<row>
3602
+
<entry>precision</entry>
3603
+
<entry><type>int</type></entry>
3604
+
<entry>
3605
+
Optional. Positive 32-bit integer specifying precision to use
3606
+
for explicit encryption. May only be set for double or
3607
+
decimal128 BSON field types.
3608
+
</entry>
3609
+
</row>
3610
+
<row>
3611
+
<entry>trimFactor</entry>
3612
+
<entry><type>int</type></entry>
3613
+
<entry>Optional. Positive 32-bit integer.</entry>
3614
+
</row>
3615
+
</tbody>
3616
+
</tgroup>
3617
+
</table>
3618
+
</para>
3619
+
</entry>
3620
+
</row>
3621
+
</tbody>
3622
+
</tgroup>
3623
+
</table>
3624
+
</para>
3625
+
</listitem>
3626
+
</varlistentry>
3627
+
'>
3628
+
<!ENTITY mongodb.parameter.query '
3629
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3630
+
<term><parameter>query</parameter> (<classname>MongoDB\Driver\Query</classname>)</term>
3631
+
<listitem>
3632
+
<para>
3633
+
The query to execute.
3634
+
</para>
3635
+
</listitem>
3636
+
</varlistentry>
3637
+
'>
3638
+
<!ENTITY mongodb.parameter.typeMap '
3639
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3640
+
<term><parameter>typeMap</parameter> (<type>array</type>)</term>
3641
+
<listitem>
3642
+
<para>
3643
+
<link linkend="mongodb.persistence.typemaps">Type map configuration</link>.
3644
+
</para>
3645
+
</listitem>
3646
+
</varlistentry>
3647
+
'>
3648
+
<!ENTITY mongodb.parameter.filter '
3649
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3650
+
<term><parameter>filter</parameter> (<type class="union"><type>array</type><type>object</type></type>)</term>
3651
+
<listitem>
3652
+
<para>
3653
+
The <link xlink:href="&url.mongodb.docs;tutorial/query-documents/" xmlns:xlink="http://www.w3.org/1999/xlink">query predicate</link>.
3654
+
An empty predicate will match all documents in the collection.
3655
+
</para>
3656
+
<note>
3657
+
<simpara>
3658
+
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="mongodb.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>).
3659
+
</simpara>
3660
+
</note>
3661
+
</listitem>
3662
+
</varlistentry>
3663
+
'>
3664
+
<!ENTITY mongodb.returns.cursor '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\Cursor</classname> on success.</para>'>
3665
+
<!ENTITY mongodb.returns.writeresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\WriteResult</classname> on success.</para>'>
3666
+
<!ENTITY mongodb.returns.bulkwritecommandresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\BulkWriteCommandResult</classname> on success.</para>'>
3667
+
<!ENTITY mongodb.throws.std '&mongodb.throws.argumentparsing;&mongodb.throws.connection;&mongodb.throws.authentication;'>
3668
+
<!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>'>
3669
+
<!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>'>
3670
+
<!ENTITY mongodb.throws.bulkwritecommandexception '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname> on any write failure (e.g. command failure, write or write concern error)</member>'>
3671
+
<!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>'>
3672
+
<!ENTITY mongodb.throws.argumentparsing '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> on argument parsing errors.</member>'>
3673
+
<!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>'>
3674
+
<!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>'>
3675
+
<!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>'>
3676
+
<!ENTITY mongodb.throws.unacknowledged '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\LogicException</classname> if the write was not acknowledged.</member>'>
3677
+
3678
+
<!-- Not used in EN anymore -->
3679
+
<!ENTITY mongodb.note.queryable-encryption-preview ''>
3680
+
3681
+
<!ENTITY mongodb.note.decimal128 '
3682
+
<note xmlns="http://docbook.org/ns/docbook">
3683
+
<simpara>
3684
+
<classname>MongoDB\BSON\Decimal128</classname> is only compatible with
3685
+
MongoDB 3.4+. Attempting to use the BSON type with an earlier version of
3686
+
MongoDB will result in an error.
3687
+
</simpara>
3688
+
</note>
3689
+
'>
3690
+
<!ENTITY mongodb.note.extended-json '
3691
+
<note xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3692
+
<simpara>
3693
+
The output is consistent with the <function>MongoDB\BSON\toJSON</function>
3694
+
function, which uses the driver-specific legacy extended JSON format. This
3695
+
does not necessarily match the
3696
+
<link xlink:href="&url.mongodb.specs.extendedjson;#relaxed-extended-json-example">relaxed</link>
3697
+
or <link xlink:href="&url.mongodb.specs.extendedjson;#canonical-extended-json-example">canonical</link>
3698
+
extended JSON representations used by
3699
+
<function>MongoDB\BSON\toRelaxedExtendedJSON</function> and
3700
+
<function>MongoDB\BSON\toCanonicalExtendedJSON</function>, respectively.
3701
+
</simpara>
3702
+
</note>
3703
+
'>
3704
+
<!ENTITY mongodb.note.forking '
3705
+
<note xmlns="http://docbook.org/ns/docbook">
3706
+
<simpara>
3707
+
On Unix platforms, the extension is sensitive to scripts that use the
3708
+
fork() system call without also calling exec(). Users are advised not to
3709
+
re-use <classname>MongoDB\Driver\Manager</classname> instances in a forked
3710
+
child process.
3711
+
</simpara>
3712
+
</note>
3713
+
'>
3714
+
3715
+
<!ENTITY mongodb.note.uint32 '
3716
+
<note xmlns="http://docbook.org/ns/docbook">
3717
+
<simpara>
3718
+
Because PHP's integer type is signed, some values returned by this
3719
+
method may appear as negative integers on 32-bit platforms. The
3720
+
<literal>"%u"</literal> formatter of <function>sprintf</function> may be
3721
+
used to obtain a string representation of the unsigned decimal value.
3722
+
</simpara>
3723
+
</note>
3724
+
'>
3725
+
3726
+
<!ENTITY mongodb.note.server.readpreference '
3727
+
<note xmlns="http://docbook.org/ns/docbook">
3728
+
<simpara>
3729
+
The <literal>"readPreference"</literal> option does not control the server
3730
+
to which the driver issues the operation; it will always be executed on
3731
+
this server object. Instead, it may be used when issuing the operation to a
3732
+
secondary (from a replica set connection, not standalone) or mongos node to
3733
+
ensure that the driver sets the wire protocol accordingly or adds the read
3734
+
preference to the operation, respectively.
3735
+
</simpara>
3736
+
</note>
3737
+
'>
3738
+
3739
+
<!ENTITY mongodb.note.server.write '
3740
+
<note xmlns="http://docbook.org/ns/docbook">
3741
+
<simpara>
3742
+
It is the caller's responsibility to ensure that the server is capable
3743
+
of executing the write operation. For example, executing a write operation
3744
+
on a secondary (excluding its "local" database) will fail.
3745
+
</simpara>
3746
+
</note>
3747
+
'>
3748
+
3749
+
<!ENTITY mongodb.warning.duplicate-keys '
3750
+
<warning xmlns="http://docbook.org/ns/docbook">
3751
+
<simpara>
3752
+
BSON documents can technically contain duplicate keys because documents are
3753
+
stored as a list of key-value pairs; however, applications should refrain
3754
+
from generating documents with duplicate keys as server and driver behavior
3755
+
may be undefined. Since PHP objects and arrays cannot have duplicate keys,
3756
+
data could also be lost when decoding a BSON document with duplicate keys.
3757
+
</simpara>
3758
+
</warning>
3759
+
'>
3760
+
1804
3761
<!-- Radius -->
1805
3762
<!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>'>
1806
3763
<!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>'>
...
...
@@ -1811,43 +3768,635 @@ paths</simpara></warning>
1811
3768
1812
3769
<!-- posix snippets -->
1813
3770
<!ENTITY posix.parameter.fd '<varlistentry xmlns="http://docbook.org/ns/docbook">
1814
-
<term><parameter>fd</parameter></term>
3771
+
<term><parameter>file_descriptor</parameter></term>
1815
3772
<listitem>
1816
3773
<para>
1817
3774
The file descriptor, which is expected to be either a file
1818
-
<type>resource</type> or an <type>integer</type>. An <type>integer</type>
3775
+
<type>resource</type> or an <type>int</type>. An <type>int</type>
1819
3776
will be assumed to be a file descriptor that can be passed directly to
1820
3777
the underlying system call.
1821
3778
</para>
1822
-
<para>
1823
-
In almost all cases, you will want to provide a file <type>resource</type>.
1824
-
</para>
1825
3779
</listitem>
1826
3780
</varlistentry>'>
1827
3781
3782
+
<!ENTITY posix.rlimits '
3783
+
<para xmlns="http://docbook.org/ns/docbook">
3784
+
Each resource has an associated soft and hard limit. The soft
3785
+
limit is the value that the kernel enforces for the corresponding
3786
+
resource. The hard limit acts as a ceiling for the soft limit.
3787
+
An unprivileged process may only set its soft limit to a value
3788
+
from 0 to the hard limit, and irreversibly lower its hard limit.
3789
+
</para>
3790
+
'>
3791
+
1828
3792
<!-- strings snippets -->
3793
+
<!ENTITY strings.stripped.characters '
3794
+
<itemizedlist xmlns="http://docbook.org/ns/docbook">
3795
+
<listitem>
3796
+
<simpara>
3797
+
<literal>" "</literal>: <acronym>ASCII</acronym> <acronym>SP</acronym> character
3798
+
<literal>0x20</literal>, an ordinary space.
3799
+
</simpara>
3800
+
</listitem>
3801
+
<listitem>
3802
+
<simpara>
3803
+
<literal>"\t"</literal>: <acronym>ASCII</acronym> <acronym>HT</acronym> character
3804
+
<literal>0x09</literal>, a tab.
3805
+
</simpara>
3806
+
</listitem>
3807
+
<listitem>
3808
+
<simpara>
3809
+
<literal>"\n"</literal>: <acronym>ASCII</acronym> <acronym>LF</acronym> character
3810
+
<literal>0x0A</literal>, a new line (line feed).
3811
+
</simpara>
3812
+
</listitem>
3813
+
<listitem>
3814
+
<simpara>
3815
+
<literal>"\r"</literal>: <acronym>ASCII</acronym> <acronym>CR</acronym> character
3816
+
<literal>0x0D</literal>, a carriage return.
3817
+
</simpara>
3818
+
</listitem>
3819
+
<listitem>
3820
+
<simpara>
3821
+
<literal>"\0"</literal>: <acronym>ASCII</acronym> <acronym>NUL</acronym> character
3822
+
<literal>0x00</literal>, the NUL-byte.
3823
+
</simpara>
3824
+
</listitem>
3825
+
<listitem>
3826
+
<simpara>
3827
+
<literal>"\v"</literal>: <acronym>ASCII</acronym> <acronym>VT</acronym>
3828
+
character <literal>0x0B</literal>, a vertical tab.
3829
+
</simpara>
3830
+
</listitem>
3831
+
</itemizedlist>
3832
+
'>
3833
+
3834
+
<!ENTITY strings.stripped.unicode '
3835
+
<itemizedlist xmlns="http://docbook.org/ns/docbook">
3836
+
<listitem>
3837
+
<simpara>
3838
+
<literal>" "</literal> (<acronym>Unicode</acronym> U+0020), an ordinary space.
3839
+
</simpara>
3840
+
</listitem>
3841
+
<listitem>
3842
+
<simpara>
3843
+
<literal>"\t"</literal> (<acronym>Unicode</acronym> U+0009), a tab.
3844
+
</simpara>
3845
+
</listitem>
3846
+
<listitem>
3847
+
<simpara>
3848
+
<literal>"\n"</literal> (<acronym>Unicode</acronym> U+000A), a new line (line feed).
3849
+
</simpara>
3850
+
</listitem>
3851
+
<listitem>
3852
+
<simpara>
3853
+
<literal>"\r"</literal> (<acronym>Unicode</acronym> U+000D), a carriage return.
3854
+
</simpara>
3855
+
</listitem>
3856
+
<listitem>
3857
+
<simpara>
3858
+
<literal>"\0"</literal> (<acronym>Unicode</acronym> U+0000), the NUL-byte.
3859
+
</simpara>
3860
+
</listitem>
3861
+
<listitem>
3862
+
<simpara>
3863
+
<literal>"\v"</literal> (<acronym>Unicode</acronym> U+000B), a vertical tab.
3864
+
</simpara>
3865
+
</listitem>
3866
+
<listitem>
3867
+
<simpara>
3868
+
<literal>"\f"</literal> (<acronym>Unicode</acronym> U+000C), a form feed.
3869
+
</simpara>
3870
+
</listitem>
3871
+
<listitem>
3872
+
<simpara>
3873
+
<literal>"\u00A0"</literal> (<acronym>Unicode</acronym> U+00A0), a NO-BREAK SPACE.
3874
+
</simpara>
3875
+
</listitem>
3876
+
<listitem>
3877
+
<simpara>
3878
+
<literal>"\u1680"</literal> (<acronym>Unicode</acronym> U+1680), a OGHAM SPACE MARK.
3879
+
</simpara>
3880
+
</listitem>
3881
+
<listitem>
3882
+
<simpara>
3883
+
<literal>"\u2000"</literal> (<acronym>Unicode</acronym> U+2000), a EN QUAD.
3884
+
</simpara>
3885
+
</listitem>
3886
+
<listitem>
3887
+
<simpara>
3888
+
<literal>"\u2001"</literal> (<acronym>Unicode</acronym> U+2001), a EM QUAD.
3889
+
</simpara>
3890
+
</listitem>
3891
+
<listitem>
3892
+
<simpara>
3893
+
<literal>"\u2002"</literal> (<acronym>Unicode</acronym> U+2002), a EN SPACE.
3894
+
</simpara>
3895
+
</listitem>
3896
+
<listitem>
3897
+
<simpara>
3898
+
<literal>"\u2003"</literal> (<acronym>Unicode</acronym> U+2003), a EM SPACE.
3899
+
</simpara>
3900
+
</listitem>
3901
+
<listitem>
3902
+
<simpara>
3903
+
<literal>"\u2004"</literal> (<acronym>Unicode</acronym> U+2004), a THREE-PER-EM SPACE.
3904
+
</simpara>
3905
+
</listitem>
3906
+
<listitem>
3907
+
<simpara>
3908
+
<literal>"\u2005"</literal> (<acronym>Unicode</acronym> U+2005), a FOUR-PER-EM SPACE.
3909
+
</simpara>
3910
+
</listitem>
3911
+
<listitem>
3912
+
<simpara>
3913
+
<literal>"\u2006"</literal> (<acronym>Unicode</acronym> U+2006), a SIX-PER-EM SPACE.
3914
+
</simpara>
3915
+
</listitem>
3916
+
<listitem>
3917
+
<simpara>
3918
+
<literal>"\u2007"</literal> (<acronym>Unicode</acronym> U+2007), a FIGURE SPACE.
3919
+
</simpara>
3920
+
</listitem>
3921
+
<listitem>
3922
+
<simpara>
3923
+
<literal>"\u2008"</literal> (<acronym>Unicode</acronym> U+2008), a PUNCTUATION SPACE.
3924
+
</simpara>
3925
+
</listitem>
3926
+
<listitem>
3927
+
<simpara>
3928
+
<literal>"\u2009"</literal> (<acronym>Unicode</acronym> U+2009), a THIN SPACE.
3929
+
</simpara>
3930
+
</listitem>
3931
+
<listitem>
3932
+
<simpara>
3933
+
<literal>"\u200A"</literal> (<acronym>Unicode</acronym> U+200A), a HAIR SPACE.
3934
+
</simpara>
3935
+
</listitem>
3936
+
<listitem>
3937
+
<simpara>
3938
+
<literal>"\u2028"</literal> (<acronym>Unicode</acronym> U+2028), a LINE SEPARATOR.
3939
+
</simpara>
3940
+
</listitem>
3941
+
<listitem>
3942
+
<simpara>
3943
+
<literal>"\u2029"</literal> (<acronym>Unicode</acronym> U+2029), a PARAGRAPH SEPARATOR.
3944
+
</simpara>
3945
+
</listitem>
3946
+
<listitem>
3947
+
<simpara>
3948
+
<literal>"\u202F"</literal> (<acronym>Unicode</acronym> U+202F), a NARROW NO-BREAK SPACE.
3949
+
</simpara>
3950
+
</listitem>
3951
+
<listitem>
3952
+
<simpara>
3953
+
<literal>"\u205F"</literal> (<acronym>Unicode</acronym> U+205F), a MEDIUM MATHEMATICAL SPACE.
3954
+
</simpara>
3955
+
</listitem>
3956
+
<listitem>
3957
+
<simpara>
3958
+
<literal>"\u3000"</literal> (<acronym>Unicode</acronym> U+3000), a IDEOGRAPHIC SPACE.
3959
+
</simpara>
3960
+
</listitem>
3961
+
<listitem>
3962
+
<simpara>
3963
+
<literal>"\u0085"</literal> (<acronym>Unicode</acronym> U+0085), a NEXT LINE (NEL).
3964
+
</simpara>
3965
+
</listitem>
3966
+
<listitem>
3967
+
<simpara>
3968
+
<literal>"\u180E"</literal> (<acronym>Unicode</acronym> U+180E), a MONGOLIAN VOWEL SEPARATOR.
3969
+
</simpara>
3970
+
</listitem>
3971
+
</itemizedlist>
3972
+
'>
3973
+
3974
+
<!ENTITY strings.parameter.characters.optional '
3975
+
<simpara xmlns="http://docbook.org/ns/docbook">
3976
+
Optionally, the stripped characters can also be specified using
3977
+
the <parameter>characters</parameter> parameter.
3978
+
Simply list all characters that need to be stripped.
3979
+
With <literal>..</literal> it is possible to specify an incrementing range of characters.
3980
+
</simpara>
3981
+
'>
3982
+
3983
+
<!ENTITY strings.parameter.unicode.optional '
3984
+
<simpara xmlns="http://docbook.org/ns/docbook">
3985
+
Optionally, the stripped characters can also be specified using
3986
+
the <parameter>characters</parameter> parameter.
3987
+
Simply list all characters that need to be stripped.
3988
+
</simpara>
3989
+
'>
3990
+
1829
3991
<!ENTITY strings.parameter.encoding '
1830
3992
<para xmlns="http://docbook.org/ns/docbook">
1831
3993
An optional argument defining the encoding used when converting characters.
1832
3994
</para>
1833
3995
1834
3996
<para xmlns="http://docbook.org/ns/docbook">
1835
-
If omitted, the default value of the <parameter>encoding</parameter> varies
1836
-
depending on the PHP version in use. In PHP 5.6 and later, the
3997
+
If omitted, <parameter>encoding</parameter> defaults to the value of the
1837
3998
<link linkend="ini.default-charset">default_charset</link> configuration
1838
-
option is used as the default value. PHP 5.4 and 5.5 will use
1839
-
<literal>UTF-8</literal> as the default. Earlier versions of PHP use
1840
-
<literal>ISO-8859-1</literal>.
3999
+
option.
1841
4000
</para>
1842
4001
1843
4002
<para xmlns="http://docbook.org/ns/docbook">
1844
4003
Although this argument is technically optional, you are highly encouraged to
1845
-
specify the correct value for your code if you are using PHP 5.5 or earlier,
1846
-
or if your <link linkend="ini.default-charset">default_charset</link>
4004
+
specify the correct value for your code
4005
+
if the <link linkend="ini.default-charset">default_charset</link>
1847
4006
configuration option may be set incorrectly for the given input.
1848
4007
</para>
1849
4008
'>
1850
4009
4010
+
<!ENTITY strings.parameter.format '
4011
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
4012
+
<term><parameter>format</parameter></term>
4013
+
<listitem>
4014
+
<para>
4015
+
The format string is composed of zero or more directives:
4016
+
ordinary characters (excluding <literal>%</literal>) that are
4017
+
copied directly to the result and <emphasis>conversion
4018
+
specifications</emphasis>, each of which results in fetching its
4019
+
own parameter.
4020
+
</para>
4021
+
4022
+
<para>
4023
+
A conversion specification follows this prototype:
4024
+
<literal>%[argnum$][flags][width][.precision]specifier</literal>.
4025
+
</para>
4026
+
4027
+
<formalpara>
4028
+
<title>Argnum</title>
4029
+
<para>
4030
+
An integer followed by a dollar sign <literal>$</literal>,
4031
+
to specify which number argument to treat in the conversion.
4032
+
</para>
4033
+
</formalpara>
4034
+
4035
+
<formalpara>
4036
+
<title>Flags</title>
4037
+
<para>
4038
+
<informaltable>
4039
+
<tgroup cols="2">
4040
+
<thead>
4041
+
<row>
4042
+
<entry>Flag</entry>
4043
+
<entry>&Description;</entry>
4044
+
</row>
4045
+
</thead>
4046
+
<tbody>
4047
+
<row>
4048
+
<entry><literal>-</literal></entry>
4049
+
<entry>
4050
+
Left-justify within the given field width;
4051
+
Right justification is the default
4052
+
</entry>
4053
+
</row>
4054
+
<row>
4055
+
<entry><literal>+</literal></entry>
4056
+
<entry>
4057
+
Prefix positive numbers with a plus sign
4058
+
<literal>+</literal>; Default only negative
4059
+
are prefixed with a negative sign.
4060
+
</entry>
4061
+
</row>
4062
+
<row>
4063
+
<entry><literal> </literal>(space)</entry>
4064
+
<entry>
4065
+
Pads the result with spaces.
4066
+
This is the default.
4067
+
</entry>
4068
+
</row>
4069
+
<row>
4070
+
<entry><literal>0</literal></entry>
4071
+
<entry>
4072
+
Only left-pads numbers with zeros.
4073
+
With <literal>s</literal> specifiers this can
4074
+
also right-pad with zeros.
4075
+
</entry>
4076
+
</row>
4077
+
<row>
4078
+
<entry><literal>'</literal>(char)</entry>
4079
+
<entry>
4080
+
Pads the result with the character (char).
4081
+
</entry>
4082
+
</row>
4083
+
</tbody>
4084
+
</tgroup>
4085
+
</informaltable>
4086
+
</para>
4087
+
</formalpara>
4088
+
4089
+
<formalpara>
4090
+
<title>Width</title>
4091
+
<para>
4092
+
Either an integer that says how many characters (minimum)
4093
+
this conversion should result in, or <literal>*</literal>.
4094
+
If <literal>*</literal> is used, then the width is supplied
4095
+
as an additional integer value preceding the one formatted
4096
+
by the specifier.
4097
+
</para>
4098
+
</formalpara>
4099
+
4100
+
<formalpara>
4101
+
<title>Precision</title>
4102
+
<para>
4103
+
A period <literal>.</literal> optionally followed by
4104
+
either an integer or <literal>*</literal>,
4105
+
whose meaning depends on the specifier:
4106
+
<itemizedlist>
4107
+
<listitem>
4108
+
<simpara>
4109
+
For <literal>e</literal>, <literal>E</literal>,
4110
+
<literal>f</literal> and <literal>F</literal>
4111
+
specifiers: this is the number of digits to be printed
4112
+
after the decimal point (by default, this is 6).
4113
+
</simpara>
4114
+
</listitem>
4115
+
<listitem>
4116
+
<simpara>
4117
+
For <literal>g</literal>, <literal>G</literal>,
4118
+
<literal>h</literal> and <literal>H</literal>
4119
+
specifiers: this is the maximum number of significant
4120
+
digits to be printed.
4121
+
</simpara>
4122
+
</listitem>
4123
+
<listitem>
4124
+
<simpara>
4125
+
For <literal>s</literal> specifier: it acts as a cutoff point,
4126
+
setting a maximum character limit to the string.
4127
+
</simpara>
4128
+
</listitem>
4129
+
</itemizedlist>
4130
+
<note>
4131
+
<simpara>
4132
+
If the period is specified without an explicit value for precision,
4133
+
0 is assumed. If <literal>*</literal> is used, the precision is
4134
+
supplied as an additional integer value preceding the one formatted
4135
+
by the specifier.
4136
+
</simpara>
4137
+
</note>
4138
+
</para>
4139
+
</formalpara>
4140
+
4141
+
<para>
4142
+
<table>
4143
+
<title>Specifiers</title>
4144
+
<tgroup cols="2">
4145
+
<thead>
4146
+
<row>
4147
+
<entry>Specifier</entry>
4148
+
<entry>&Description;</entry>
4149
+
</row>
4150
+
</thead>
4151
+
<tbody>
4152
+
<row>
4153
+
<entry><literal>%</literal></entry>
4154
+
<entry>
4155
+
A literal percent character. No argument is required.
4156
+
</entry>
4157
+
</row>
4158
+
<row>
4159
+
<entry><literal>b</literal></entry>
4160
+
<entry>
4161
+
The argument is treated as an integer and presented
4162
+
as a binary number.
4163
+
</entry>
4164
+
</row>
4165
+
<row>
4166
+
<entry><literal>c</literal></entry>
4167
+
<entry>
4168
+
The argument is treated as an integer and presented
4169
+
as the character with that ASCII.
4170
+
</entry>
4171
+
</row>
4172
+
<row>
4173
+
<entry><literal>d</literal></entry>
4174
+
<entry>
4175
+
The argument is treated as an integer and presented
4176
+
as a (signed) decimal number.
4177
+
</entry>
4178
+
</row>
4179
+
<row>
4180
+
<entry><literal>e</literal></entry>
4181
+
<entry>
4182
+
The argument is treated as scientific notation (e.g. 1.2e+2).
4183
+
</entry>
4184
+
</row>
4185
+
<row>
4186
+
<entry><literal>E</literal></entry>
4187
+
<entry>
4188
+
Like the <literal>e</literal> specifier but uses
4189
+
uppercase letter (e.g. 1.2E+2).
4190
+
</entry>
4191
+
</row>
4192
+
<row>
4193
+
<entry><literal>f</literal></entry>
4194
+
<entry>
4195
+
The argument is treated as a float and presented
4196
+
as a floating-point number (locale aware).
4197
+
</entry>
4198
+
</row>
4199
+
<row>
4200
+
<entry><literal>F</literal></entry>
4201
+
<entry>
4202
+
The argument is treated as a float and presented
4203
+
as a floating-point number (non-locale aware).
4204
+
</entry>
4205
+
</row>
4206
+
<row>
4207
+
<entry><literal>g</literal></entry>
4208
+
<entry>
4209
+
<para>
4210
+
General format.
4211
+
</para>
4212
+
<para>
4213
+
Let P equal the precision if nonzero, 6 if the precision is omitted,
4214
+
or 1 if the precision is zero.
4215
+
Then, if a conversion with style E would have an exponent of X:
4216
+
</para>
4217
+
<para>
4218
+
If P > X ≥ −4, the conversion is with style f and precision P − (X + 1).
4219
+
Otherwise, the conversion is with style e and precision P − 1.
4220
+
</para>
4221
+
</entry>
4222
+
</row>
4223
+
<row>
4224
+
<entry><literal>G</literal></entry>
4225
+
<entry>
4226
+
Like the <literal>g</literal> specifier but uses
4227
+
<literal>E</literal> and <literal>f</literal>.
4228
+
</entry>
4229
+
</row>
4230
+
<row>
4231
+
<entry><literal>h</literal></entry>
4232
+
<entry>
4233
+
Like the <literal>g</literal> specifier but uses <literal>F</literal>.
4234
+
Available as of PHP 8.0.0.
4235
+
</entry>
4236
+
</row>
4237
+
<row>
4238
+
<entry><literal>H</literal></entry>
4239
+
<entry>
4240
+
Like the <literal>g</literal> specifier but uses
4241
+
<literal>E</literal> and <literal>F</literal>. Available as of PHP 8.0.0.
4242
+
</entry>
4243
+
</row>
4244
+
<row>
4245
+
<entry><literal>o</literal></entry>
4246
+
<entry>
4247
+
The argument is treated as an integer and presented
4248
+
as an octal number.
4249
+
</entry>
4250
+
</row>
4251
+
<row>
4252
+
<entry><literal>s</literal></entry>
4253
+
<entry>
4254
+
The argument is treated and presented as a string.
4255
+
</entry>
4256
+
</row>
4257
+
<row>
4258
+
<entry><literal>u</literal></entry>
4259
+
<entry>
4260
+
The argument is treated as an integer and presented
4261
+
as an unsigned decimal number.
4262
+
</entry>
4263
+
</row>
4264
+
<row>
4265
+
<entry><literal>x</literal></entry>
4266
+
<entry>
4267
+
The argument is treated as an integer and presented
4268
+
as a hexadecimal number (with lowercase letters).
4269
+
</entry>
4270
+
</row>
4271
+
<row>
4272
+
<entry><literal>X</literal></entry>
4273
+
<entry>
4274
+
The argument is treated as an integer and presented
4275
+
as a hexadecimal number (with uppercase letters).
4276
+
</entry>
4277
+
</row>
4278
+
</tbody>
4279
+
</tgroup>
4280
+
</table>
4281
+
</para>
4282
+
4283
+
<warning>
4284
+
<para>
4285
+
The <literal>c</literal> type specifier ignores padding and width.
4286
+
</para>
4287
+
</warning>
4288
+
4289
+
<warning>
4290
+
<para>
4291
+
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.
4292
+
</para>
4293
+
</warning>
4294
+
4295
+
<para>
4296
+
Variables will be co-erced to a suitable type for the specifier:
4297
+
<table>
4298
+
<title>Type Handling</title>
4299
+
<tgroup cols="2">
4300
+
<thead>
4301
+
<row>
4302
+
<entry>Type</entry>
4303
+
<entry>Specifiers</entry>
4304
+
</row>
4305
+
</thead>
4306
+
<tbody>
4307
+
<row>
4308
+
<entry><type>string</type></entry>
4309
+
<entry><literal>s</literal></entry>
4310
+
</row>
4311
+
<row>
4312
+
<entry><type>int</type></entry>
4313
+
<entry>
4314
+
<literal>d</literal>,
4315
+
<literal>u</literal>,
4316
+
<literal>c</literal>,
4317
+
<literal>o</literal>,
4318
+
<literal>x</literal>,
4319
+
<literal>X</literal>,
4320
+
<literal>b</literal>
4321
+
</entry>
4322
+
</row>
4323
+
<row>
4324
+
<entry><type>float</type></entry>
4325
+
<entry>
4326
+
<literal>e</literal>,
4327
+
<literal>E</literal>,
4328
+
<literal>f</literal>,
4329
+
<literal>F</literal>,
4330
+
<literal>g</literal>,
4331
+
<literal>G</literal>,
4332
+
<literal>h</literal>,
4333
+
<literal>H</literal>
4334
+
</entry>
4335
+
</row>
4336
+
</tbody>
4337
+
</tgroup>
4338
+
</table>
4339
+
</para>
4340
+
</listitem>
4341
+
</varlistentry>
4342
+
'>
4343
+
4344
+
<!ENTITY strings.scanf.parameter.format '
4345
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
4346
+
<term><parameter>format</parameter></term>
4347
+
<listitem>
4348
+
<para>
4349
+
The interpreted format for <parameter>string</parameter>, which is
4350
+
described in the documentation for <function>sprintf</function> with
4351
+
following differences:
4352
+
<simplelist>
4353
+
<member>
4354
+
Function is not locale-aware.
4355
+
</member>
4356
+
<member>
4357
+
<literal>F</literal>, <literal>g</literal>, <literal>G</literal> and
4358
+
<literal>b</literal> are not supported.
4359
+
</member>
4360
+
<member>
4361
+
<literal>D</literal> stands for decimal number.
4362
+
</member>
4363
+
<member>
4364
+
<literal>i</literal> stands for integer with base detection.
4365
+
</member>
4366
+
<member>
4367
+
<literal>n</literal> stands for number of characters processed so far.
4368
+
</member>
4369
+
<member>
4370
+
<literal>s</literal> stops reading at any whitespace character.
4371
+
</member>
4372
+
<member>
4373
+
<literal>*</literal> instead of <literal>argnum$</literal> suppresses
4374
+
the assignment of this conversion specification.
4375
+
</member>
4376
+
</simplelist>
4377
+
</para>
4378
+
</listitem>
4379
+
</varlistentry>
4380
+
'>
4381
+
4382
+
<!ENTITY strings.parameter.needle.non-string '
4383
+
<para xmlns="http://docbook.org/ns/docbook">
4384
+
Prior to PHP 8.0.0, if <parameter>needle</parameter> is not a string, it is converted
4385
+
to an integer and applied as the ordinal value of a character.
4386
+
This behavior is deprecated as of PHP 7.3.0, and relying on it is highly
4387
+
discouraged. Depending on the intended behavior, the
4388
+
<parameter>needle</parameter> should either be explicitly cast to string,
4389
+
or an explicit call to <function>chr</function> should be performed.
4390
+
</para>
4391
+
'>
4392
+
4393
+
<!ENTITY strings.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
4394
+
<entry>8.0.0</entry>
4395
+
<entry>
4396
+
<parameter>needle</parameter> now accepts an empty string.
4397
+
</entry>
4398
+
</row>'>
4399
+
1851
4400
<!ENTITY strings.changelog.encoding '
1852
4401
<row xmlns="http://docbook.org/ns/docbook">
1853
4402
<entry>5.6.0</entry>
...
...
@@ -1860,25 +4409,377 @@ paths</simpara></warning>
1860
4409
</row>
1861
4410
'>
1862
4411
4412
+
<!ENTITY strings.changelog.ascii-case-conversion '
4413
+
<row xmlns="http://docbook.org/ns/docbook">
4414
+
<entry>8.2.0</entry>
4415
+
<entry>
4416
+
Case conversion no longer depends on the locale set with
4417
+
<function>setlocale</function>. Only ASCII characters will be converted.
4418
+
</entry>
4419
+
</row>
4420
+
'>
4421
+
4422
+
<!ENTITY strings.changelog.ascii-case-folding '
4423
+
<row xmlns="http://docbook.org/ns/docbook">
4424
+
<entry>8.2.0</entry>
4425
+
<entry>
4426
+
Case folding no longer depends on the locale set with
4427
+
<function>setlocale</function>. Only ASCII case folding will be done.
4428
+
Non-ASCII bytes will be compared by their byte value.
4429
+
</entry>
4430
+
</row>
4431
+
'>
4432
+
4433
+
<!ENTITY strings.changelog.sprintf '
4434
+
<informaltable xmlns="http://docbook.org/ns/docbook">
4435
+
<tgroup cols="2">
4436
+
<thead>
4437
+
<row>
4438
+
<entry>&Version;</entry>
4439
+
<entry>&Description;</entry>
4440
+
</row>
4441
+
</thead>
4442
+
<tbody>
4443
+
<row>
4444
+
<entry>8.0.0</entry>
4445
+
<entry>
4446
+
This function no longer returns &false; on failure.
4447
+
</entry>
4448
+
</row>
4449
+
<row>
4450
+
<entry>8.0.0</entry>
4451
+
<entry>
4452
+
Throw a <classname>ValueError</classname> if the number of arguments is zero;
4453
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4454
+
</entry>
4455
+
</row>
4456
+
<row>
4457
+
<entry>8.0.0</entry>
4458
+
<entry>
4459
+
Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4460
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4461
+
</entry>
4462
+
</row>
4463
+
<row>
4464
+
<entry>8.0.0</entry>
4465
+
<entry>
4466
+
Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4467
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4468
+
</entry>
4469
+
</row>
4470
+
<row>
4471
+
<entry>8.0.0</entry>
4472
+
<entry>
4473
+
Throw a <classname>ArgumentCountError</classname> when less arguments are given than required;
4474
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4475
+
</entry>
4476
+
</row>
4477
+
</tbody>
4478
+
</tgroup>
4479
+
</informaltable>
4480
+
'>
4481
+
4482
+
<!ENTITY strings.changelog.vsprintf '
4483
+
<informaltable xmlns="http://docbook.org/ns/docbook">
4484
+
<tgroup cols="2">
4485
+
<thead>
4486
+
<row>
4487
+
<entry>&Version;</entry>
4488
+
<entry>&Description;</entry>
4489
+
</row>
4490
+
</thead>
4491
+
<tbody>
4492
+
<row>
4493
+
<entry>8.0.0</entry>
4494
+
<entry>
4495
+
This function no longer returns &false; on failure.
4496
+
</entry>
4497
+
</row>
4498
+
<row>
4499
+
<entry>8.0.0</entry>
4500
+
<entry>
4501
+
Throw a <classname>ValueError</classname> if the number of arguments is zero;
4502
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4503
+
</entry>
4504
+
</row>
4505
+
<row>
4506
+
<entry>8.0.0</entry>
4507
+
<entry>
4508
+
Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4509
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4510
+
</entry>
4511
+
</row>
4512
+
<row>
4513
+
<entry>8.0.0</entry>
4514
+
<entry>
4515
+
Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4516
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4517
+
</entry>
4518
+
</row>
4519
+
<row>
4520
+
<entry>8.0.0</entry>
4521
+
<entry>
4522
+
Throw a <classname>ValueError</classname> when less arguments are given than required;
4523
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4524
+
</entry>
4525
+
</row>
4526
+
</tbody>
4527
+
</tgroup>
4528
+
</informaltable>
4529
+
'>
4530
+
4531
+
<!ENTITY strings.errors.sprintf '
4532
+
<para xmlns="http://docbook.org/ns/docbook">
4533
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
4534
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4535
+
</para>
4536
+
<para xmlns="http://docbook.org/ns/docbook">
4537
+
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>.
4538
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4539
+
</para>
4540
+
<para xmlns="http://docbook.org/ns/docbook">
4541
+
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>.
4542
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4543
+
</para>
4544
+
<para xmlns="http://docbook.org/ns/docbook">
4545
+
As of PHP 8.0.0, a <classname>ArgumentCountError</classname> is thrown when less arguments are given than required.
4546
+
Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
4547
+
</para>
4548
+
'>
4549
+
4550
+
<!ENTITY strings.errors.vsprintf '
4551
+
<para xmlns="http://docbook.org/ns/docbook">
4552
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
4553
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4554
+
</para>
4555
+
<para xmlns="http://docbook.org/ns/docbook">
4556
+
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>.
4557
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4558
+
</para>
4559
+
<para xmlns="http://docbook.org/ns/docbook">
4560
+
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>.
4561
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4562
+
</para>
4563
+
<para xmlns="http://docbook.org/ns/docbook">
4564
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown when less arguments are given than required.
4565
+
Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
4566
+
</para>
4567
+
'>
4568
+
4569
+
<!ENTITY strings.comparison.return '
4570
+
<simpara xmlns="http://docbook.org/ns/docbook">
4571
+
Returns a value less than 0 if <parameter>string1</parameter>
4572
+
is less than <parameter>string2</parameter>; a value greater
4573
+
than 0 if <parameter>string1</parameter> is greater than
4574
+
<parameter>string2</parameter>, and <literal>0</literal> if they
4575
+
are equal.
4576
+
No particular meaning can be reliably inferred from the value aside
4577
+
from its sign.
4578
+
</simpara>
4579
+
'>
4580
+
1863
4581
<!-- filter snippets -->
4582
+
<!-- TODO: Remove -->
1864
4583
<!ENTITY filter.param.filter '
1865
4584
<varlistentry xmlns="http://docbook.org/ns/docbook">
1866
4585
<term><parameter>filter</parameter></term>
1867
4586
<listitem>
1868
4587
<para>
1869
-
The ID of the filter to apply. The <xref linkend="filter.filters" />
1870
-
manual page lists the available filters.
4588
+
The filter to apply.
4589
+
Can be a validation filter by using one of the
4590
+
<constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>
4591
+
constants, a sanitization filter by using one of the
4592
+
<constant>FILTER_SANITIZE_<replaceable>*</replaceable></constant>
4593
+
or <constant>FILTER_UNSAFE_RAW</constant>, or a custom filter by using
4594
+
<constant>FILTER_CALLBACK</constant>.
1871
4595
</para>
1872
4596
<para>
1873
-
If omitted, <constant>FILTER_DEFAULT</constant> will be used, which is
1874
-
equivalent to
1875
-
<link linkend="filter.filters.sanitize"><constant>FILTER_UNSAFE_RAW</constant></link>.
4597
+
The default is <constant>FILTER_DEFAULT</constant>,
4598
+
which is an alias of <constant>FILTER_UNSAFE_RAW</constant>.
1876
4599
This will result in no filtering taking place by default.
1877
4600
</para>
1878
4601
</listitem>
1879
4602
</varlistentry>
1880
4603
'>
1881
4604
4605
+
<!-- csprng snippets -->
4606
+
<!ENTITY csprng.sources '
4607
+
<para xmlns="http://docbook.org/ns/docbook">
4608
+
The sources of randomness in the order of priority are as follows:
4609
+
</para>
4610
+
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4611
+
<listitem>
4612
+
<para>
4613
+
Linux: <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4614
+
</para>
4615
+
</listitem>
4616
+
<listitem>
4617
+
<para>
4618
+
FreeBSD >= 12 (PHP >= 7.3): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4619
+
</para>
4620
+
</listitem>
4621
+
<listitem>
4622
+
<para>
4623
+
Windows (PHP >= 7.2): <link xlink:href="&url.csprng.cng-api;">CNG-API</link>
4624
+
</para>
4625
+
<para>
4626
+
Windows: <link xlink:href="&url.csprng.crypt-gen-random;">CryptGenRandom</link>
4627
+
</para>
4628
+
</listitem>
4629
+
<listitem>
4630
+
<para>
4631
+
macOS (PHP >= 8.2; >= 8.1.9; >= 8.0.22 if CCRandomGenerateBytes is available at compile time): CCRandomGenerateBytes()
4632
+
</para>
4633
+
<para>
4634
+
macOS (PHP >= 8.1; >= 8.0.2): arc4random_buf(), <filename>/dev/urandom</filename>
4635
+
</para>
4636
+
</listitem>
4637
+
<listitem>
4638
+
<para>
4639
+
NetBSD >= 7 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
4640
+
</para>
4641
+
</listitem>
4642
+
<listitem>
4643
+
<para>
4644
+
OpenBSD >= 5.5 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
4645
+
</para>
4646
+
</listitem>
4647
+
<listitem>
4648
+
<para>
4649
+
DragonflyBSD (PHP >= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4650
+
</para>
4651
+
</listitem>
4652
+
<listitem>
4653
+
<para>
4654
+
Solaris (PHP >= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4655
+
</para>
4656
+
</listitem>
4657
+
<listitem>
4658
+
<simpara>
4659
+
Any combination of operating system and PHP version not previously mentioned: <filename>/dev/urandom</filename>
4660
+
</simpara>
4661
+
</listitem>
4662
+
<listitem>
4663
+
<simpara>
4664
+
If none of the sources are available or they all fail to generate
4665
+
randomness, then a <classname>Random\RandomException</classname>
4666
+
will be thrown.
4667
+
</simpara>
4668
+
</listitem>
4669
+
</itemizedlist>
4670
+
'>
4671
+
<!ENTITY csprng.errors '
4672
+
<listitem xmlns="http://docbook.org/ns/docbook">
4673
+
<simpara>
4674
+
If an appropriate source of randomness cannot be found,
4675
+
a <classname>Random\RandomException</classname> will be thrown.
4676
+
</simpara>
4677
+
</listitem>
4678
+
'>
4679
+
<!ENTITY csprng.function.backport '
4680
+
<note xmlns="http://docbook.org/ns/docbook">
4681
+
<simpara>
4682
+
Although this function was added to PHP in PHP 7.0, a
4683
+
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.csprng.compat;">userland implementation</link>
4684
+
is available for PHP 5.2 to 5.6, inclusive.
4685
+
</simpara>
4686
+
</note>
4687
+
'>
4688
+
4689
+
<!-- Random snippets -->
4690
+
<!ENTITY random.engineErrors '
4691
+
<listitem xmlns="http://docbook.org/ns/docbook">
4692
+
<simpara>
4693
+
Any <classname>Throwable</classname>s thrown by the <methodname>Random\Engine::generate</methodname> method
4694
+
of the underlying <link linkend="random-randomizer.props.engine"><literal>Random\Randomizer::$engine</literal></link>.
4695
+
</simpara>
4696
+
</listitem>
4697
+
'>
4698
+
4699
+
<!-- UOPZ snippets -->
4700
+
4701
+
<!ENTITY uopz.warn.removed.function-5-0-0 '<warning
4702
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
4703
+
<emphasis>REMOVED</emphasis> in PECL uopz 5.0.0.</simpara></warning>'>
4704
+
4705
+
<!-- XML snippets -->
4706
+
<!ENTITY xml.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
4707
+
<term><parameter>parser</parameter></term>
4708
+
<listitem>
4709
+
<para>
4710
+
The XML parser.
4711
+
</para>
4712
+
</listitem>
4713
+
</varlistentry>'>
4714
+
4715
+
<!ENTITY xml.handler.description '<para xmlns="http://docbook.org/ns/docbook">
4716
+
If &null; is passed, the handler is reset to its default state.
4717
+
<warning>
4718
+
<simpara>
4719
+
An empty string will also reset the handler,
4720
+
however this is deprecated as of PHP 8.4.0.
4721
+
</simpara>
4722
+
</warning>
4723
+
</para>
4724
+
<para xmlns="http://docbook.org/ns/docbook">
4725
+
If <parameter>handler</parameter> is a <type>callable</type>,
4726
+
the callable is set as the handler.
4727
+
</para>
4728
+
<para xmlns="http://docbook.org/ns/docbook">
4729
+
If <parameter>handler</parameter> is a <type>string</type>,
4730
+
it can be the name of a method of an object set with
4731
+
<function>xml_set_object</function>.
4732
+
<warning>
4733
+
<simpara>
4734
+
This is deprecated as of PHP 8.4.0.
4735
+
</simpara>
4736
+
</warning>
4737
+
</para>
4738
+
<warning xmlns="http://docbook.org/ns/docbook">
4739
+
<simpara>
4740
+
As of PHP 8.4.0, the callable is checked to be valid while setting the handler,
4741
+
not when it is called.
4742
+
This means that <function>xml_set_object</function> must be called prior to
4743
+
setting a method string as the callback.
4744
+
However, as this behaviour is also deprecated as of PHP 8.4.0,
4745
+
using a proper <type>callable</type> for the method is recommended instead.
4746
+
</simpara>
4747
+
</warning>
4748
+
'>
4749
+
4750
+
<!ENTITY xml.handler.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
4751
+
<term><parameter>parser</parameter></term>
4752
+
<listitem>
4753
+
<simpara>
4754
+
The XML parser calling the handler.
4755
+
</simpara>
4756
+
</listitem>
4757
+
</varlistentry>'>
4758
+
4759
+
<!ENTITY xml.changelog.handler-param '<row xmlns="http://docbook.org/ns/docbook">
4760
+
<entry>8.4.0</entry>
4761
+
<entry>
4762
+
Passing a non-<type>callable</type> <type>string</type> to
4763
+
<parameter>handler</parameter> is now deprecated,
4764
+
use a proper callable for methods, or &null; to reset the handler.
4765
+
</entry>
4766
+
</row>
4767
+
<row xmlns="http://docbook.org/ns/docbook">
4768
+
<entry>8.4.0</entry>
4769
+
<entry>
4770
+
The validity of <parameter>handler</parameter> as a <type>callable</type>
4771
+
is now checked when setting the handler instead of checking when calling it.
4772
+
</entry>
4773
+
</row>'>
4774
+
4775
+
<!ENTITY xml.changelog.parser-param '<row xmlns="http://docbook.org/ns/docbook">
4776
+
<entry>8.0.0</entry>
4777
+
<entry>
4778
+
<parameter>parser</parameter> expects an <classname>XMLParser</classname>
4779
+
instance now; previously, a valid <literal>xml</literal> <type>resource</type> was expected.
4780
+
</entry>
4781
+
</row>'>
4782
+
1882
4783
<!-- Migration Guide snippets -->
1883
4784
<!ENTITY migration56.openssl.peer-verification '
1884
4785
<para xmlns="http://docbook.org/ns/docbook">
1885
4786