language-snippets.ent
2a72c95c0a3773a6404d10602005dc453b024843
2a72c95c0a3773a6404d10602005dc453b024843
...
...
@@ -1,17 +1,57 @@
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
12
-
generate cryptographically secure values, and should not be used for cryptographic purposes. If you need a
13
-
cryptographically secure value, consider using <function>random_int</function>, <function>random_bytes</function>, or
14
-
<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>'>
33
+
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>'>
15
55
16
56
<!-- Notes -->
17
57
...
...
@@ -22,15 +62,23 @@ binary-safe.</simpara></note>'>
22
62
function are cached. See <function>clearstatcache</function> for
23
63
more details.</simpara></note>'>
24
64
25
-
<!ENTITY note.context-support '<note xmlns="http://docbook.org/ns/docbook"><simpara>Context support was added
26
-
with PHP 5.0.0. For a description of <literal>contexts</literal>, refer to
27
-
<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>'>
28
67
29
68
<!ENTITY note.exec-bg '<note xmlns="http://docbook.org/ns/docbook"><para>If a program is started with this function,
30
69
in order for it to continue running in the background, the output of the
31
70
program must be redirected to a file or another output stream. Failing to do so
32
71
will cause PHP to hang until the execution of the program ends.</para></note>'>
33
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
+
34
82
<!ENTITY note.func-callback '<note xmlns="http://docbook.org/ns/docbook"><simpara>Instead of a function name, an
35
83
array containing an object reference and a method name can also be
36
84
supplied.</simpara></note>'>
...
...
@@ -48,6 +96,13 @@ current scope to determine parameter details, it cannot be used as a
48
96
function parameter in versions prior to 5.3.0. If this value must be passed, the results should be assigned
49
97
to a variable, and that variable should be passed.</para></note>'>
50
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
+
51
106
<!ENTITY note.line-endings '<note xmlns="http://docbook.org/ns/docbook"><simpara>If PHP is not properly recognizing
52
107
the line endings when reading files either on or created by a Macintosh
53
108
computer, enabling the
...
...
@@ -72,17 +127,14 @@ implemented on Windows platforms.</simpara></note>'>
72
127
<!ENTITY note.no-windows.extension '<note xmlns="http://docbook.org/ns/docbook"><simpara>This extension is not
73
128
available on Windows platforms.</simpara></note>'>
74
129
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
+
75
133
<!ENTITY note.randomseed '<note xmlns="http://docbook.org/ns/docbook"><simpara>There is no need
76
134
to seed the random number generator with <function>srand</function> or
77
135
<function>mt_srand</function> as this is done automatically.
78
136
</simpara></note>'>
79
137
80
-
<!ENTITY note.registerglobals '<note xmlns="http://docbook.org/ns/docbook"><title>register_globals: important
81
-
note</title><para>As of PHP 4.2.0, the default value for the PHP directive
82
-
<link linkend="ini.register-globals">register_globals</link> is <emphasis>
83
-
off</emphasis>. The PHP community discourages developers from relying on this directive, and encourages the use
84
-
of other means, such as the &link.superglobals;.</para></note>'>
85
-
86
138
<!ENTITY note.is-superglobal "<note xmlns='http://docbook.org/ns/docbook'><para>This is a 'superglobal', or
87
139
automatic global, variable. This simply means that it is available in
88
140
all scopes throughout a script. There is no need to do
...
...
@@ -93,6 +145,10 @@ all scopes throughout a script. There is no need to do
93
145
is used, this function uses internal output buffering so it cannot be used inside an
94
146
<function>ob_start</function> callback function.</para></note>'>
95
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
+
96
152
<!ENTITY note.filesystem-time-res '<note xmlns="http://docbook.org/ns/docbook"><para>Note that time resolution may differ
97
153
from one file system to another.</para></note>'>
98
154
...
...
@@ -108,25 +164,31 @@ from one file system to another.</para></note>'>
108
164
</note>
109
165
'>
110
166
111
-
<!ENTITY note.passwordhashing '<note xmlns="http://docbook.org/ns/docbook">
112
-
<title>Secure password hashing</title>
167
+
<!ENTITY note.sigchild '<note xmlns="http://docbook.org/ns/docbook">
113
168
<para>
114
-
It is not recommended to use this function to secure passwords, due to the fast nature of this hashing algorithm. See
115
-
<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.
116
170
</para>
117
171
</note>
118
172
'>
119
173
120
-
<!ENTITY note.sigchild '<note xmlns="http://docbook.org/ns/docbook">
174
+
<!ENTITY note.sort-unstable '<note xmlns="http://docbook.org/ns/docbook">
121
175
<para>
122
-
If PHP has been compiled with --enable-sigchild, the return value of this function is undefined.
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.
123
178
</para>
124
179
</note>
125
180
'>
126
181
127
-
<!ENTITY note.sort-unstable '<note xmlns="http://docbook.org/ns/docbook">
182
+
<!ENTITY note.reset-index "<note xmlns='http://docbook.org/ns/docbook'>
128
183
<para>
129
-
If two members compare as equal, their relative order in the sorted array is undefined.
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.
130
192
</para>
131
193
</note>
132
194
'>
...
...
@@ -176,16 +238,6 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
176
238
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature
177
239
is highly discouraged.</simpara></warning>'>
178
240
179
-
<!ENTITY warn.deprecated.feature-5-3-0.removed-6-0-0 '<warning
180
-
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
181
-
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature is
182
-
highly discouraged.</simpara></warning>'>
183
-
184
-
<!ENTITY warn.deprecated.function-5-3-0.removed-6-0-0 '<warning
185
-
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
186
-
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature is
187
-
highly discouraged.</simpara></warning>'>
188
-
189
241
<!ENTITY warn.deprecated.feature-5-3-0.removed-5-4-0 '<warning
190
242
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
191
243
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0 and <emphasis>REMOVED</emphasis>
...
...
@@ -210,6 +262,107 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
210
262
<emphasis>DEPRECATED</emphasis> as of PHP 7.0.0. Relying on this feature
211
263
is highly discouraged.</simpara></warning>'>
212
264
265
+
<!ENTITY warn.deprecated.feature-7-1-0 '<warning
266
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
267
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0. Relying on this feature
268
+
is highly discouraged.</simpara></warning>'>
269
+
270
+
<!ENTITY warn.deprecated.function-7-1-0 '<warning
271
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
272
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0. Relying on this function
273
+
is highly discouraged.</simpara></warning>'>
274
+
275
+
<!ENTITY warn.deprecated.function-7-0-0.removed-8-0-0 '<warning
276
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
277
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.0.0 and
278
+
<emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
279
+
is highly discouraged.</simpara></warning>'>
280
+
281
+
<!ENTITY warn.deprecated.function-7-1-0.removed-7-2-0 '<warning
282
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
283
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0 and
284
+
<emphasis>REMOVED</emphasis> as of PHP 7.2.0. Relying on this function
285
+
is highly discouraged.</simpara></warning>'>
286
+
287
+
<!ENTITY warn.deprecated.feature-7-2-0 '<warning
288
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
289
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0. Relying on this feature
290
+
is highly discouraged.</simpara></warning>'>
291
+
292
+
<!ENTITY warn.deprecated.feature-7-2-0.removed-8-0-0 '<warning
293
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
294
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this feature
295
+
is highly discouraged.</simpara></warning>'>
296
+
297
+
<!ENTITY warn.deprecated.function-7-2-0 '<warning
298
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
299
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0. Relying on this function
300
+
is highly discouraged.</simpara></warning>'>
301
+
302
+
<!ENTITY warn.deprecated.function-7-2-0.removed-8-0-0 '<warning
303
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
304
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
305
+
is highly discouraged.</simpara></warning>'>
306
+
307
+
<!ENTITY warn.deprecated.feature-7-3-0 '<warning
308
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
309
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0. Relying on this feature
310
+
is highly discouraged.</simpara></warning>'>
311
+
312
+
<!ENTITY warn.deprecated.function-7-3-0 '<warning
313
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
314
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0. Relying on this function
315
+
is highly discouraged.</simpara></warning>'>
316
+
317
+
<!ENTITY warn.deprecated.function-7-3-0.removed-8-0-0 '<warning
318
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
319
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
320
+
is highly discouraged.</simpara></warning>'>
321
+
322
+
<!ENTITY warn.deprecated.feature-7-4-0 '<warning
323
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
324
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0. Relying on this feature
325
+
is highly discouraged.</simpara></warning>'>
326
+
327
+
<!ENTITY warn.deprecated.function-7-4-0 '<warning
328
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
329
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0. Relying on this function
330
+
is highly discouraged.</simpara></warning>'>
331
+
332
+
<!ENTITY warn.deprecated.function-7-4-0.removed-8-0-0 '<warning
333
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
334
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
335
+
is highly discouraged.</simpara></warning>'>
336
+
337
+
<!ENTITY warn.feature.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook">
338
+
<simpara>This feature was <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara>
339
+
</warning>'>
340
+
341
+
<!ENTITY warn.deprecated.function-8-0-0 '<warning
342
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
343
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0. Relying on this function
344
+
is highly discouraged.</simpara></warning>'>
345
+
346
+
<!ENTITY warn.deprecated.function-8-1-0 '<warning
347
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
348
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
349
+
is highly discouraged.</simpara></warning>'>
350
+
351
+
<!ENTITY warn.deprecated.function-8-2-0 '<warning
352
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
353
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.2.0. Relying on this function
354
+
is highly discouraged.</simpara></warning>'>
355
+
356
+
<!ENTITY warn.deprecated.feature-8-3-0 '<warning
357
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
358
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this feature
359
+
is highly discouraged.</simpara></warning>'>
360
+
361
+
<!ENTITY warn.deprecated.function-8-3-0 '<warning
362
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
363
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this function
364
+
is highly discouraged.</simpara></warning>'>
365
+
213
366
<!ENTITY removed.php.future 'This deprecated feature <emphasis xmlns="http://docbook.org/ns/docbook">will</emphasis>
214
367
certainly be <emphasis xmlns="http://docbook.org/ns/docbook">removed</emphasis> in the future.'>
215
368
...
...
@@ -265,6 +418,22 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This feature was
265
418
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
266
419
<emphasis>REMOVED</emphasis> in PHP 7.0.0.</simpara></warning>'>
267
420
421
+
<!ENTITY warn.removed.function-7-4-0 '<warning
422
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
423
+
<emphasis>REMOVED</emphasis> in PHP 7.4.0.</simpara></warning>'>
424
+
425
+
<!ENTITY warn.deprecated.alias-7-2-0.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was
426
+
<emphasis>DEPRECATED</emphasis> in PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
427
+
428
+
<!ENTITY warn.deprecated.alias-7-4-0.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was
429
+
<emphasis>DEPRECATED</emphasis> in PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
430
+
431
+
<!ENTITY warn.deprecated.alias-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias is
432
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
433
+
434
+
<!ENTITY warn.removed.alias-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias is
435
+
<emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>
436
+
268
437
<!ENTITY warn.experimental.func '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function is
269
438
<emphasis>EXPERIMENTAL</emphasis>. The behaviour of this function, its name, and
270
439
surrounding documentation may change without notice in a future release of PHP.
...
...
@@ -272,8 +441,8 @@ This function should be used at your own risk.
272
441
</simpara></warning>'>
273
442
274
443
<!ENTITY warn.imaprecodeyaz '<warning xmlns="http://docbook.org/ns/docbook"><simpara>The <link
275
-
linkend="book.imap">IMAP</link>, <link linkend="book.recode">recode</link>,
276
-
<link linkend="book.yaz">YAZ</link> and <link linkend="book.cyrus">Cyrus</link>
444
+
linkend="book.imap">IMAP</link>, <link linkend="book.recode">recode</link> and
445
+
<link linkend="book.yaz">YAZ</link>
277
446
extensions cannot be used in conjunction, because they
278
447
share the same internal symbols. Note: Yaz 2.0 and above does not suffer from this problem.</simpara></warning>'>
279
448
...
...
@@ -282,11 +451,16 @@ to several possible vulnerabilities. Please read our
282
451
<link linkend="security.cgi-bin">CGI security section</link> to learn how to
283
452
defend yourself from such attacks.</para></warning>'>
284
453
285
-
<!ENTITY note.magicquotes.gpc '<note xmlns="http://docbook.org/ns/docbook"><title>directive note: magic_quotes_gpc
286
-
</title><para>The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>
287
-
directive defaults to <literal>on</literal>. It essentially runs
288
-
<function>addslashes</function> on all GET, POST, and COOKIE data.
289
-
<function>stripslashes</function> may be used to remove them.</para></note>'>
454
+
<!ENTITY warn.passwordhashing '
455
+
<warning xmlns="http://docbook.org/ns/docbook">
456
+
<para>
457
+
It is not recommended to use this function to secure passwords,
458
+
due to the fast nature of this hashing algorithm. See the
459
+
<link linkend="faq.passwords.fasthash">Password Hashing FAQ</link>
460
+
for details and best practices.
461
+
</para>
462
+
</warning>
463
+
'>
290
464
291
465
<!ENTITY warn.ssl-non-standard '<warning xmlns="http://docbook.org/ns/docbook"><para>When using SSL, Microsoft IIS
292
466
will violate the protocol by closing the connection without sending a
...
...
@@ -376,15 +550,39 @@ currently not documented; only its argument list is available.
376
550
</para>
377
551
'>
378
552
553
+
<!ENTITY warn.deprecated.feature.7-1-0.removed.7-2-0.alternatives '
554
+
<para xmlns="http://docbook.org/ns/docbook">
555
+
This feature was <emphasis>DEPRECATED</emphasis> in PHP 7.1.0, and
556
+
<emphasis>REMOVED</emphasis> in PHP 7.2.0.
557
+
</para>
558
+
<para xmlns="http://docbook.org/ns/docbook">
559
+
Alternatives to this feature include:
560
+
</para>
561
+
'>
562
+
563
+
<!ENTITY warn.deprecated.function.7-1-0.removed.7-2-0.alternatives '
564
+
<para xmlns="http://docbook.org/ns/docbook">
565
+
This function was <emphasis>DEPRECATED</emphasis> in PHP 7.1.0, and
566
+
<emphasis>REMOVED</emphasis> in PHP 7.2.0.
567
+
</para>
568
+
<para xmlns="http://docbook.org/ns/docbook">
569
+
Alternatives to this function include:
570
+
</para>
571
+
'>
572
+
573
+
<!ENTITY warn.deprecated.function-8-1-0.alternatives '<warning
574
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
575
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
576
+
is highly discouraged.</simpara></warning>
577
+
<para xmlns="http://docbook.org/ns/docbook">
578
+
Alternatives to this function include:
579
+
</para>
580
+
'>
379
581
380
582
<!-- Misc -->
381
583
382
584
<!ENTITY version.exists.asof 'This exists as of PHP '>
383
585
384
-
<!ENTITY version.trunk.after.53 '<emphasis xmlns="http://docbook.org/ns/docbook">This change
385
-
exists in the <link linkend="about.phpversions">development version</link> of PHP, and will
386
-
probably exist after 5.3.</emphasis>'>
387
-
388
586
<!ENTITY version.trunk.changelog 'Future'>
389
587
390
588
<!ENTITY no.function.parameters '<para xmlns="http://docbook.org/ns/docbook">This function has no parameters.</para>'>
...
...
@@ -403,6 +601,30 @@ probably exist after 5.3.</emphasis>'>
403
601
404
602
<!ENTITY example.outputs.7 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7:</para>'>
405
603
604
+
<!ENTITY example.outputs.70 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.0:</para>'>
605
+
606
+
<!ENTITY example.outputs.71 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.1:</para>'>
607
+
608
+
<!ENTITY example.outputs.72 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.2:</para>'>
609
+
610
+
<!ENTITY example.outputs.73 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.3:</para>'>
611
+
612
+
<!ENTITY example.outputs.8 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8:</para>'>
613
+
614
+
<!ENTITY example.outputs.8.similar '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8 is similar to:</para>'>
615
+
616
+
<!ENTITY example.outputs.80 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.0:</para>'>
617
+
618
+
<!ENTITY example.outputs.81 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.1:</para>'>
619
+
620
+
<!ENTITY example.outputs.82 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.2:</para>'>
621
+
622
+
<!ENTITY example.outputs.82.similar '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.2 is similar to:</para>'>
623
+
624
+
<!ENTITY example.outputs.83 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.3:</para>'>
625
+
626
+
<!ENTITY example.outputs.83.similar '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.3 is similar to:</para>'>
627
+
406
628
<!ENTITY example.outputs.32bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 32 bit machines:</para>'>
407
629
408
630
<!ENTITY example.outputs.64bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 64 bit machines:</para>'>
...
...
@@ -423,17 +645,110 @@ something similar to:</para>'>
423
645
<function>reset</function> the <type>array</type> pointer of the input array after
424
646
use.</simpara></note>'>
425
647
648
+
<!ENTITY array.changelog.by-ref '<row xmlns="http://docbook.org/ns/docbook">
649
+
<entry>8.0.0</entry>
650
+
<entry>
651
+
If <parameter>callback</parameter> expects a parameter to be passed
652
+
by reference, this function will now emit an <constant>E_WARNING</constant>.
653
+
</entry>
654
+
</row>'>
655
+
656
+
<!ENTITY array.changelog.require-only-one '<row xmlns="http://docbook.org/ns/docbook">
657
+
<entry>8.0.0</entry>
658
+
<entry>
659
+
This function can now be called with only one parameter.
660
+
Formerly, at least two parameters have been required.
661
+
</entry>
662
+
</row>'>
663
+
426
664
<!ENTITY seealso.array.sorting 'The <link xmlns="http://docbook.org/ns/docbook" linkend="array.sorting">comparison of array sorting functions</link>'>
427
665
428
-
<!ENTITY seealso.callback 'information about the <link xmlns="http://docbook.org/ns/docbook" linkend="language.types.callback">callback</link> type'>
666
+
<!ENTITY sort.flags.parameter '<varlistentry xmlns="http://docbook.org/ns/docbook">
667
+
<term><parameter>flags</parameter></term>
668
+
<listitem>
669
+
<para>
670
+
The optional second parameter <parameter>flags</parameter>
671
+
may be used to modify the sorting behavior using these values:
672
+
</para>
673
+
<para>
674
+
Sorting type flags:
675
+
<itemizedlist>
676
+
<listitem>
677
+
<simpara><constant>SORT_REGULAR</constant> - compare items normally;
678
+
the details are described in the <link linkend="language.operators.comparison">comparison operators</link> section</simpara>
679
+
</listitem>
680
+
<listitem>
681
+
<simpara><constant>SORT_NUMERIC</constant> - compare items numerically</simpara>
682
+
</listitem>
683
+
<listitem>
684
+
<simpara><constant>SORT_STRING</constant> - compare items as strings</simpara>
685
+
</listitem>
686
+
<listitem>
687
+
<simpara>
688
+
<constant>SORT_LOCALE_STRING</constant> - compare items as
689
+
strings, based on the current locale. It uses the locale,
690
+
which can be changed using <function>setlocale</function>
691
+
</simpara>
692
+
</listitem>
693
+
<listitem>
694
+
<simpara>
695
+
<constant>SORT_NATURAL</constant> - compare items as strings
696
+
using "natural ordering" like <function>natsort</function>
697
+
</simpara>
698
+
</listitem>
699
+
<listitem>
700
+
<simpara>
701
+
<constant>SORT_FLAG_CASE</constant> - can be combined
702
+
(bitwise OR) with
703
+
<constant>SORT_STRING</constant> or
704
+
<constant>SORT_NATURAL</constant> to sort strings case-insensitively
705
+
</simpara>
706
+
</listitem>
707
+
</itemizedlist>
708
+
</para>
709
+
</listitem>
710
+
</varlistentry>
711
+
'>
429
712
430
-
<!ENTITY avail.register-long-arrays 'As of PHP 5.0.0, the long PHP
431
-
<link xmlns="http://docbook.org/ns/docbook" linkend="language.variables.predefined">predefined variable</link>
432
-
arrays may be disabled with the
433
-
<link xmlns="http://docbook.org/ns/docbook" linkend="ini.register-long-arrays">register_long_arrays</link>
434
-
directive.'>
713
+
<!ENTITY sort.callback.description '<para xmlns="http://docbook.org/ns/docbook">
714
+
&return.callbacksort;
715
+
</para>
716
+
&callback.cmp;
717
+
<caution xmlns="http://docbook.org/ns/docbook">
718
+
<para>
719
+
Returning <emphasis>non-integer</emphasis> values from the comparison
720
+
function, such as <type>float</type>, will result in an internal cast to
721
+
<type>int</type> of the callback's return value. So values such as
722
+
<literal>0.99</literal> and <literal>0.1</literal> will both be cast to an
723
+
integer value of <literal>0</literal>, which will compare such values as equal.
724
+
</para>
725
+
</caution>'>
726
+
727
+
<!ENTITY sort.callback.description.presort '<caution xmlns="http://docbook.org/ns/docbook">
728
+
<para>
729
+
The sorting callback must handle any value from any array in any order,
730
+
regardless of the order they were originally provided.
731
+
This is because each individual array is first sorted before being compared against other arrays.
435
732
436
-
<!ENTITY ini.shorthandbytes '<simpara xmlns="http://docbook.org/ns/docbook">When an <type>integer</type> is used, the
733
+
For example:
734
+
<programlisting role="php">
735
+
<![CDATA[
736
+
<?php
737
+
$arrayA = ["string", 1];
738
+
$arrayB = [["value" => 1]];
739
+
// $item1 and $item2 can be any of "string", 1 or ["value" => 1]
740
+
$compareFunc = static function ($item1, $item2) {
741
+
$value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);
742
+
$value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);
743
+
return $value1 <=> $value2;
744
+
};
745
+
?>
746
+
]]>
747
+
</programlisting>
748
+
</para>
749
+
</caution>'>
750
+
751
+
<!ENTITY ini.shorthandbytes '<simpara xmlns="http://docbook.org/ns/docbook">When an <type>int</type> is used, the
437
752
value is measured in bytes. Shorthand notation, as described
438
753
in <link linkend="faq.using.shorthandbytes">this FAQ</link>, may also be used.
439
754
</simpara>'>
...
...
@@ -464,13 +779,15 @@ files from the PHP folder into the Windows system directory also works
464
779
465
780
<!ENTITY manual.migration.seealso 'See also the migration guides for PHP versions'>
466
781
467
-
<!ENTITY style.oop 'Object oriented style'>
782
+
<!ENTITY style.oop 'Object-oriented style'>
468
783
<!ENTITY style.procedural 'Procedural style'>
469
784
470
785
<!ENTITY resource '<link xmlns="http://docbook.org/ns/docbook" linkend="language.types.resource">resource</link>'>
471
786
472
787
<!ENTITY foreach '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.foreach">foreach</link>'>
473
788
789
+
<!ENTITY match '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.match">match</link>'>
790
+
474
791
<!ENTITY yield '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.yield">yield</link>'>
475
792
476
793
<!ENTITY parameter.context 'Refer to the <link xmlns="http://docbook.org/ns/docbook" linkend="context">context</link>
...
...
@@ -481,13 +798,24 @@ searched for within the <link xmlns="http://docbook.org/ns/docbook" linkend="ini
481
798
482
799
<!-- Returns -->
483
800
801
+
<!ENTITY return.type.true '<row xmlns="http://docbook.org/ns/docbook">
802
+
<entry>8.2.0</entry>
803
+
<entry>
804
+
The return type is &true; now; previously, it was <type>bool</type>.
805
+
</entry>
806
+
</row>'>
807
+
484
808
<!ENTITY return.falseforfailure ' or &false; on failure'>
485
809
<!ENTITY return.falseforfailure.style.procedural '&style.procedural; returns &false; on failure.'>
486
810
487
811
<!ENTITY return.success 'Returns &true; on success&return.falseforfailure;.'>
488
812
813
+
<!ENTITY return.nullorfalse 'Returns &null; on success&return.falseforfailure;.'>
814
+
489
815
<!ENTITY return.void 'No value is returned.'>
490
816
817
+
<!ENTITY return.true.always 'Always returns &true;.'>
818
+
491
819
<!ENTITY return.callbacksort 'The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.'>
492
820
493
821
<!ENTITY return.falseproblem '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function may
...
...
@@ -498,6 +826,42 @@ information. Use <link linkend="language.operators.comparison">the ===
498
826
operator</link> for testing the return value of this
499
827
function.</simpara></warning>'>
500
828
829
+
<!-- Standard -->
830
+
<!ENTITY standard.changelog.calling-on-objects '<row xmlns="http://docbook.org/ns/docbook">
831
+
<entry>8.1.0</entry>
832
+
<entry>
833
+
Calling this function on &object;s is deprecated.
834
+
Either convert the &object; to an &array; using <function>get_mangled_object_vars</function> first, or use the methods
835
+
provided by a class that implements <interfacename>Iterator</interfacename>, such as <classname>ArrayIterator</classname>, instead.
836
+
</entry>
837
+
</row>
838
+
<row xmlns="http://docbook.org/ns/docbook">
839
+
<entry>7.4.0</entry>
840
+
<entry>
841
+
Instances of <link xmlns="http://docbook.org/ns/docbook" linkend="book.spl">SPL</link> classes are now treated like empty objects that have no properties instead of calling the <interfacename>Iterator</interfacename> method with the same name as this function.
842
+
</entry>
843
+
</row>
844
+
'>
845
+
846
+
<!ENTITY standard.changelog.binary-safe-string-comparison '<row xmlns="http://docbook.org/ns/docbook">
847
+
<entry>8.2.0</entry>
848
+
<entry>
849
+
This function now returns <literal>-1</literal> or <literal>1</literal>,
850
+
where it previously returned a negative or positive number.
851
+
</entry>
852
+
</row>
853
+
'>
854
+
855
+
<!-- FileInfo -->
856
+
<!ENTITY fileinfo.parameters.finfo '<para xmlns="http://docbook.org/ns/docbook">An <classname>finfo</classname> instance, returned by <function>finfo_open</function>.</para>'>
857
+
<!ENTITY fileinfo.changelog.finfo-object '<row xmlns="http://docbook.org/ns/docbook">
858
+
<entry>8.1.0</entry>
859
+
<entry>
860
+
The <parameter>finfo</parameter> parameter expects an <classname>finfo</classname>
861
+
instance now; previously, a &resource; was expected.
862
+
</entry>
863
+
</row>'>
864
+
501
865
<!-- OpenSSL -->
502
866
<!ENTITY openssl.param.x509 '<varlistentry xmlns="http://docbook.org/ns/docbook">
503
867
<term><parameter>x509</parameter></term>
...
...
@@ -508,41 +872,105 @@ function.</simpara></warning>'>
508
872
</listitem>
509
873
</varlistentry>'>
510
874
875
+
<!ENTITY openssl.param.csr '<varlistentry xmlns="http://docbook.org/ns/docbook">
876
+
<term><parameter>csr</parameter></term>
877
+
<listitem>
878
+
<para>
879
+
See <link linkend="openssl.certparams">CSR parameters</link> for a list of valid values.
880
+
</para>
881
+
</listitem>
882
+
</varlistentry>'>
883
+
884
+
<!ENTITY openssl.param.key '<varlistentry xmlns="http://docbook.org/ns/docbook">
885
+
<term><parameter>key</parameter></term>
886
+
<listitem>
887
+
<para>
888
+
See <link linkend="openssl.certparams">Public/Private Key parameters</link> for a list of valid values.
889
+
</para>
890
+
</listitem>
891
+
</varlistentry>'>
892
+
511
893
<!-- Image (GD) Notes -->
512
894
<!ENTITY note.config.t1lib '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available
513
895
if PHP is compiled using <option role="configure">--with-t1lib[=DIR]</option>.
514
896
</simpara></note>'>
515
897
516
-
<!ENTITY note.config.jpeg '<note xmlns="http://docbook.org/ns/docbook"><simpara>JPEG support is only available if
517
-
PHP was compiled against GD-1.8 or later.</simpara></note>'>
518
-
519
-
<!ENTITY note.config.wbmp '<note xmlns="http://docbook.org/ns/docbook"><simpara>WBMP support is only available if
520
-
PHP was compiled against GD-1.8 or later.</simpara></note>'>
521
-
522
-
<!ENTITY note.bundled.gd '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available if
523
-
PHP is compiled with the bundled version of the GD library.</simpara></note>'>
524
-
525
898
<!ENTITY note.freetype '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available if
526
899
PHP is compiled with freetype support (<option role="configure">--with-freetype-dir=DIR</option>)
527
900
</simpara></note>'>
528
901
529
-
<!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>'>
530
-
531
902
<!ENTITY note.gd.notrequired '<note xmlns="http://docbook.org/ns/docbook"><para>This function does not require the GD image library.</para></note>'>
532
903
533
904
<!ENTITY note.gd.interpolation '<note xmlns="http://docbook.org/ns/docbook"><para>This function is affected by the interpolation method set by <function>imagesetinterpolation</function>.</para></note>'>
534
905
535
-
<!ENTITY gd.image.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
536
-
image</parameter></term><listitem><para>An image resource, returned by one of the image creation functions,
906
+
<!ENTITY gd.image.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
907
+
<parameter>image</parameter></term><listitem><para>A <classname>GdImage</classname> object, returned by one of the image creation functions,
537
908
such as <function>imagecreatetruecolor</function>.</para></listitem></varlistentry>'>
538
909
539
-
<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
540
-
font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in
541
-
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or any of your
542
-
own font identifiers registered with <function>imageloadfont</function>.
543
-
</para></listitem></varlistentry>'>
910
+
<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
911
+
<parameter>font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in
912
+
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or <classname>GdFont</classname> instance,
913
+
returned by <function>imageloadfont</function>.</para></listitem></varlistentry>'>
544
914
545
-
<!ENTITY gd.return.identifier 'Returns an image resource identifier on success, &false; on errors.'>
915
+
<!ENTITY gd.changelog.gdfont-instance '<row xmlns="http://docbook.org/ns/docbook">
916
+
<entry>8.1.0</entry>
917
+
<entry>
918
+
The <parameter>font</parameter> parameter now accepts both an <classname>GdFont</classname> instance
919
+
and an &integer;; previously only &integer; was accepted.
920
+
</entry>
921
+
</row>'>
922
+
923
+
<!ENTITY gd.ttf.fontfile "
924
+
<varlistentry xmlns='http://docbook.org/ns/docbook'>
925
+
<term><parameter>fontfile</parameter></term>
926
+
<listitem>
927
+
<para>
928
+
The path to the TrueType font you wish to use.
929
+
</para>
930
+
<para>
931
+
Depending on which version of the GD library PHP is using, <emphasis>when
932
+
<parameter>fontfile</parameter> does not begin with a leading
933
+
<literal>/</literal> then <literal>.ttf</literal> will be appended</emphasis>
934
+
to the filename and the library will attempt to search for that
935
+
filename along a library-defined font path.
936
+
</para>
937
+
<para>
938
+
When using versions of the GD library lower than 2.0.18, a <literal>space</literal> character,
939
+
rather than a semicolon, was used as the 'path separator' for different font files.
940
+
Unintentional use of this feature will result in the warning message:
941
+
<literal>Warning: Could not find/open font</literal>. For these affected versions, the
942
+
only solution is moving the font to a path which does not contain spaces.
943
+
</para>
944
+
<para>
945
+
In many cases where a font resides in the same directory as the script using it
946
+
the following trick will alleviate any include problems.
947
+
<programlisting role='php'>
948
+
<![CDATA[
949
+
<?php
950
+
// Set the environment variable for GD
951
+
putenv('GDFONTPATH=' . realpath('.'));
952
+
953
+
// Name the font to be used (note the lack of the .ttf extension)
954
+
$font = 'SomeFont';
955
+
?>
956
+
]]>
957
+
</programlisting>
958
+
</para>
959
+
<note>
960
+
<para>
961
+
Note that <link linkend='ini.open-basedir'>open_basedir</link> does
962
+
<emphasis>not</emphasis> apply to <parameter>fontfile</parameter>.
963
+
</para>
964
+
</note>
965
+
</listitem>
966
+
</varlistentry>
967
+
">
968
+
969
+
<!ENTITY gd.return.identifier 'Returns an image object on success, &false; on errors.'>
970
+
971
+
<!ENTITY gd.return.trueonerror '<caution xmlns="http://docbook.org/ns/docbook"><simpara>However, if libgd fails to output the image, this function returns &true;.</simpara></caution>'>
972
+
973
+
<!ENTITY gd.identifier.color "A color identifier created with <function xmlns='http://docbook.org/ns/docbook'>imagecolorallocate</function>.">
546
974
547
975
<!ENTITY gd.value.red 'Value of red component.'>
548
976
...
...
@@ -554,24 +982,88 @@ own font identifiers registered with <function>imageloadfont</function>.
554
982
555
983
<!ENTITY gd.source.width 'Source width.'>
556
984
557
-
<!ENTITY gd.image.path 'The path to save the file to. If not set or &null;, the raw image stream will be outputted directly.'>
985
+
<!ENTITY gd.image.path 'The path or an open stream resource (which is automatically closed after this function returns) to save the file to. If not set or &null;, the raw image stream will be output directly.'>
558
986
559
987
<!ENTITY gd.image.new 'Create a new image from file or URL'>
560
988
561
-
<!ENTITY gd.image.source 'Source image link resource.'>
989
+
<!ENTITY gd.image.source 'Source image resource.'>
562
990
563
-
<!ENTITY gd.image.destination 'Destination image link resource.'>
991
+
<!ENTITY gd.image.destination 'Destination image resource.'>
564
992
565
993
<!ENTITY gd.image.output 'Output image to browser or file'>
566
994
567
995
<!ENTITY gd.image.colors 'If you created the image from a file, only colors used in the image are resolved. Colors present only in the palette are not resolved.'>
568
996
569
-
<!ENTITY gd.font.size 'The font size. Depending on your version of GD, this should be specified as the pixel size (GD1) or point size (GD2).'>
997
+
<!ENTITY gd.font.size 'The font size in points.'>
998
+
999
+
<!ENTITY gd.constants.types '<simpara xmlns="http://docbook.org/ns/docbook">
1000
+
Used as a return value by <function>imagetypes</function>
1001
+
</simpara>'>
1002
+
1003
+
<!ENTITY gd.constants.color '<simpara xmlns="http://docbook.org/ns/docbook">
1004
+
Special color option which can be used instead of a color allocated with
1005
+
<function>imagecolorallocate</function> or
1006
+
<function>imagecolorallocatealpha</function>.
1007
+
</simpara>'>
1008
+
1009
+
<!ENTITY gd.constants.affine '<simpara xmlns="http://docbook.org/ns/docbook">
1010
+
An affine transformation type constant used by the <function>imageaffinematrixget</function> function.
1011
+
</simpara>'>
1012
+
1013
+
<!ENTITY gd.constants.arc '<simpara xmlns="http://docbook.org/ns/docbook">
1014
+
A style constant used by the <function>imagefilledarc</function> function.
1015
+
</simpara>'>
1016
+
1017
+
<!ENTITY gd.constants.gd2 '<simpara xmlns="http://docbook.org/ns/docbook">
1018
+
A type constant used by the <function>imagegd2</function> function.
1019
+
</simpara>'>
1020
+
1021
+
<!ENTITY gd.constants.effect '<simpara xmlns="http://docbook.org/ns/docbook">
1022
+
Alpha blending effect used by the <function>imagelayereffect</function> function.
1023
+
</simpara>'>
1024
+
1025
+
<!ENTITY gd.constants.filter '<simpara xmlns="http://docbook.org/ns/docbook">
1026
+
Special GD filter used by the <function>imagefilter</function> function.
1027
+
</simpara>'>
1028
+
1029
+
<!ENTITY gd.constants.type '<simpara xmlns="http://docbook.org/ns/docbook">
1030
+
Image type constant used by the <function>image_type_to_mime_type</function>
1031
+
and <function>image_type_to_extension</function> functions.
1032
+
</simpara>'>
1033
+
1034
+
<!ENTITY gd.constants.png-filter '<simpara xmlns="http://docbook.org/ns/docbook">
1035
+
A special PNG filter, used by the <function>imagepng</function> function.
1036
+
</simpara>'>
1037
+
1038
+
<!ENTITY gd.constants.flip '<simpara xmlns="http://docbook.org/ns/docbook">
1039
+
Used together with <function>imageflip</function>, available as of PHP 5.5.0.
1040
+
</simpara>'>
1041
+
1042
+
<!ENTITY gd.constants.interpolation '<simpara xmlns="http://docbook.org/ns/docbook">
1043
+
Used together with <function>imagesetinterpolation</function>, available as of PHP 5.5.0.
1044
+
</simpara>'>
1045
+
1046
+
<!ENTITY gd.changlog.t1lib '<row xmlns="http://docbook.org/ns/docbook">
1047
+
<entry>7.0.0</entry><entry>T1Lib support was removed from PHP, thus this function was removed.</entry>
1048
+
</row>'>
1049
+
1050
+
<!ENTITY gd.deprecated.gd-formats '<warning xmlns="http://docbook.org/ns/docbook"><simpara>The GD
1051
+
and GD2 image formats are proprietary image formats of libgd. They have to be regarded
1052
+
<emphasis>obsolete</emphasis>, and should only be used for development and testing
1053
+
purposes.</simpara></warning>'>
1054
+
1055
+
<!ENTITY gd.changelog.image-param '<row xmlns="http://docbook.org/ns/docbook">
1056
+
<entry>8.0.0</entry>
1057
+
<entry>
1058
+
<parameter>image</parameter> expects a <classname>GdImage</classname>
1059
+
instance now; previously, a valid <literal>gd</literal> <type>resource</type> was expected.
1060
+
</entry>
1061
+
</row>'>
570
1062
571
1063
<!-- DBM notes -->
572
1064
573
-
<!ENTITY dbm.dbm-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
574
-
dbm_identifier</parameter></term><listitem><para>The DBM link identifier,
1065
+
<!ENTITY dbm.dbm-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1066
+
<parameter>dbm_identifier</parameter></term><listitem><para>The DBM link identifier,
575
1067
returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
576
1068
577
1069
<!-- JSON notes -->
...
...
@@ -580,35 +1072,133 @@ returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
580
1072
<note xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
581
1073
<para>
582
1074
PHP implements a superset of JSON as specified in the original
583
-
<link xlink:href="&url.rfc;4627">RFC 4627</link> - it will also encode and
584
-
decode scalar types and &null;. RFC 4627 only supports these values when
585
-
they are nested inside an array or an object.
586
-
</para>
587
-
<para>
588
-
Although this superset is consistent with the expanded definition of "JSON
589
-
text" in the newer <link xlink:href="&url.rfc;7159">RFC 7159</link> (which
590
-
aims to supersede RFC 4627) and
591
-
<link xlink:href="&url.json.ecma;">ECMA-404</link>, this may cause
592
-
interoperability issues with older JSON parsers that adhere strictly to RFC
593
-
4627 when encoding a single scalar value.
1075
+
<link xlink:href="&url.rfc;7159">RFC 7159</link>.
594
1076
</para>
595
1077
</note>
596
1078
'>
597
1079
598
1080
<!-- cURL notes -->
599
1081
600
-
<!ENTITY curl.ch.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>ch</parameter>
1082
+
<!ENTITY curl.ch.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>handle</parameter>
601
1083
</term><listitem><para>A cURL handle returned by
602
1084
<function>curl_init</function>.</para></listitem></varlistentry>'>
603
1085
604
-
<!ENTITY curl.mh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>mh</parameter>
1086
+
<!ENTITY curl.mh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>multi_handle</parameter>
605
1087
</term><listitem><para>A cURL multi handle returned by
606
1088
<function>curl_multi_init</function>.</para></listitem></varlistentry>'>
607
1089
1090
+
<!ENTITY curl.sh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>share_handle</parameter>
1091
+
</term><listitem><para>A cURL share handle returned by
1092
+
<function>curl_share_init</function>.</para></listitem></varlistentry>'>
1093
+
1094
+
<!ENTITY curl.changelog.handle-param '<row xmlns="http://docbook.org/ns/docbook">
1095
+
<entry>8.0.0</entry>
1096
+
<entry>
1097
+
<parameter>handle</parameter> expects a <classname>CurlHandle</classname>
1098
+
instance now; previously, a <type>resource</type> was expected.
1099
+
</entry>
1100
+
</row>'>
1101
+
1102
+
<!ENTITY curl.changelog.multi-handle-param '<row xmlns="http://docbook.org/ns/docbook">
1103
+
<entry>8.0.0</entry>
1104
+
<entry>
1105
+
<parameter>multi_handle</parameter> expects a <classname>CurlMultiHandle</classname>
1106
+
instance now; previously, a <type>resource</type> was expected.
1107
+
</entry>
1108
+
</row>'>
1109
+
1110
+
<!ENTITY curl.changelog.share-handle-param '<row xmlns="http://docbook.org/ns/docbook">
1111
+
<entry>8.0.0</entry>
1112
+
<entry>
1113
+
<parameter>share_handle</parameter> expects a <classname>CurlShareHandle</classname>
1114
+
instance now; previously, a <type>resource</type> was expected.
1115
+
</entry>
1116
+
</row>'>
1117
+
1118
+
<!-- dbase notes -->
1119
+
1120
+
<!ENTITY dbase.type-conversion '<para xmlns="http://docbook.org/ns/docbook">
1121
+
Each field is converted to the appropriate PHP type, except:
1122
+
<itemizedlist>
1123
+
<listitem>
1124
+
<simpara>
1125
+
Dates are left as strings.
1126
+
</simpara>
1127
+
</listitem>
1128
+
<listitem>
1129
+
<simpara>
1130
+
DateTime values are converted to strings.
1131
+
</simpara>
1132
+
</listitem>
1133
+
<listitem>
1134
+
<simpara>
1135
+
Integers outside the range
1136
+
<constant>PHP_INT_MIN</constant>..<constant>PHP_INT_MAX</constant> are
1137
+
returned as strings.
1138
+
</simpara>
1139
+
</listitem>
1140
+
<listitem>
1141
+
<simpara>
1142
+
Before dbase 7.0.0, booleans (<literal>L</literal>) were converted to <literal>1</literal> or
1143
+
<literal>0</literal>.
1144
+
</simpara>
1145
+
</listitem>
1146
+
</itemizedlist>
1147
+
</para>'>
1148
+
1149
+
<!-- enchant entities -->
1150
+
1151
+
<!ENTITY enchant.param.broker '<varlistentry xmlns="http://docbook.org/ns/docbook">
1152
+
<term><parameter>broker</parameter></term>
1153
+
<listitem>
1154
+
<para>
1155
+
An Enchant broker returned by <function>enchant_broker_init</function>.
1156
+
</para>
1157
+
</listitem>
1158
+
</varlistentry>'>
1159
+
1160
+
<!ENTITY enchant.param.dictionary '<varlistentry xmlns="http://docbook.org/ns/docbook">
1161
+
<term><parameter>dictionary</parameter></term>
1162
+
<listitem>
1163
+
<para>
1164
+
An Enchant dictionary returned by <function>enchant_broker_request_dict</function>
1165
+
or <function>enchant_broker_request_pwl_dict</function>.
1166
+
</para>
1167
+
</listitem>
1168
+
</varlistentry>'>
1169
+
1170
+
<!ENTITY enchant.changelog.broker-param '<row xmlns="http://docbook.org/ns/docbook">
1171
+
<entry>8.0.0</entry>
1172
+
<entry>
1173
+
<parameter>broker</parameter> expects an <classname>EnchantBroker</classname> instance now;
1174
+
previoulsy, a &resource; was expected.
1175
+
</entry>
1176
+
</row>'>
1177
+
1178
+
<!ENTITY enchant.changelog.dictionary-param '<row xmlns="http://docbook.org/ns/docbook">
1179
+
<entry>8.0.0</entry>
1180
+
<entry>
1181
+
<parameter>dictionary</parameter> expects an <classname>EnchantDictionary</classname> instance now;
1182
+
previoulsy, a &resource; was expected.
1183
+
</entry>
1184
+
</row>'>
1185
+
608
1186
<!-- IMAP notes -->
609
1187
610
-
<!ENTITY imap.imap-stream.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
611
-
imap_stream</parameter></term><listitem><para>An IMAP stream returned by
1188
+
<!ENTITY imap.changelog.imap-param '<row xmlns="http://docbook.org/ns/docbook">
1189
+
<entry>8.1.0</entry>
1190
+
<entry>
1191
+
The <parameter>imap</parameter> parameter expects an <classname>IMAP\Connection</classname>
1192
+
instance now; previously, a valid <literal>imap</literal> &resource; was expected.
1193
+
</entry>
1194
+
</row>'>
1195
+
1196
+
<!ENTITY imap.imap-parameter.imap '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1197
+
<parameter>imap</parameter></term><listitem><para>An <classname>IMAP\Connection</classname> instance.</para></listitem></varlistentry>'>
1198
+
1199
+
<!-- Deprecated -->
1200
+
<!ENTITY imap.imap-stream.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1201
+
<parameter>imap</parameter></term><listitem><para>An IMAP stream returned by
612
1202
<function>imap_open</function>.</para></listitem></varlistentry>'>
613
1203
614
1204
<!ENTITY imap.pattern '<para xmlns="http://docbook.org/ns/docbook">Specifies where in the mailbox hierarchy
...
...
@@ -624,18 +1214,102 @@ means to return the current level only.
624
1214
parameter will return only the top level
625
1215
mailboxes; '<literal>~/mail/%</literal>' on <literal>UW_IMAPD</literal> will return every mailbox in the <filename>~/mail</filename> directory, but none in subfolders of that directory.</para>'>
626
1216
1217
+
<!ENTITY imap.mailboxname.insecure '<warning xmlns="http://docbook.org/ns/docbook"><simpara>
1218
+
Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unless
1219
+
<link linkend="ini.imap.enable-insecure-rsh">imap.enable_insecure_rsh</link> is disabled.
1220
+
</simpara></warning>'>
1221
+
627
1222
<!-- intl notes -->
628
1223
629
-
<!ENTITY intl.codepoint.parameter '<para xmlns="http://docbook.org/ns/docbook">The <type>integer</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>'>
1224
+
<!ENTITY intl.parameter.intl-calendar '<para xmlns="http://docbook.org/ns/docbook">An <classname>IntlCalendar</classname> instance.</para>'>
1225
+
1226
+
<!ENTITY intl.error.intl-calendar '<para xmlns="http://docbook.org/ns/docbook">On failure &false; is also returned. To detect error conditions use <function>intl_get_error_code</function>, or set up Intl to throw <link linkend="ini.intl.use-exceptions">exceptions</link>.</para>'>
1227
+
1228
+
<!ENTITY intl.codepoint.parameter '<para xmlns="http://docbook.org/ns/docbook">The <type>int</type> codepoint value (e.g. <literal>0x2603</literal> for <emphasis>U+2603 SNOWMAN</emphasis>), or the character encoded as a UTF-8 <type>string</type> (e.g. <literal>"\u{2603}"</literal>)</para>'>
630
1229
631
-
<!ENTITY intl.codepoint.return '<para xmlns="http://docbook.org/ns/docbook">The return type will be <type>integer</type> unless the code point was passed as a UTF-8 <type>string</type>, in which case a <type>string</type> will be returned.</para>'>
1230
+
<!ENTITY intl.codepoint.return '<para xmlns="http://docbook.org/ns/docbook">The return type is <type>int</type> unless the code point was passed as a UTF-8 <type>string</type>, in which case a <type>string</type> is returned. Returns &null; on failure.</para>'>
632
1231
633
1232
<!ENTITY intl.codepoint.example 'Testing different code points'>
634
1233
1234
+
<!ENTITY intl.locale-len.return '<para xmlns="http://docbook.org/ns/docbook">Returns &null; when the length of <parameter>locale</parameter> exceeds <constant>INTL_MAX_LOCALE_LEN</constant>.</para>'>
1235
+
635
1236
<!ENTITY intl.property.parameter '<para xmlns="http://docbook.org/ns/docbook">The Unicode property to lookup (see the <literal>IntlChar::PROPERTY_*</literal> constants).</para>'>
636
1237
637
1238
<!ENTITY intl.property.example 'Testing different properties'>
638
1239
1240
+
<!-- LDAP notes -->
1241
+
1242
+
<!ENTITY ldap.parameter.ldap 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\Connection</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_connect</function>.'>
1243
+
1244
+
<!ENTITY ldap.parameter.result 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_list</function> or <function xmlns="http://docbook.org/ns/docbook">ldap_search</function>.'>
1245
+
1246
+
<!ENTITY ldap.parameter.entry 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\ResultEntry</classname> instance.'>
1247
+
1248
+
<!ENTITY ldap.warn.control-paged '<warning xmlns="http://docbook.org/ns/docbook">
1249
+
<simpara>
1250
+
This function has been <emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.
1251
+
Instead the <parameter>controls</parameter> parameter of <function>ldap_search</function> should be used.
1252
+
See also <link linkend="ldap.controls">LDAP Controls</link> for details.
1253
+
</simpara>
1254
+
</warning>'>
1255
+
1256
+
<!ENTITY ldap.changelog.controls-nullable '<row xmlns="http://docbook.org/ns/docbook">
1257
+
<entry>8.0.0</entry>
1258
+
<entry>
1259
+
<parameter>controls</parameter> is nullable now; previously, it defaulted to <literal>[]</literal>.
1260
+
</entry>
1261
+
</row>'>
1262
+
1263
+
<!ENTITY ldap.changelog.ldap-object '<row xmlns="http://docbook.org/ns/docbook">
1264
+
<entry>8.1.0</entry>
1265
+
<entry>
1266
+
The <parameter>ldap</parameter> parameter expects an <classname>LDAP\Connection</classname>
1267
+
instance now; previously, a valid <literal>ldap link</literal> &resource; was expected.
1268
+
</entry>
1269
+
</row>'>
1270
+
1271
+
<!ENTITY ldap.changelog.entry-object '<row xmlns="http://docbook.org/ns/docbook">
1272
+
<entry>8.1.0</entry>
1273
+
<entry>
1274
+
The <parameter>entry</parameter> parameter expects an <classname>LDAP\ResultEntry</classname>
1275
+
instance now; previously, a valid <literal>ldap result entry</literal> &resource; was expected.
1276
+
</entry>
1277
+
</row>'>
1278
+
1279
+
<!ENTITY ldap.changelog.result-object '<row xmlns="http://docbook.org/ns/docbook">
1280
+
<entry>8.1.0</entry>
1281
+
<entry>
1282
+
The <parameter>result</parameter> parameter expects an <classname>LDAP\Result</classname>
1283
+
instance now; previously, a valid <literal>ldap result</literal> &resource; was expected.
1284
+
</entry>
1285
+
</row>'>
1286
+
1287
+
<!ENTITY ldap.changelog.return-result-object '<row xmlns="http://docbook.org/ns/docbook">
1288
+
<entry>8.1.0</entry>
1289
+
<entry>
1290
+
Returns an <classname>LDAP\Result</classname> instance now;
1291
+
previously, a &resource; was returned.
1292
+
</entry>
1293
+
</row>'>
1294
+
1295
+
<!ENTITY ldap.changelog.return-result-entry-object '<row xmlns="http://docbook.org/ns/docbook">
1296
+
<entry>8.1.0</entry>
1297
+
<entry>
1298
+
Returns an <classname>LDAP\ResultEntry</classname> instance now;
1299
+
previously, a &resource; was returned.
1300
+
</entry>
1301
+
</row>'>
1302
+
1303
+
<!ENTITY ldap.return-result 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance,&return.falseforfailure;.'>
1304
+
<!ENTITY ldap.return-result-array 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance, an array of <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instances,&return.falseforfailure;.'>
1305
+
1306
+
<!ENTITY ldap.return-result-array-info '<para xmlns="http://docbook.org/ns/docbook">It is also possible to perform parallel searches. In this case, the first argument should be an array of
1307
+
<classname>LDAP\Connection</classname> instances, rather than a single one.
1308
+
If the searches should not all use the same base DN and filter, an array of base DNs and/or an array of filters can be passed as arguments instead.
1309
+
These arrays must be of the same size as the <classname>LDAP\Connection</classname> instances array,
1310
+
since the first entries of the arrays are used for one search, the second entries are used for another, and so on.
1311
+
When doing parallel searches an array of <classname>LDAP\Result</classname> instances is returned, except in case of error, when the return value will be &false;.</para>'>
1312
+
639
1313
<!-- mbstring notes -->
640
1314
641
1315
<!ENTITY note.mbstring.encoding.internal '<note xmlns="http://docbook.org/ns/docbook"><para>The internal encoding or the
...
...
@@ -647,11 +1321,25 @@ character encoding specified by <function>mb_regex_encoding</function>
647
1321
will be used as the character encoding for this function by default.</para></note>'>
648
1322
649
1323
<!ENTITY mbstring.encoding.parameter '<para xmlns="http://docbook.org/ns/docbook">The <parameter>encoding</parameter>
650
-
parameter is the character encoding. If it is omitted, the internal character
1324
+
parameter is the character encoding. If it is omitted or &null;, the internal character
651
1325
encoding value will be used.</para>'>
652
1326
653
1327
<!ENTITY mbstring.warning.e-modifier '<warning xmlns="http://docbook.org/ns/docbook"><para>Never use the <literal>e</literal> modifier when working on untrusted input. No automatic escaping will happen (as known from <function>preg_replace</function>). Not taking care of this will most likely create remote code execution vulnerabilities in your application.</para></warning>'>
654
1328
1329
+
<!ENTITY mbstring.changelog.encoding-nullable '<row xmlns="http://docbook.org/ns/docbook">
1330
+
<entry>8.0.0</entry>
1331
+
<entry>
1332
+
<parameter>encoding</parameter> is nullable now.
1333
+
</entry>
1334
+
</row>'>
1335
+
1336
+
<!ENTITY mbstring.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
1337
+
<entry>8.0.0</entry>
1338
+
<entry>
1339
+
<parameter>needle</parameter> now accepts an empty string.
1340
+
</entry>
1341
+
</row>'>
1342
+
655
1343
<!-- mcrypt notes -->
656
1344
657
1345
<!ENTITY mcrypt.parameter.cipher '<para xmlns="http://docbook.org/ns/docbook">One of the <constant>MCRYPT_ciphername</constant> constants, or the name of the algorithm as string.</para>'>
...
...
@@ -664,12 +1352,20 @@ encoding value will be used.</para>'>
664
1352
665
1353
<!-- MCVE notes -->
666
1354
667
-
<!ENTITY mcve.conn.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
668
-
conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
1355
+
<!ENTITY mcve.conn.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1356
+
<parameter>conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
669
1357
<function>m_initengine</function>.</para></listitem></varlistentry>'>
670
1358
671
1359
<!-- memcached notes -->
672
1360
1361
+
<!ENTITY memcached.note.delete-time '<note xmlns="http://docbook.org/ns/docbook"><simpara>
1362
+
As of memcached 1.3.0 (released 2009) this feature is no longer
1363
+
supported. Passing a non-zero <parameter>time</parameter> will cause
1364
+
the deletion to fail. <methodname>Memcached::getResultCode</methodname>
1365
+
will return <constant>MEMCACHED_INVALID_ARGUMENTS</constant>.
1366
+
</simpara></note>
1367
+
'>
1368
+
673
1369
<!ENTITY memcached.parameter.expiration 'The expiration time, defaults to 0. See <link
674
1370
linkend="memcached.expiration" xmlns="http://docbook.org/ns/docbook">Expiration Times</link> for more info.'>
675
1371
...
...
@@ -683,6 +1379,19 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
683
1379
684
1380
<!ENTITY memcached.result.getresultcode 'Use <methodname xmlns="http://docbook.org/ns/docbook">Memcached::getResultCode</methodname> if necessary.'>
685
1381
1382
+
<!ENTITY memcached.result.delete-multi '<para xmlns="http://docbook.org/ns/docbook">
1383
+
Returns an array indexed by <parameter>keys</parameter>. Each element
1384
+
is &true; if the corresponding key was deleted, or one of the
1385
+
<constant>Memcached::RES_*</constant> constants if the corresponding deletion
1386
+
failed.
1387
+
</para>
1388
+
<para xmlns="http://docbook.org/ns/docbook">
1389
+
The <methodname>Memcached::getResultCode</methodname> will return
1390
+
the result code for the last executed delete operation, that is, the delete
1391
+
operation for the last element of <parameter>keys</parameter>.
1392
+
</para>
1393
+
'>
1394
+
686
1395
<!-- password notes -->
687
1396
688
1397
<!ENTITY password.parameter.algo 'A <link xmlns="http://docbook.org/ns/docbook" linkend="password.constants">password algorithm constant</link> denoting the algorithm to use when hashing the password.'>
...
...
@@ -693,6 +1402,54 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
693
1402
694
1403
<!ENTITY password.parameter.password 'The user's password.'>
695
1404
1405
+
<!-- pspell notes -->
1406
+
1407
+
<!ENTITY pspell.changelog.pspell-dictionary '<row xmlns="http://docbook.org/ns/docbook">
1408
+
<entry>8.1.0</entry>
1409
+
<entry>
1410
+
The <parameter>dictionary</parameter> parameter expects an <classname>PSpell\Dictionary</classname>
1411
+
instance now; previously, a &resource; was expected.
1412
+
</entry>
1413
+
</row>'>
1414
+
1415
+
<!ENTITY pspell.changelog.pspell-config '<row xmlns="http://docbook.org/ns/docbook">
1416
+
<entry>8.1.0</entry>
1417
+
<entry>
1418
+
The <parameter>config</parameter> parameter expects an <classname>PSpell\Config</classname>
1419
+
instance now; previously, a &resource; was expected.
1420
+
</entry>
1421
+
</row>'>
1422
+
1423
+
<!ENTITY pspell.parameter.pspell-dictionary '<para xmlns="http://docbook.org/ns/docbook">An <classname>PSpell\Dictionary</classname> instance.</para>'>
1424
+
1425
+
<!ENTITY pspell.parameter.pspell-config '<para xmlns="http://docbook.org/ns/docbook">An <classname>PSpell\Config</classname> instance.</para>'>
1426
+
1427
+
<!-- RNP -->
1428
+
1429
+
<!ENTITY rnp.parameter.ffi-description 'The FFI object returned by rnp_ffi_create.'>
1430
+
1431
+
<!ENTITY rnp.parameter.key-format 'The key format of the data (GPG, KBX, G10).'>
1432
+
1433
+
<!ENTITY rnp.parameter.loadsave-flags 'See RNP_LOAD_SAVE_* flags description.'>
1434
+
1435
+
<!-- socket entities -->
1436
+
1437
+
<!ENTITY sockets.changelog.socket-param '<row xmlns="http://docbook.org/ns/docbook">
1438
+
<entry>8.0.0</entry>
1439
+
<entry>
1440
+
<parameter>socket</parameter> is a <classname>Socket</classname> instance now;
1441
+
previously, it was a <type>resource</type>.
1442
+
</entry>
1443
+
</row>'>
1444
+
1445
+
<!ENTITY sockets.changelog.address-param '<row xmlns="http://docbook.org/ns/docbook">
1446
+
<entry>8.0.0</entry>
1447
+
<entry>
1448
+
<parameter>address</parameter> is an <classname>AddressInfo</classname> instance now;
1449
+
previously, it was a <type>resource</type>.
1450
+
</entry>
1451
+
</row>'>
1452
+
696
1453
<!-- geaman notes -->
697
1454
698
1455
<!ENTITY gearman.parameter.host 'The job server host name.'>
...
...
@@ -717,12 +1474,14 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
717
1474
<!ENTITY date.timezone.intro "<para xmlns='http://docbook.org/ns/docbook'>
718
1475
Here you'll find the complete list of timezones supported by PHP, which are
719
1476
meant to be used with e.g. <function>date_default_timezone_set</function>.
1477
+
<caution><simpara>The behavior of timezones not listed here is undefined.</simpara></caution>
720
1478
</para><note xmlns='http://docbook.org/ns/docbook'><simpara>The latest version of the timezone database can be
721
1479
installed via PECL's <link xlink:href='&url.pecl.package.get;timezonedb' xmlns:xlink='http://www.w3.org/1999/xlink'>timezonedb</link>.
722
1480
</simpara></note>">
723
1481
724
1482
<!ENTITY date.timezone.bc '<simpara xmlns="http://docbook.org/ns/docbook">Please do not use any of the timezones
725
-
listed here (besides UTC), they only exist for backward compatible reasons.
1483
+
listed here (besides UTC), they only exist for backward compatible reasons, and may expose erroneous behavior.
1484
+
Furthermore, these timezones may be removed from the IANA timezone database at any time.
726
1485
</simpara>'>
727
1486
728
1487
<!ENTITY date.timezone.posix-signs '<simpara xmlns="http://docbook.org/ns/docbook">
...
...
@@ -750,11 +1509,8 @@ It is strongly recommended to avoid timezone abbreviations.
750
1509
</simpara>'>
751
1510
752
1511
<!ENTITY date.timezone.errors.description '<para xmlns="http://docbook.org/ns/docbook">
753
-
Every call to a date/time function will generate a <constant>E_NOTICE</constant>
754
-
if the time zone is not valid, and/or a <constant>E_STRICT</constant>
755
-
or <constant>E_WARNING</constant> message
756
-
if using the system settings or the <varname>TZ</varname> environment
757
-
variable. See also <function>date_default_timezone_set</function></para>'>
1512
+
Every call to a date/time function will generate a <constant>E_WARNING</constant>
1513
+
if the time zone is not valid. See also <function>date_default_timezone_set</function></para>'>
758
1514
759
1515
<!ENTITY date.timezone.errors.changelog '<row xmlns="http://docbook.org/ns/docbook"><entry>5.1.0</entry><entry><para>
760
1516
Now issues the <constant>E_STRICT</constant> and <constant>E_NOTICE</constant>
...
...
@@ -763,8 +1519,8 @@ time zone errors.</para></entry></row>'>
763
1519
<!ENTITY date.timestamp.description '
764
1520
<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>timestamp</parameter></term><listitem><para>
765
1521
The optional <parameter>timestamp</parameter> parameter is an
766
-
<type>integer</type> Unix timestamp that defaults to the current
767
-
local time if a <parameter>timestamp</parameter> is not given. In other
1522
+
<type>int</type> Unix timestamp that defaults to the current
1523
+
local time if <parameter>timestamp</parameter> is omitted or &null;. In other
768
1524
words, it defaults to the value of <function>time</function>.
769
1525
</para></listitem></varlistentry>'>
770
1526
...
...
@@ -777,14 +1533,14 @@ returned by <function>date_create</function></para></listitem></varlistentry>'>
777
1533
returned by <function>date_create</function>.
778
1534
The function modifies this object.</para></listitem></varlistentry>'>
779
1535
780
-
<!ENTITY date.datetimezone.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
781
-
object</parameter></term><listitem><para>Procedural style only: A <classname>DateTimeZone</classname> object
1536
+
<!ENTITY date.datetimezone.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1537
+
<parameter>object</parameter></term><listitem><para>Procedural style only: A <classname>DateTimeZone</classname> object
782
1538
returned by <function>timezone_open</function></para></listitem></varlistentry>'>
783
1539
784
-
<!ENTITY date.datetime.retval.changelog '<row xmlns="http://docbook.org/ns/docbook"><entry>5.3.0</entry><entry>Changed the
785
-
return value on success from &null; to <classname>DateTime</classname>.</entry></row>'>
786
-
787
-
<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining&return.falseforfailure;.'>
1540
+
<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the modified <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining&return.falseforfailure;.'>
1541
+
<!ENTITY date.datetime.return.modifiedobject 'Returns the modified <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining.'>
1542
+
<!ENTITY date.datetimeimmutable.return.modifiedobjectorfalseforfailure 'Returns a new <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object with the modified data &return.falseforfailure;.'>
1543
+
<!ENTITY date.datetimeimmutable.return.modifiedobject 'Returns a new <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object with the modified data.'>
788
1544
789
1545
<!ENTITY date.timezone.dbversion 'This list is based upon the timezone database version'>
790
1546
...
...
@@ -813,8 +1569,11 @@ is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">domnode_
813
1569
<!ENTITY dom.node.inserted 'This node will not show up in the document unless
814
1570
it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNode::appendChild</function>.'>
815
1571
816
-
<!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>'>
817
1572
<!ENTITY dom.malformederror '<para xmlns="http://docbook.org/ns/docbook">While malformed HTML should load successfully, this function may generate <constant>E_WARNING</constant> errors when it encounters bad markup. <link linkend="function.libxml-use-internal-errors">libxml's error handling functions</link> may be used to handle these errors.</para>'>
1573
+
<!ENTITY dom.note.utf8 '<note xmlns="http://docbook.org/ns/docbook"><para>The DOM extension uses UTF-8 encoding. Use <function>mb_convert_encoding</function>, <methodname>UConverter::transcode</methodname>, or <function>iconv</function> to handle other encodings.</para></note>'>
1574
+
<!ENTITY dom.note.json '<note xmlns="http://docbook.org/ns/docbook"><para>When using <function>json_encode</function> on a <classname>DOMDocument</classname> object the result will be that of encoding an empty object.</para></note>'>
1575
+
1576
+
818
1577
819
1578
<!-- Dom Examples -->
820
1579
<!ENTITY dom.book.example '<para xmlns="http://docbook.org/ns/docbook">The following examples use <filename>book.xml</filename> which contains the following:</para>
...
...
@@ -850,6 +1609,77 @@ it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNo
850
1609
</books>
851
1610
]]></programlisting>'>
852
1611
1612
+
<!-- Dom entities -->
1613
+
<!ENTITY dom.parameter.options '<para xmlns="http://docbook.org/ns/docbook">
1614
+
<link linkend="language.operators.bitwise">Bitwise <literal>OR</literal></link>
1615
+
of the <link linkend="libxml.constants">libxml option constants</link>.
1616
+
</para>'>
1617
+
1618
+
<!ENTITY dom.parameters.register_node_ns '<varlistentry xmlns="http://docbook.org/ns/docbook">
1619
+
<term><parameter>registerNodeNS</parameter></term>
1620
+
<listitem>
1621
+
<para>
1622
+
Whether to automatically register the in-scope namespace prefixes of the context node to the <classname>DOMXPath</classname> object.
1623
+
This can be used to avoid needing to call <methodname>DOMXPath::registerNamespace</methodname> manually for each in-scope namespaces.
1624
+
When a namespace prefix conflict exists, only the nearest descendant namespace prefix is registered.
1625
+
</para>
1626
+
</listitem>
1627
+
</varlistentry>'>
1628
+
1629
+
<!ENTITY dom.errors.hierarchy.parent '<varlistentry xmlns="http://docbook.org/ns/docbook">
1630
+
<term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
1631
+
<listitem>
1632
+
<para>
1633
+
Raised if the parent is of a type that does not allow children of the
1634
+
type of one of the passed <parameter>nodes</parameter>, or if the node to
1635
+
put in is one of this node's ancestors or this node itself.
1636
+
</para>
1637
+
</listitem>
1638
+
</varlistentry>'>
1639
+
1640
+
<!ENTITY dom.errors.hierarchy.self '<varlistentry xmlns="http://docbook.org/ns/docbook">
1641
+
<term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
1642
+
<listitem>
1643
+
<para>
1644
+
Raised if this node is of a type that does not allow children of the
1645
+
type of one of the passed <parameter>nodes</parameter>, or if the node to
1646
+
put in is one of this node's ancestors or this node itself.
1647
+
</para>
1648
+
</listitem>
1649
+
</varlistentry>'>
1650
+
1651
+
<!ENTITY dom.errors.wrong_document '<varlistentry xmlns="http://docbook.org/ns/docbook">
1652
+
<term><constant>DOM_WRONG_DOCUMENT_ERR</constant></term>
1653
+
<listitem>
1654
+
<para>
1655
+
Raised if one of the passed <parameter>nodes</parameter> was created from a different
1656
+
document than the one that created this node.
1657
+
</para>
1658
+
</listitem>
1659
+
</varlistentry>'>
1660
+
1661
+
<!ENTITY dom.changelog.previous_hierarchy_exception 'Previously this threw a
1662
+
<classname xmlns="http://docbook.org/ns/docbook">DOMException</classname> with code
1663
+
<constant xmlns="http://docbook.org/ns/docbook">DOM_HIERARCHY_REQUEST_ERR</constant>.'>
1664
+
1665
+
<!ENTITY dom.c14n.xpath_array '<listitem xmlns="http://docbook.org/ns/docbook">
1666
+
<para>
1667
+
An array of XPaths to filter the nodes by.
1668
+
Each entry in this array is an associative array with:
1669
+
<itemizedlist>
1670
+
<listitem>
1671
+
<simpara>
1672
+
A required <literal>query</literal> key containing the XPath expression as a string.
1673
+
</simpara>
1674
+
</listitem>
1675
+
<listitem>
1676
+
<simpara>
1677
+
An optional <literal>namespaces</literal> key containing an array that maps namespace prefixes (keys) to namespace URIs (values).
1678
+
</simpara>
1679
+
</listitem>
1680
+
</itemizedlist>
1681
+
</para>
1682
+
</listitem>'>
853
1683
854
1684
<!-- FileSystem entities -->
855
1685
<!ENTITY fs.emits.warning.on.failure '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -892,8 +1722,15 @@ that is typically created using <function>fopen</function>.</para>'>
892
1722
<!ENTITY odbc.connection.id '<para xmlns="http://docbook.org/ns/docbook">The ODBC connection identifier,
893
1723
see <function>odbc_connect</function> for details.</para>'>
894
1724
1725
+
<!ENTITY odbc.parameter.catalog 'The catalog ('qualifier' in ODBC 2 parlance).'>
1726
+
1727
+
<!ENTITY odbc.parameter.schema 'The schema ('owner' in ODBC 2 parlance).'>
1728
+
895
1729
<!ENTITY odbc.parameter.search 'This parameter accepts the following search patterns:
896
-
"%" to match zero or more characters, and "_" to match a single character.'>
1730
+
<literal xmlns="http://docbook.org/ns/docbook">%</literal> to match zero or more characters,
1731
+
and <literal xmlns="http://docbook.org/ns/docbook">_</literal> to match a single character.'>
1732
+
1733
+
<!ENTITY odbc.result.driver-specific 'Drivers can report additional columns.'>
897
1734
898
1735
<!-- OAUTH -->
899
1736
<!ENTITY oauth.callback.error 'Emits an <constant xmlns="http://docbook.org/ns/docbook">E_ERROR</constant> level
...
...
@@ -909,7 +1746,7 @@ string</link>, or a Connect Name from
909
1746
the <filename>tnsnames.ora</filename> file, or the name of a local
910
1747
Oracle instance.
911
1748
</para>
912
-
<para xmlns='http://docbook.org/ns/docbook'>If not specified, PHP uses
1749
+
<para xmlns='http://docbook.org/ns/docbook'>If not specified or &null;, PHP uses
913
1750
environment variables such as <constant>TWO_TASK</constant> (on Linux)
914
1751
or <constant>LOCAL</constant> (on Windows)
915
1752
and <constant>ORACLE_SID</constant> to determine the
...
...
@@ -922,18 +1759,18 @@ To use the Easy Connect naming method, PHP must be linked with Oracle
922
1759
<emphasis>[//]host_name[:port][/service_name]</emphasis>. From Oracle
923
1760
11<emphasis>g</emphasis>, the syntax is:
924
1761
<emphasis>[//]host_name[:port][/service_name][:server_type][/instance_name]</emphasis>.
925
-
Service names can be found by running the Oracle
926
-
utility <literal>lsnrctl status</literal> on the database server
1762
+
Further options were introduced with Oracle 19c, including timeout and keep-alive
1763
+
settings. Refer to Oracle documentation. Service names can be found by running
1764
+
the Oracle utility <literal>lsnrctl status</literal> on the database server
927
1765
machine.
928
1766
</para>
929
1767
<para xmlns='http://docbook.org/ns/docbook'>
930
-
The <filename>tnsnames.ora</filename> file can be in the Oracle Net
931
-
search path, which
932
-
includes <filename>$ORACLE_HOME/network/admin</filename>
933
-
and <filename>/etc</filename>. Alternatively
934
-
set <literal>TNS_ADMIN</literal> so
935
-
that <filename>$TNS_ADMIN/tnsnames.ora</filename> is read. Make sure
936
-
the web daemon has read access to the file.
1768
+
The <filename>tnsnames.ora</filename> file can be in the Oracle Net search path,
1769
+
which
1770
+
includes <filename>/your/path/to/instantclient/network/admin</filename>, <filename>$ORACLE_HOME/network/admin</filename>
1771
+
and <filename>/etc</filename>. Alternatively set <literal>TNS_ADMIN</literal>
1772
+
so that <filename>$TNS_ADMIN/tnsnames.ora</filename> is read. Make sure the web
1773
+
daemon has read access to the file.
937
1774
</para>">
938
1775
939
1776
<!ENTITY oci.charset "<para xmlns='http://docbook.org/ns/docbook'>Determines
...
...
@@ -998,8 +1835,8 @@ OCI8 or the Oracle Database, the client information can be set using the Oracle
998
1835
<literal>DBMS_APPLICATION_INFO</literal> package. This is less efficient than
999
1836
using <function>oci_set_client_info</function>.</para></tip>'>
1000
1837
1001
-
<!ENTITY oci.roundtrip.caution '<caution xmlns="http://docbook.org/ns/docbook"><title>Roundtrip Gotcha</title>
1002
-
<para>Some but not all OCI8 functions cause roundtrips. Roundtrips to the
1838
+
<!ENTITY oci.roundtrip.caution '<caution xmlns="http://docbook.org/ns/docbook"><title>Round-trip Gotcha</title>
1839
+
<para>Some but not all OCI8 functions cause round-trips. Round-trips to the
1003
1840
database may not occur with queries when result caching is enabled.
1004
1841
</para></caution>'>
1005
1842
...
...
@@ -1028,13 +1865,17 @@ is printed or viewed but it will show up if the document is converted to
1028
1865
pdf by either Acrobat Distiller™ or Ghostview.</para>'>
1029
1866
1030
1867
<!-- Notes for safe-mode limited functions: -->
1868
+
1869
+
<!-- Not used in EN anymore -->
1031
1870
<!ENTITY note.sm.disabled '<note xmlns="http://docbook.org/ns/docbook"><simpara>&sm.disabled;</simpara></note>'>
1032
1871
1872
+
<!-- Not used in EN anymore -->
1033
1873
<!ENTITY note.sm.uidcheck '<note xmlns="http://docbook.org/ns/docbook"><simpara>When <link
1034
1874
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether
1035
1875
the files or directories being operated upon have the same UID (owner) as the
1036
1876
script that is being executed.</simpara></note>'>
1037
1877
1878
+
<!-- Not used in EN anymore -->
1038
1879
<!ENTITY note.sm.uidcheck.dir '<note xmlns="http://docbook.org/ns/docbook"><simpara>When <link
1039
1880
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether
1040
1881
the directory in which the script is operating has the same UID (owner) as the
...
...
@@ -1046,29 +1887,36 @@ linkend="ini.open-basedir">open_basedir</link>.</para></note>'>
1046
1887
1047
1888
<!ENTITY note.language-construct '<note xmlns="http://docbook.org/ns/docbook"><simpara>Because this is a
1048
1889
language construct and not a function, it cannot be called using
1049
-
<link linkend="functions.variable-functions">variable functions</link>.</simpara>
1890
+
<link linkend="functions.variable-functions">variable functions</link>,
1891
+
or <link linkend="functions.named-arguments">named arguments</link>.</simpara>
1050
1892
</note>'>
1051
1893
1052
1894
<!-- Common pieces in features/safe-mode.xml
1053
1895
Jade doesn't allow in-line entities, so I put them here... Though they
1054
1896
should have been inline in safe-mode.xml -->
1897
+
1898
+
<!-- Not used in EN anymore -->
1055
1899
<!ENTITY sm.uidcheck 'Checks whether the files or directories being operated
1056
1900
upon have the same UID (owner) as the script that is being executed.'>
1057
1901
1902
+
<!-- Not used in EN anymore -->
1058
1903
<!ENTITY warn.sm.exec '<warning xmlns="http://docbook.org/ns/docbook"><simpara>With <link linkend="features.safe-mode">safe mode</link> enabled,
1059
1904
the command string is escaped with <function>escapeshellcmd</function>. Thus,
1060
1905
<literal>echo y | echo x</literal> becomes <literal>echo y \| echo x</literal>.</simpara></warning>'>
1061
1906
1907
+
<!-- Not used in EN anymore -->
1062
1908
<!ENTITY note.exec-path '<note xmlns="http://docbook.org/ns/docbook"><simpara>When
1063
1909
<link linkend="features.safe-mode">safe mode</link> is enabled, you can only
1064
1910
execute files within the <link linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
1065
1911
For practical reasons, it is currently not allowed to have <literal>..</literal>
1066
1912
components in the path to the executable.</simpara></note>'>
1067
1913
1914
+
<!-- Not used in EN anymore -->
1068
1915
<!ENTITY sm.uidcheck.dir 'Checks whether the directory in which
1069
1916
the script is operating has the same UID (owner) as the script that is being
1070
1917
executed.'>
1071
1918
1919
+
<!-- Not used in EN anymore -->
1072
1920
<!ENTITY sm.disabled 'This function is disabled when PHP is running in <link xmlns="http://docbook.org/ns/docbook"
1073
1921
linkend="features.safe-mode">safe mode</link>.'>
1074
1922
...
...
@@ -1092,7 +1940,7 @@ The behaviour of these functions is affected by settings in &php.ini;.
1092
1940
</simpara>'>
1093
1941
1094
1942
<!ENTITY ini.php.constants 'For further details and definitions of the
1095
-
PHP_INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>
1943
+
INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>
1096
1944
1097
1945
<!-- Used in reference/$extname/constants.xml -->
1098
1946
<!ENTITY extension.constants '<simpara xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1123,17 +1971,26 @@ compiled into PHP or dynamically loaded at runtime. In addition, these
1123
1971
driver-specific constants should only be used if you are using this driver.
1124
1972
Using driver-specific attributes with another driver may result in
1125
1973
unexpected behaviour. <function>PDO::getAttribute</function> may be used to
1126
-
obtain the <constant>PDO_ATTR_DRIVER_NAME</constant> attribute to check the
1974
+
obtain the <constant>PDO::ATTR_DRIVER_NAME</constant> attribute to check the
1127
1975
driver, if your code can run against multiple drivers.</simpara>'>
1128
1976
1129
1977
<!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>'>
1130
1978
1979
+
<!-- PDO errors -->
1980
+
1981
+
<!ENTITY pdo.errors '<para xmlns="http://docbook.org/ns/docbook">
1982
+
Emits an error with level <constant>E_WARNING</constant> if the attribute <constant>PDO::ATTR_ERRMODE</constant> is set
1983
+
to <constant>PDO::ERRMODE_WARNING</constant>.
1984
+
</para>
1985
+
<para xmlns="http://docbook.org/ns/docbook">
1986
+
Throws a <classname>PDOException</classname> if the attribute <constant>PDO::ATTR_ERRMODE</constant>
1987
+
is set to <constant>PDO::ERRMODE_EXCEPTION</constant>.
1988
+
</para>'>
1989
+
1131
1990
<!-- PECL entities -->
1132
-
<!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
1133
-
is not bundled with PHP.'>
1991
+
<!ENTITY pecl.moved 'This &link.pecl; extension is not bundled with PHP.'>
1134
1992
1135
-
<!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
1136
-
is bundled with PHP.'>
1993
+
<!ENTITY pecl.bundled 'This &link.pecl; extension is bundled with PHP.'>
1137
1994
1138
1995
<!ENTITY pecl.info 'Information for installing this PECL extension may be
1139
1996
found in the manual chapter titled <link xmlns="http://docbook.org/ns/docbook" linkend="install.pecl">Installation
...
...
@@ -1145,22 +2002,83 @@ located here: '>
1145
2002
this extension is still available within <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym>
1146
2003
<acronym xmlns="http://docbook.org/ns/docbook">SVN</acronym> here: '>
1147
2004
2005
+
<!ENTITY pecl.info.dead.git 'This extension is considered unmaintained and dead. However, the source code for
2006
+
this extension is still available within <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym>
2007
+
<acronym xmlns="http://docbook.org/ns/docbook">GIT</acronym> here: '>
2008
+
1148
2009
<!ENTITY pecl.windows.download 'A <acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> for this
1149
2010
<acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension is currently unavailable. See also the
1150
-
<link xmlns="http://docbook.org/ns/docbook" linkend="install.windows.legacy.building">building on Windows</link>
2011
+
<link xmlns="http://docbook.org/ns/docbook" linkend="install.windows.building">building on Windows</link>
1151
2012
section.'>
1152
2013
1153
-
<!ENTITY pecl.windows.download.unbundled '&pecl.windows.download;'>
2014
+
<!ENTITY pecl.windows.download.avail 'Windows binaries (<acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> files)
2015
+
for this <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension are available from the PECL website.'>
1154
2016
1155
-
<!ENTITY pecl.moved-ver 'This extension has been moved to the
1156
-
<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
1157
-
PHP as of PHP '>
2017
+
<!ENTITY pecl.windows.download.unbundled '&pecl.windows.download;'>
1158
2018
1159
-
<!-- kept for BC -->
1160
-
<!ENTITY note.pecl-php5 '<note xmlns="http://docbook.org/ns/docbook"><simpara>
1161
-
This extension has been removed as of PHP 5 and moved to the
1162
-
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> repository.
1163
-
</simpara></note>'>
2019
+
<!ENTITY pecl.moved-ver 'This extension has been moved to the &link.pecl;
2020
+
repository and is no longer bundled with PHP as of PHP '>
2021
+
2022
+
<!-- PGSQL entities -->
2023
+
2024
+
<!ENTITY pgsql.parameter.connection '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.</para>'>
2025
+
2026
+
<!ENTITY pgsql.parameter.connection-with-unspecified-default '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.
2027
+
When <parameter>connection</parameter> is unspecified, the default connection is used.
2028
+
The default connection is the last connection made by <function>pg_connect</function>
2029
+
or <function>pg_pconnect</function>.
2030
+
<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>
2031
+
2032
+
<!ENTITY pgsql.parameter.connection-with-nullable-default '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.
2033
+
When <parameter>connection</parameter> is &null;, the default connection is used.
2034
+
The default connection is the last connection made by <function>pg_connect</function>
2035
+
or <function>pg_pconnect</function>.
2036
+
<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>
2037
+
2038
+
<!ENTITY pgsql.parameter.result '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Result</classname> instance, returned by <function>pg_query</function>,
2039
+
<function>pg_query_params</function> or <function>pg_execute</function>(among others).</para>'>
2040
+
2041
+
<!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>'>
2042
+
2043
+
<!ENTITY pgsql.parameter.mode '<para xmlns="http://docbook.org/ns/docbook">
2044
+
An optional parameter that controls how the returned <type>array</type> is indexed.
2045
+
<parameter>mode</parameter> is a constant and can take the following values:
2046
+
<constant>PGSQL_ASSOC</constant>, <constant>PGSQL_NUM</constant> and <constant>PGSQL_BOTH</constant>.
2047
+
Using <constant>PGSQL_NUM</constant>, the function will return an array with numerical indices,
2048
+
using <constant>PGSQL_ASSOC</constant> it will return only associative indices
2049
+
while <constant>PGSQL_BOTH</constant> will return both numerical and associative indices.</para>'>
2050
+
2051
+
<!ENTITY pgsql.changelog.connection-object '<row xmlns="http://docbook.org/ns/docbook">
2052
+
<entry>8.1.0</entry>
2053
+
<entry>
2054
+
The <parameter>connection</parameter> parameter expects an <classname>PgSql\Connection</classname>
2055
+
instance now; previously, a &resource; was expected.
2056
+
</entry>
2057
+
</row>'>
2058
+
2059
+
<!ENTITY pgsql.changelog.result-object '<row xmlns="http://docbook.org/ns/docbook">
2060
+
<entry>8.1.0</entry>
2061
+
<entry>
2062
+
The <parameter>result</parameter> parameter expects an <classname>PgSql\Result</classname>
2063
+
instance now; previously, a &resource; was expected.
2064
+
</entry>
2065
+
</row>'>
2066
+
2067
+
<!ENTITY pgsql.changelog.lob-object '<row xmlns="http://docbook.org/ns/docbook">
2068
+
<entry>8.1.0</entry>
2069
+
<entry>
2070
+
The <parameter>lob</parameter> parameter expects an <classname>PgSql\Lob</classname>
2071
+
instance now; previously, a &resource; was expected.
2072
+
</entry>
2073
+
</row>'>
2074
+
2075
+
<!ENTITY pgsql.changelog.return-result-object '<row xmlns="http://docbook.org/ns/docbook">
2076
+
<entry>8.1.0</entry>
2077
+
<entry>
2078
+
Returns an <classname>PgSql\Result</classname> instance now;
2079
+
previously, a &resource; was returned.
2080
+
</entry>
2081
+
</row>'>
1164
2082
1165
2083
<!-- Common pieces for reference part END -->
1166
2084
...
...
@@ -1175,8 +2093,8 @@ extensions in order to use these functions.</simpara>'>
1175
2093
<!ENTITY sqlsafemode '<link xmlns="http://docbook.org/ns/docbook" linkend="ini.sql.safe-mode">SQL safe mode</link>'>
1176
2094
1177
2095
<!-- APD Notes -->
1178
-
<!ENTITY apd.debug-level.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1179
-
debug_level</parameter></term><listitem><para>An integer which is formed by adding
2096
+
<!ENTITY apd.debug-level.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2097
+
<parameter>debug_level</parameter></term><listitem><para>An integer which is formed by adding
1180
2098
together the <literal>XXX_TRACE</literal> constants.</para><para>It is not recommended
1181
2099
to use <constant>MEMORY_TRACE</constant>. It is very slow and does not appear to be accurate.
1182
2100
<constant>ASSIGNMENT_TRACE</constant> is not implemented yet.</para><para>To turn on all
...
...
@@ -1184,49 +2102,52 @@ functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the val
1184
2102
</listitem></varlistentry>'>
1185
2103
1186
2104
<!-- BCMath Notes -->
1187
-
<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1188
-
scale</parameter></term><listitem><para>This optional parameter is used to set the number
2105
+
<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2106
+
<parameter>scale</parameter></term><listitem><para>This optional parameter is used to set the number
1189
2107
of digits after the decimal place in the result. If omitted, it will default to the scale set
1190
2108
globally with the <function>bcscale</function> function, or fallback to <literal>0</literal> if
1191
2109
this has not been set.</para></listitem></varlistentry>'>
1192
2110
1193
2111
<!-- CTYPE Notes -->
1194
2112
<!ENTITY note.ctype.parameter.integer '<note xmlns="http://docbook.org/ns/docbook"><para>
1195
-
If an <type>integer</type> between -128 and 255 inclusive is provided, it is interpreted as
2113
+
If an <type>int</type> between -128 and 255 inclusive is provided, it is interpreted as
1196
2114
the ASCII value of a single character (negative values have 256 added in order to allow
1197
2115
characters in the Extended ASCII range). Any other integer is interpreted as a string
1198
2116
containing the decimal digits of the integer.</para></note>'>
1199
2117
1200
-
<!-- FBSQL Notes -->
1201
-
<!ENTITY fbsql.link-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1202
-
link_identifier</parameter></term><listitem><para>A FrontBase link identifier
1203
-
returned by <function>fbsql_connect</function> or
1204
-
<function>fbsql_pconnect</function>.</para><para>If optional and not specified,
1205
-
the function will try to find an open link to the FrontBase server and if no
1206
-
such link is found it will try to create one as if
1207
-
<function>fbsql_connect</function> was called with no arguments.</para>
1208
-
</listitem></varlistentry>'>
2118
+
<!ENTITY note.ctype.parameter.non-string '<warning xmlns="http://docbook.org/ns/docbook"><para>
2119
+
As of PHP 8.1.0, passing a non-string argument is deprecated.
2120
+
In the future, the argument will be interpreted as a string instead of an ASCII codepoint.
2121
+
Depending on the intended behavior, the argument should either be cast to &string;
2122
+
or an explicit call to <function>chr</function> should be made.</para></warning>'>
2123
+
2124
+
<!ENTITY ctype.result.empty-string 'When called with an empty string the result will always be &false;.'>
1209
2125
1210
-
<!ENTITY fbsql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1211
-
result</parameter></term><listitem><para>A result identifier
1212
-
returned by <function>fbsql_query</function> or
1213
-
<function>fbsql_db_query</function>.</para></listitem></varlistentry>'>
2126
+
<!-- FTP Notes -->
2127
+
<!ENTITY ftp.changelog.ftp-param '<row xmlns="http://docbook.org/ns/docbook">
2128
+
<entry>8.1.0</entry>
2129
+
<entry>
2130
+
The <parameter>ftp</parameter> parameter expects an <classname>FTP\Connection</classname>
2131
+
instance now; previously, a &resource; was expected.
2132
+
</entry>
2133
+
</row>'>
2134
+
<!ENTITY ftp.parameter.ftp '<para xmlns="http://docbook.org/ns/docbook">An <classname>FTP\Connection</classname> instance.</para>'>
1214
2135
1215
2136
<!-- GMP Notes -->
1216
-
<!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.'>
1217
-
<!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>'>
2137
+
<!ENTITY gmp.return 'A <classname xmlns="http://docbook.org/ns/docbook">GMP</classname> object.'>
2138
+
<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">A <classname>GMP</classname> object, an &integer; or a numeric &string;.</para>'>
1218
2139
1219
2140
<!-- MySQLi Notes -->
1220
-
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1221
-
result</parameter></term><listitem><para>Procedural style only: A result set
1222
-
identifier returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>
1223
-
or <function>mysqli_use_result</function>.</para></listitem></varlistentry>'>
1224
-
<!ENTITY mysqli.link.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1225
-
link</parameter></term><listitem><para>Procedural style only: A link identifier
2141
+
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2142
+
<parameter>result</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_result</classname>
2143
+
object returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>,
2144
+
<function>mysqli_use_result</function> or <function>mysqli_stmt_get_result</function>.</para></listitem></varlistentry>'>
2145
+
<!ENTITY mysqli.link.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2146
+
<parameter>mysql</parameter></term><listitem><para>Procedural style only: A <classname>mysqli</classname> object
1226
2147
returned by <function>mysqli_connect</function> or <function>mysqli_init</function>
1227
2148
</para></listitem></varlistentry>'>
1228
-
<!ENTITY mysqli.stmt.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1229
-
stmt</parameter></term><listitem><para>Procedural style only: A statement identifier
2149
+
<!ENTITY mysqli.stmt.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2150
+
<parameter>statement</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_stmt</classname> object
1230
2151
returned by <function>mysqli_stmt_init</function>.</para></listitem></varlistentry>'>
1231
2152
<!ENTITY mysqli.available.mysqlnd 'Available only with <link xmlns="http://docbook.org/ns/docbook"
1232
2153
linkend="book.mysqlnd">mysqlnd</link>.'>
...
...
@@ -1235,11 +2156,35 @@ linkend="book.mysqlnd">mysqlnd</link>.'>
1235
2156
hand-shake/authentication, which mysqlnd will use.</para><para>Libmysqlclient uses the default charset set in the
1236
2157
<filename>my.cnf</filename> or by an explicit call to <function>mysqli_options</function> prior to
1237
2158
calling <function>mysqli_real_connect</function>, but after <function>mysqli_init</function>.</para></note>'>
2159
+
<!ENTITY mysqli.integer.overflow.as.string.note '<note xmlns="http://docbook.org/ns/docbook">
2160
+
<para>If the number of rows is greater than <constant>PHP_INT_MAX</constant>,
2161
+
the number will be returned as a &string;.</para></note>'>
2162
+
<!ENTITY mysqli.sqlinjection.warning '<warning xmlns="http://docbook.org/ns/docbook">
2163
+
<title>Security warning: SQL injection</title><para>If the query contains any variable
2164
+
input then <link linkend="mysqli.quickstart.prepared-statements">parameterized
2165
+
prepared statements</link> should be used instead. Alternatively, the
2166
+
data must be properly formatted and all strings must be escaped using
2167
+
the <function>mysqli_real_escape_string</function>
2168
+
function.</para></warning>'>
2169
+
<!ENTITY mysqli.conditionalexception '<para xmlns="http://docbook.org/ns/docbook">
2170
+
If mysqli error reporting is enabled (<constant>MYSQLI_REPORT_ERROR</constant>) and the requested operation fails,
2171
+
a warning is generated. If, in addition, the mode is set to <constant>MYSQLI_REPORT_STRICT</constant>,
2172
+
a <classname>mysqli_sql_exception</classname> is thrown instead.</para>'>
2173
+
2174
+
<!-- Notes for PCRE -->
2175
+
<!ENTITY pcre.pattern.warning '<para xmlns="http://docbook.org/ns/docbook">
2176
+
If the regex pattern passed does not compile to a valid regex, an <constant>E_WARNING</constant> is emitted.
2177
+
</para>'>
1238
2178
1239
2179
<!-- Notes for SAPI/Apache -->
1240
2180
<!ENTITY apache.req.module '<simpara xmlns="http://docbook.org/ns/docbook">This function is supported when PHP
1241
-
is installed as an Apache module or by the <link linkend="book.nsapi">NSAPI server module</link> in Netscape/iPlanet/SunONE
1242
-
webservers.</simpara>'>
2181
+
is installed as an Apache module webserver.
2182
+
</simpara>'>
2183
+
2184
+
<!-- Notes for SAPI/FPM -->
2185
+
<!ENTITY fpm.intro '<para xmlns="http://docbook.org/ns/docbook">FPM (FastCGI Process Manager) is
2186
+
a primary PHP FastCGI implementation containing some features (mostly) useful for heavy-loaded sites.
2187
+
</para>'>
1243
2188
1244
2189
<!-- SimpleXML Notes -->
1245
2190
<!ENTITY simplexml.iteration '<note xmlns="http://docbook.org/ns/docbook"><simpara>SimpleXML has made a rule of adding
...
...
@@ -1285,85 +2230,80 @@ the PHP &null; value.</simpara></note>'>
1285
2230
1286
2231
<!-- MSQL Notes -->
1287
2232
<!-- The msql.*.description entities are used in the parameters refsect1 -->
1288
-
<!ENTITY msql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1289
-
link_identifier</parameter></term><listitem><para>The mSQL connection.
2233
+
<!ENTITY msql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2234
+
<parameter>link_identifier</parameter></term><listitem><para>The mSQL connection.
1290
2235
If not specified, the last link opened by <function>msql_connect</function>
1291
2236
is assumed. If no such link is found, the function will try to establish a
1292
2237
link as if <function>msql_connect</function> was called, and use it.
1293
2238
</para></listitem></varlistentry>'>
1294
2239
1295
-
<!ENTITY msql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1296
-
result</parameter></term><listitem><para>The result <type>resource</type> that
2240
+
<!ENTITY msql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2241
+
<parameter>result</parameter></term><listitem><para>The result <type>resource</type> that
1297
2242
is being evaluated. This result comes from a call to
1298
2243
<function>msql_query</function>.</para></listitem></varlistentry>'>
1299
2244
1300
-
<!ENTITY msql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1301
-
field_offset</parameter></term><listitem><para>The numerical field offset. The
2245
+
<!ENTITY msql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2246
+
<parameter>field_offset</parameter></term><listitem><para>The numerical field offset. The
1302
2247
<parameter>field_offset</parameter> starts at <literal>1</literal>.</para></listitem></varlistentry>'>
1303
2248
1304
2249
1305
2250
<!-- MySQL Notes -->
1306
2251
<!-- The mysql.*.description entities are used in the parameters refsect1 -->
1307
-
<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1308
-
link_identifier</parameter></term><listitem><para>The MySQL connection. If the
2252
+
<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2253
+
<parameter>link_identifier</parameter></term><listitem><para>The MySQL connection. If the
1309
2254
link identifier is not specified, the last link opened by
1310
2255
<function>mysql_connect</function> is assumed. If no such link is found, it
1311
-
will try to create one as if <function>mysql_connect</function> was called
2256
+
will try to create one as if <function>mysql_connect</function> had been called
1312
2257
with no arguments. If no connection is found or established, an
1313
2258
<constant>E_WARNING</constant> level error is generated.</para></listitem>
1314
2259
</varlistentry>'>
1315
2260
1316
2261
<!ENTITY mysql.linkid-noreopen.description '<varlistentry
1317
-
xmlns="http://docbook.org/ns/docbook"><term><parameter>
1318
-
link_identifier</parameter></term><listitem><para>The MySQL connection. If the
2262
+
xmlns="http://docbook.org/ns/docbook"><term>
2263
+
<parameter>link_identifier</parameter></term><listitem><para>The MySQL connection. If the
1319
2264
link identifier is not specified, the last link opened by
1320
2265
<function>mysql_connect</function> is assumed. If no connection is found or
1321
2266
established, an <constant>E_WARNING</constant> level error is
1322
2267
generated.</para></listitem></varlistentry>'>
1323
2268
1324
-
<!ENTITY mysql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1325
-
result</parameter></term><listitem><para>The result <type>resource</type> that
2269
+
<!ENTITY mysql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2270
+
<parameter>result</parameter></term><listitem><para>The result <type>resource</type> that
1326
2271
is being evaluated. This result comes from a call to
1327
2272
<function>mysql_query</function>.</para></listitem></varlistentry>'>
1328
2273
1329
-
<!ENTITY mysql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1330
-
field_offset</parameter></term><listitem><para>The numerical field offset. The
2274
+
<!ENTITY mysql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2275
+
<parameter>field_offset</parameter></term><listitem><para>The numerical field offset. The
1331
2276
<parameter>field_offset</parameter> starts at <literal>0</literal>. If
1332
2277
<parameter>field_offset</parameter> does not exist, an error of level
1333
2278
<constant>E_WARNING</constant> is also issued.</para></listitem></varlistentry>'>
1334
2279
1335
2280
<!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.
1336
2281
Instead, the <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extension should be used.
1337
-
See also <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and
1338
-
<link linkend="faq.databases.mysql.deprecated">related FAQ</link> for more information.
2282
+
See also <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
1339
2283
Alternatives to this function include:</para>'>
1340
2284
1341
2285
<!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
1342
2286
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
1343
2287
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
1344
-
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its
1345
-
<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information.
2288
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
1346
2289
Alternatives to this function include:</para>'>
1347
2290
1348
2291
<!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
1349
2292
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
1350
2293
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
1351
-
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its
1352
-
<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information.
2294
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
1353
2295
Alternatives to this function include:</para>'>
1354
2296
1355
2297
<!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
1356
2298
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
1357
2299
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
1358
-
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its
1359
-
<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information.
2300
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
1360
2301
Alternatives to this function include:</para>'>
1361
2302
1362
2303
<!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
1363
2304
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
1364
2305
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
1365
-
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its
1366
-
<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information.
2306
+
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
1367
2307
Alternatives to this function include:</para>'>
1368
2308
1369
2309
<!ENTITY mysql.close.connections.result.sets '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1382,8 +2322,8 @@ using the CT library interface to Sybase, and not with the DB library.
1382
2322
<!ENTITY sybase.db.only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when
1383
2323
using the DB library interface to Sybase, and not with the CT library.</simpara></note>'>
1384
2324
1385
-
<!ENTITY sybase.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1386
-
link_identifier</parameter></term><listitem><para>The Sybase connection. If the
2325
+
<!ENTITY sybase.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2326
+
<parameter>link_identifier</parameter></term><listitem><para>The Sybase connection. If the
1387
2327
link identifier is not specified, the last link opened by
1388
2328
<function>sybase_connect</function> is assumed. If no such link is found, it
1389
2329
will try to create one as if <function>sybase_connect</function> was called
...
...
@@ -1397,15 +2337,15 @@ determines the unit length. If it is <literal>0</literal> or omitted, the
1397
2337
default unit as specified for the page is used. In other cases, the coordinates
1398
2338
are measured in postscript points, disregarding the current unit.</para>'>
1399
2339
1400
-
<!ENTITY cpdf.mode.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1401
-
mode</parameter></term><listitem><para>The optional parameter <parameter>mode</parameter>
2340
+
<!ENTITY cpdf.mode.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2341
+
<parameter>mode</parameter></term><listitem><para>The optional parameter <parameter>mode</parameter>
1402
2342
determines the unit length. If it is <literal>0</literal> or omitted, the
1403
2343
default unit as specified for the page is used. In other cases, the coordinates
1404
2344
are measured in postscript points, disregarding the current unit.</para>
1405
2345
</listitem></varlistentry>'>
1406
2346
1407
-
<!ENTITY cpdf.pdf-document.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1408
-
pdf_document</parameter></term><listitem><para>The document handle, returned by
2347
+
<!ENTITY cpdf.pdf-document.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2348
+
<parameter>pdf_document</parameter></term><listitem><para>The document handle, returned by
1409
2349
<function>cpdf_open</function>.</para></listitem></varlistentry>'>
1410
2350
1411
2351
<!-- Xattr entities -->
...
...
@@ -1424,19 +2364,8 @@ brackets—for example, <literal>tcp://[fe80::1]:80</literal>.</simpara></note>'
1424
2364
</simpara></note>'>
1425
2365
1426
2366
<!-- Notes for tidy -->
1427
-
<!ENTITY note.tidy.ze2 '<note xmlns="http://docbook.org/ns/docbook"><simpara> This function is only available with
1428
-
Zend Engine 2 (PHP >= 5.0.0).</simpara></note>'>
1429
-
1430
2367
<!ENTITY tidy.object 'The <classname xmlns="http://docbook.org/ns/docbook">Tidy</classname> object.'>
1431
2368
1432
-
<!ENTITY note.tidy.1only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available in
1433
-
Tidy 1.0. It became obsolete in Tidy 2.0, and thus has been removed.
1434
-
</simpara></note>'>
1435
-
1436
-
<!ENTITY note.tidy.2only '<note xmlns="http://docbook.org/ns/docbook"><simpara>The optional parameters
1437
-
<parameter>config</parameter> and <parameter>encoding</parameter> were
1438
-
added in Tidy 2.0.</simpara></note>'>
1439
-
1440
2369
<!ENTITY tidy.conf-enc '<para xmlns="http://docbook.org/ns/docbook">The <parameter>config</parameter> parameter
1441
2370
can be passed either as an array or as a string. If a string is passed,
1442
2371
it is interpreted as the name of the configuration file, otherwise, it is
...
...
@@ -1469,7 +2398,7 @@ slash may also be necessary for directories.</simpara></note>'>
1469
2398
<!ENTITY Credit.Authors.and.Contributors 'Authors and Contributors'>
1470
2399
1471
2400
<!ENTITY Credit.Introduction '<para xmlns="http://docbook.org/ns/docbook"> We highlight the currently most active
1472
-
people on front page of the manual, but there are many more contributors who
2401
+
people on the front page of the manual, but there are many more contributors who
1473
2402
currently help in our work or have provided a great amount of help to the project
1474
2403
in the past. There are a lot of unnamed people who help out with user
1475
2404
notes on manual pages, which continually get included in the references, the
...
...
@@ -1529,9 +2458,17 @@ using public key authentication, use the
1529
2458
<!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.'>
1530
2459
1531
2460
<!-- XMLWriter Notes -->
1532
-
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1533
-
xmlwriter</parameter></term><listitem><para>Only for procedural calls.
1534
-
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>'>
2461
+
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2462
+
<parameter>writer</parameter></term><listitem><para>Only for procedural calls.
2463
+
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>'>
2464
+
2465
+
<!ENTITY xmlwriter.changelog.writer-param '<row xmlns="http://docbook.org/ns/docbook">
2466
+
<entry>8.0.0</entry>
2467
+
<entry>
2468
+
<parameter>writer</parameter> expects an <classname>XMLWriter</classname>
2469
+
instance now; previously, a <type>resource</type> was expected.
2470
+
</entry>
2471
+
</row>'>
1535
2472
1536
2473
<!-- SOAP notes -->
1537
2474
<!ENTITY soap.wsdl.mode.only "<note xmlns='http://docbook.org/ns/docbook'><para>This function only works in WSDL mode.</para></note>">
...
...
@@ -1555,6 +2492,7 @@ The XMLWriter <type>resource</type> that is being modified. This resource comes
1555
2492
<!ENTITY fann.return.bool '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>
1556
2493
<!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>'>
1557
2494
<!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>'>
2495
+
<!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>'>
1558
2496
1559
2497
<!-- Imagick generic return types -->
1560
2498
<!ENTITY imagick.return.success 'Returns &true; on success.'>
...
...
@@ -1582,8 +2520,12 @@ The XMLWriter <type>resource</type> that is being modified. This resource comes
1582
2520
<!ENTITY imagick.method.available.0x653 'This method is available if Imagick has been compiled against ImageMagick version 6.5.3 or newer.'>
1583
2521
<!ENTITY imagick.method.available.0x657 'This method is available if Imagick has been compiled against ImageMagick version 6.5.7 or newer.'>
1584
2522
2523
+
<!ENTITY imagick.method.not.available.0x700 'This method is not available if Imagick has been compiled against ImageMagick version 7.0.0 or newer.'>
2524
+
1585
2525
<!ENTITY imagick.constant.available 'This constant is available if Imagick has been compiled against ImageMagick version'>
1586
2526
2527
+
<!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>'>
2528
+
1587
2529
<!-- Imagick default channel information -->
1588
2530
<!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>'>
1589
2531
...
...
@@ -1668,11 +2610,32 @@ method has been removed from the phar extension as of version 2.0.0. Alternativ
1668
2610
implementations are available using <function>PharFileInfo::isCompressed</function>,
1669
2611
<function>PharFileInfo::decompress</function>, and <function>PharFileInfo::compress</function>.</para></note>'>
1670
2612
2613
+
<!ENTITY phar.note.performance '<note xmlns="http://docbook.org/ns/docbook">
2614
+
<simpara>
2615
+
<function>Phar::addFile</function>, <function>Phar::addFromString</function> and <function>Phar::offsetSet</function>
2616
+
save a new phar archive each time they are called. If performance is a concern,
2617
+
<function>Phar::buildFromDirectory</function> or <function>Phar::buildFromIterator</function>
2618
+
should be used instead.
2619
+
</simpara>
2620
+
</note>'>
2621
+
2622
+
<!ENTITY phardata.note.performance '<note xmlns="http://docbook.org/ns/docbook">
2623
+
<simpara>
2624
+
<function>PharData::addFile</function>, <function>PharData::addFromString</function> and <function>PharData::offsetSet</function>
2625
+
save a new phar archive each time they are called. If performance is a concern,
2626
+
<function>PharData::buildFromDirectory</function> or <function>PharData::buildFromIterator</function>
2627
+
should be used instead.
2628
+
</simpara>
2629
+
</note>'>
2630
+
1671
2631
<!-- XML -->
1672
-
<!ENTITY libxml.required '<para xmlns="http://docbook.org/ns/docbook">This extension requires the
1673
-
<link linkend="book.libxml">libxml</link> PHP extension. This means that passing in
1674
-
<option role="configure">--enable-libxml</option> is also required, although this is implicitly accomplished
1675
-
because libxml is enabled by default.</para>'>
2632
+
<!ENTITY libxml.required '<para xmlns="http://docbook.org/ns/docbook">
2633
+
This extension requires the <link linkend="book.libxml">libxml</link> PHP extension.
2634
+
This means passing the <option role="configure">--with-libxml</option>,
2635
+
or prior to PHP 7.4 the <option role="configure">--enable-libxml</option>,
2636
+
configuration flag, although this is implicitly accomplished because libxml
2637
+
is enabled by default.
2638
+
</para>'>
1676
2639
1677
2640
<!-- XMLReader -->
1678
2641
<!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>'>
...
...
@@ -1707,6 +2670,34 @@ to be references, then they must be references in the passed argument list.'>
1707
2670
1708
2671
<!ENTITY reflection.export.param.name 'The reflection to export.'>
1709
2672
2673
+
<!ENTITY reflection.getattributes.param.name '<varlistentry xmlns="http://docbook.org/ns/docbook">
2674
+
<term><parameter>name</parameter></term>
2675
+
<listitem>
2676
+
<para>
2677
+
Filter the results to include only <classname>ReflectionAttribute</classname>
2678
+
instances for attributes matching this class name.
2679
+
</para>
2680
+
</listitem>
2681
+
</varlistentry>'>
2682
+
2683
+
<!ENTITY reflection.getattributes.param.flags '<varlistentry xmlns="http://docbook.org/ns/docbook">
2684
+
<term><parameter>flags</parameter></term>
2685
+
<listitem>
2686
+
<para>
2687
+
Flags for determining how to filter the results, if <parameter>name</parameter>
2688
+
is provided.
2689
+
</para>
2690
+
<para>
2691
+
Default is <literal>0</literal> which will only return results for attributes that
2692
+
are of the class <parameter>name</parameter>.
2693
+
</para>
2694
+
<para>
2695
+
The only other option available, is to use <constant>ReflectionAttribute::IS_INSTANCEOF</constant>,
2696
+
which will instead use <literal>instanceof</literal> for filtering.
2697
+
</para>
2698
+
</listitem>
2699
+
</varlistentry>'>
2700
+
1710
2701
<!-- SPL -->
1711
2702
<!ENTITY spl.datastructures.intro.title '<title xmlns="http://docbook.org/ns/docbook">Datastructures</title>'>
1712
2703
...
...
@@ -1726,10 +2717,13 @@ to be references, then they must be references in the passed argument list.'>
1726
2717
<!ENTITY spl.misc.intro.title '<title xmlns="http://docbook.org/ns/docbook">Miscellaneous Classes and Interfaces</title>'>
1727
2718
<!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>'>
1728
2719
2720
+
<!-- ZIP -->
2721
+
<!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>'>
2722
+
1729
2723
<!-- Win32Service -->
1730
2724
<!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.'>
1731
2725
<!ENTITY win32service.success.false.error 'Returns &true; on success&win32service.false.error;'>
1732
-
<!ENTITY win32service.noerror.false.error 'Returns <constant xmlns="http://docbook.org/ns/docbook">WIN32_NO_ERROR</constant> on success&win32service.false.error;'>
2726
+
<!ENTITY win32service.noerror.false.error 'returned <constant xmlns="http://docbook.org/ns/docbook">WIN32_NO_ERROR</constant> on success&win32service.false.error;'>
1733
2727
1734
2728
<!-- SNMP -->
1735
2729
<!ENTITY snmp.set.type.values '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1898,7 +2892,7 @@ paths</simpara></warning>
1898
2892
<!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>'>
1899
2893
<!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>'>
1900
2894
<!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>'>
1901
-
<!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>'>
2895
+
<!ENTITY mongo.listcollections.note '<note xmlns="http://docbook.org/ns/docbook"><simpara>This method will use the <link xlink:href="&url.mongodb.docs.command;listCollections" xmlns:xlink="http://www.w3.org/1999/xlink">listCollections</link> database command when communicating with MongoDB 2.8+. For previous database versions, the method will query the special <literal>system.namespaces</literal> collection.</simpara></note>'>
1902
2896
<!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>'>
1903
2897
<!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>'>
1904
2898
<!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>'>
...
...
@@ -1946,6 +2940,373 @@ the <link linkend="set.mongodb">MongoDB</link> extension should be
1946
2940
used.</para>'>
1947
2941
1948
2942
<!-- mongodb -->
2943
+
<!ENTITY mongodb.changelog.tentative-return-types '
2944
+
<row xmlns="http://docbook.org/ns/docbook">
2945
+
<entry>PECL mongodb 1.15.0</entry>
2946
+
<entry>
2947
+
Return types for methods are declared as tentative on PHP 8.0 and newer,
2948
+
triggering deprecation notices in code that implements this interface
2949
+
without declaring the appropriate return types. The <code>#[ReturnTypeWillChange]</code>
2950
+
attribute can be added to silence the deprecation notice.
2951
+
</entry>
2952
+
</row>
2953
+
'>
2954
+
2955
+
<!ENTITY mongodb.option.collation '
2956
+
<row xmlns="http://docbook.org/ns/docbook">
2957
+
<entry>collation</entry>
2958
+
<entry><type class="union"><type>array</type><type>object</type></type></entry>
2959
+
<entry>
2960
+
<para>
2961
+
<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>.
2962
+
</para>
2963
+
<para>
2964
+
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.
2965
+
</para>
2966
+
<para>
2967
+
This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
2968
+
</para>
2969
+
</entry>
2970
+
</row>
2971
+
'>
2972
+
<!ENTITY mongodb.option.let '
2973
+
<row xmlns="http://docbook.org/ns/docbook">
2974
+
<entry>let</entry>
2975
+
<entry><type class="union"><type>array</type><type>object</type></type></entry>
2976
+
<entry>
2977
+
<para>
2978
+
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>).
2979
+
</para>
2980
+
<para>
2981
+
This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.
2982
+
</para>
2983
+
</entry>
2984
+
</row>
2985
+
'>
2986
+
<!ENTITY mongodb.option.encryption.keyVaultClient '
2987
+
<row xmlns="http://docbook.org/ns/docbook">
2988
+
<entry>keyVaultClient</entry>
2989
+
<entry><classname>MongoDB\Driver\Manager</classname></entry>
2990
+
<entry>The Manager used to route data key queries to a separate MongoDB cluster. By default, the current Manager and cluster is used.</entry>
2991
+
</row>
2992
+
'>
2993
+
<!ENTITY mongodb.option.encryption.keyVaultNamespace '
2994
+
<row xmlns="http://docbook.org/ns/docbook">
2995
+
<entry>keyVaultNamespace</entry>
2996
+
<entry><type>string</type></entry>
2997
+
<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>
2998
+
</row>
2999
+
'>
3000
+
<!ENTITY mongodb.option.encryption.kmsProviders '
3001
+
<row xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3002
+
<entry>kmsProviders</entry>
3003
+
<entry><type>array</type></entry>
3004
+
<entry>
3005
+
<para>
3006
+
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.
3007
+
</para>
3008
+
<para>
3009
+
If an empty document is specified for <literal>"aws"</literal>,
3010
+
<literal>"azure"</literal>, or <literal>"gcp"</literal>, the driver
3011
+
will attempt to configure the provider using
3012
+
<link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#automatic-credentials">Automatic Credentials</link>.
3013
+
</para>
3014
+
<para>
3015
+
The format for <literal>"aws"</literal> is as follows:
3016
+
</para>
3017
+
<programlisting role="javascript">
3018
+
<![CDATA[
3019
+
aws: {
3020
+
accessKeyId: <string>,
3021
+
secretAccessKey: <string>,
3022
+
sessionToken: <optional string>
3023
+
}
3024
+
]]>
3025
+
</programlisting>
3026
+
<para>
3027
+
The format for <literal>"azure"</literal> is as follows:
3028
+
</para>
3029
+
<programlisting role="javascript">
3030
+
<![CDATA[
3031
+
azure: {
3032
+
tenantId: <string>,
3033
+
clientId: <string>,
3034
+
clientSecret: <string>,
3035
+
identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
3036
+
}
3037
+
]]>
3038
+
</programlisting>
3039
+
<para>
3040
+
The format for <literal>"gcp"</literal> is as follows:
3041
+
</para>
3042
+
<programlisting role="javascript">
3043
+
<![CDATA[
3044
+
gcp: {
3045
+
email: <string>,
3046
+
privateKey: <base64 string>|<MongoDB\BSON\Binary>,
3047
+
endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
3048
+
}
3049
+
]]>
3050
+
</programlisting>
3051
+
<para>
3052
+
The format for <literal>"kmip"</literal> is as follows:
3053
+
</para>
3054
+
<programlisting role="javascript">
3055
+
<![CDATA[
3056
+
kmip: {
3057
+
endpoint: <string>
3058
+
}
3059
+
]]>
3060
+
</programlisting>
3061
+
<para>
3062
+
The format for <literal>"local"</literal> is as follows:
3063
+
</para>
3064
+
<programlisting role="javascript">
3065
+
<![CDATA[
3066
+
local: {
3067
+
// 96-byte master key used to encrypt/decrypt data keys
3068
+
key: <base64 string>|<MongoDB\BSON\Binary>
3069
+
}
3070
+
]]>
3071
+
</programlisting>
3072
+
</entry>
3073
+
</row>
3074
+
'>
3075
+
<!ENTITY mongodb.option.encryption.masterKey-options-by-provider '
3076
+
<para xmlns="http://docbook.org/ns/docbook">
3077
+
<table>
3078
+
<title><literal>"aws"</literal> provider options</title>
3079
+
<tgroup cols="3">
3080
+
<thead>
3081
+
<row>
3082
+
<entry>Option</entry>
3083
+
<entry>Type</entry>
3084
+
<entry>Description</entry>
3085
+
</row>
3086
+
</thead>
3087
+
<tbody>
3088
+
<row>
3089
+
<entry>region</entry>
3090
+
<entry>string</entry>
3091
+
<entry>Required.</entry>
3092
+
</row>
3093
+
<row>
3094
+
<entry>key</entry>
3095
+
<entry>string</entry>
3096
+
<entry>Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).</entry>
3097
+
</row>
3098
+
<row>
3099
+
<entry>endpoint</entry>
3100
+
<entry>string</entry>
3101
+
<entry>Optional. An alternate host identifier to send KMS requests to. May include port number.</entry>
3102
+
</row>
3103
+
</tbody>
3104
+
</tgroup>
3105
+
</table>
3106
+
</para>
3107
+
<para xmlns="http://docbook.org/ns/docbook">
3108
+
<table>
3109
+
<title><literal>"azure"</literal> provider options</title>
3110
+
<tgroup cols="3">
3111
+
<thead>
3112
+
<row>
3113
+
<entry>Option</entry>
3114
+
<entry>Type</entry>
3115
+
<entry>Description</entry>
3116
+
</row>
3117
+
</thead>
3118
+
<tbody>
3119
+
<row>
3120
+
<entry>keyVaultEndpoint</entry>
3121
+
<entry>string</entry>
3122
+
<entry>Required. Host with optional port (e.g. "example.vault.azure.net").</entry>
3123
+
</row>
3124
+
<row>
3125
+
<entry>keyName</entry>
3126
+
<entry>string</entry>
3127
+
<entry>Required.</entry>
3128
+
</row>
3129
+
<row>
3130
+
<entry>keyVersion</entry>
3131
+
<entry>string</entry>
3132
+
<entry>Optional. A specific version of the named key. Defaults to using the key's primary version.</entry>
3133
+
</row>
3134
+
</tbody>
3135
+
</tgroup>
3136
+
</table>
3137
+
</para>
3138
+
<para xmlns="http://docbook.org/ns/docbook">
3139
+
<table>
3140
+
<title><literal>"gcp"</literal> provider options</title>
3141
+
<tgroup cols="3">
3142
+
<thead>
3143
+
<row>
3144
+
<entry>Option</entry>
3145
+
<entry>Type</entry>
3146
+
<entry>Description</entry>
3147
+
</row>
3148
+
</thead>
3149
+
<tbody>
3150
+
<row>
3151
+
<entry>projectId</entry>
3152
+
<entry>string</entry>
3153
+
<entry>Required.</entry>
3154
+
</row>
3155
+
<row>
3156
+
<entry>location</entry>
3157
+
<entry>string</entry>
3158
+
<entry>Required.</entry>
3159
+
</row>
3160
+
<row>
3161
+
<entry>keyRing</entry>
3162
+
<entry>string</entry>
3163
+
<entry>Required.</entry>
3164
+
</row>
3165
+
<row>
3166
+
<entry>keyName</entry>
3167
+
<entry>string</entry>
3168
+
<entry>Required.</entry>
3169
+
</row>
3170
+
<row>
3171
+
<entry>keyVersion</entry>
3172
+
<entry>string</entry>
3173
+
<entry>Optional. A specific version of the named key. Defaults to using the key's primary version.</entry>
3174
+
</row>
3175
+
<row>
3176
+
<entry>endpoint</entry>
3177
+
<entry>string</entry>
3178
+
<entry>Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".</entry>
3179
+
</row>
3180
+
</tbody>
3181
+
</tgroup>
3182
+
</table>
3183
+
</para>
3184
+
<para xmlns="http://docbook.org/ns/docbook">
3185
+
<table>
3186
+
<title><literal>"kmip"</literal> provider options</title>
3187
+
<tgroup cols="3">
3188
+
<thead>
3189
+
<row>
3190
+
<entry>Option</entry>
3191
+
<entry>Type</entry>
3192
+
<entry>Description</entry>
3193
+
</row>
3194
+
</thead>
3195
+
<tbody>
3196
+
<row>
3197
+
<entry>keyId</entry>
3198
+
<entry>string</entry>
3199
+
<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>
3200
+
</row>
3201
+
<row>
3202
+
<entry>endpoint</entry>
3203
+
<entry>string</entry>
3204
+
<entry>Optional. Host with optional port.</entry>
3205
+
</row>
3206
+
</tbody>
3207
+
</tgroup>
3208
+
</table>
3209
+
</para>
3210
+
'>
3211
+
<!ENTITY mongodb.option.encryption.tlsOptions '
3212
+
<row xmlns="http://docbook.org/ns/docbook">
3213
+
<entry>tlsOptions</entry>
3214
+
<entry><type>array</type></entry>
3215
+
<entry>
3216
+
<para>
3217
+
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:
3218
+
</para>
3219
+
<programlisting role="javascript">
3220
+
<![CDATA[
3221
+
<provider>: {
3222
+
tlsCaFile: <optional string>,
3223
+
tlsCertificateKeyFile: <optional string>,
3224
+
tlsCertificateKeyFilePassword: <optional string>,
3225
+
tlsDisableOCSPEndpointCheck: <optional bool>
3226
+
}
3227
+
]]>
3228
+
</programlisting>
3229
+
</entry>
3230
+
</row>
3231
+
'>
3232
+
<!ENTITY mongodb.option.maxCommitTimeMS '
3233
+
<row xmlns="http://docbook.org/ns/docbook">
3234
+
<entry>maxCommitTimeMS</entry>
3235
+
<entry>integer</entry>
3236
+
<entry>
3237
+
<para>
3238
+
The maximum amount of time in milliseconds to allow a single
3239
+
<literal>commitTransaction</literal> command to run.
3240
+
</para>
3241
+
<para>
3242
+
If specified, <literal>maxCommitTimeMS</literal> must be a signed
3243
+
32-bit integer greater than or equal to zero.
3244
+
</para>
3245
+
</entry>
3246
+
</row>
3247
+
'>
3248
+
<!ENTITY mongodb.option.readConcern '
3249
+
<row xmlns="http://docbook.org/ns/docbook">
3250
+
<entry>readConcern</entry>
3251
+
<entry><classname>MongoDB\Driver\ReadConcern</classname></entry>
3252
+
<entry>
3253
+
<para>
3254
+
A read concern to apply to the operation.
3255
+
</para>
3256
+
<para>
3257
+
This option is available in MongoDB 3.2+ and will result in an
3258
+
exception at execution time if specified for an older server
3259
+
version.
3260
+
</para>
3261
+
</entry>
3262
+
</row>
3263
+
'>
3264
+
<!ENTITY mongodb.option.readPreference '
3265
+
<row xmlns="http://docbook.org/ns/docbook">
3266
+
<entry>readPreference</entry>
3267
+
<entry><classname>MongoDB\Driver\ReadPreference</classname></entry>
3268
+
<entry>
3269
+
<para>
3270
+
A read preference to use for selecting a server for the operation.
3271
+
</para>
3272
+
</entry>
3273
+
</row>
3274
+
'>
3275
+
<!ENTITY mongodb.option.session '
3276
+
<row xmlns="http://docbook.org/ns/docbook">
3277
+
<entry>session</entry>
3278
+
<entry><classname>MongoDB\Driver\Session</classname></entry>
3279
+
<entry>
3280
+
<para>
3281
+
A session to associate with the operation.
3282
+
</para>
3283
+
</entry>
3284
+
</row>
3285
+
'>
3286
+
<!ENTITY mongodb.option.transactionReadWriteConcern '
3287
+
<warning xmlns="http://docbook.org/ns/docbook">
3288
+
<para>
3289
+
If you are using a <literal>"session"</literal> which has a transaction
3290
+
in progress, you cannot specify a <literal>"readConcern"</literal> or
3291
+
<literal>"writeConcern"</literal> option. This will result in an
3292
+
<classname>MongoDB\Driver\Exception\InvalidArgumentException</classname>
3293
+
being thrown. Instead, you should set these two options when you create
3294
+
the transaction with
3295
+
<methodname>MongoDB\Driver\Session::startTransaction</methodname>.
3296
+
</para>
3297
+
</warning>
3298
+
'>
3299
+
<!ENTITY mongodb.option.writeConcern '
3300
+
<row xmlns="http://docbook.org/ns/docbook">
3301
+
<entry>writeConcern</entry>
3302
+
<entry><classname>MongoDB\Driver\WriteConcern</classname></entry>
3303
+
<entry>
3304
+
<para>
3305
+
A write concern to apply to the operation.
3306
+
</para>
3307
+
</entry>
3308
+
</row>
3309
+
'>
1949
3310
<!ENTITY mongodb.parameter.namespace '
1950
3311
<varlistentry xmlns="http://docbook.org/ns/docbook">
1951
3312
<term><parameter>namespace</parameter> (<type>string</type>)</term>
...
...
@@ -1968,40 +3329,180 @@ used.</para>'>
1968
3329
'>
1969
3330
<!ENTITY mongodb.parameter.bulkwrite '
1970
3331
<varlistentry xmlns="http://docbook.org/ns/docbook">
1971
-
<term><parameter>bulk</parameter> (<type>MongoDB\Driver\BulkWrite</type>)</term>
3332
+
<term><parameter>bulk</parameter> (<classname>MongoDB\Driver\BulkWrite</classname>)</term>
1972
3333
<listitem>
1973
3334
<para>
1974
-
The <classname>MongoDB\Driver\BulkWrite</classname> to execute.
3335
+
The write(s) to execute.
1975
3336
</para>
1976
3337
</listitem>
1977
3338
</varlistentry>
1978
3339
'>
1979
3340
<!ENTITY mongodb.parameter.command '
1980
3341
<varlistentry xmlns="http://docbook.org/ns/docbook">
1981
-
<term><parameter>command</parameter> (<type>MongoDB\Driver\Command</type>)</term>
3342
+
<term><parameter>command</parameter> (<classname>MongoDB\Driver\Command</classname>)</term>
1982
3343
<listitem>
1983
3344
<para>
1984
-
The <classname>MongoDB\Driver\Command</classname> to execute.
3345
+
The command to execute.
1985
3346
</para>
1986
3347
</listitem>
1987
3348
</varlistentry>
1988
3349
'>
1989
-
<!ENTITY mongodb.parameter.query '
3350
+
<!ENTITY mongodb.parameter.encryptOpts '
1990
3351
<varlistentry xmlns="http://docbook.org/ns/docbook">
1991
-
<term><parameter>query</parameter> (<type>MongoDB\Driver\Query</type>)</term>
3352
+
<term><parameter>options</parameter></term>
1992
3353
<listitem>
1993
3354
<para>
1994
-
The <classname>MongoDB\Driver\Query</classname> to execute.
3355
+
<table>
3356
+
<title>Encryption options</title>
3357
+
<tgroup cols="3">
3358
+
<thead>
3359
+
<row>
3360
+
<entry>Option</entry>
3361
+
<entry>Type</entry>
3362
+
<entry>Description</entry>
3363
+
</row>
3364
+
</thead>
3365
+
<tbody>
3366
+
<row>
3367
+
<entry>algorithm</entry>
3368
+
<entry><type>string</type></entry>
3369
+
<entry>
3370
+
<para>
3371
+
The encryption algorithm to be used. This option is required.
3372
+
Specify one of the following
3373
+
<link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
3374
+
</para>
3375
+
<simplelist>
3376
+
<member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC</constant></member>
3377
+
<member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM</constant></member>
3378
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant></member>
3379
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED</constant></member>
3380
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW</constant></member>
3381
+
</simplelist>
3382
+
</entry>
3383
+
</row>
3384
+
<row>
3385
+
<entry>contentionFactor</entry>
3386
+
<entry><type>int</type></entry>
3387
+
<entry>
3388
+
<para>
3389
+
The contention factor for evaluating queries with indexed, encrypted
3390
+
payloads.
3391
+
</para>
3392
+
<para>
3393
+
This option only applies and may only be specified when
3394
+
<literal>algorithm</literal> is
3395
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
3396
+
or
3397
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW</constant>.
3398
+
</para>
3399
+
</entry>
3400
+
</row>
3401
+
<row>
3402
+
<entry>keyAltName</entry>
3403
+
<entry><type>string</type></entry>
3404
+
<entry>
3405
+
<para>
3406
+
Identifies a key vault collection document by
3407
+
<literal>keyAltName</literal>. This option is mutually exclusive
3408
+
with <literal>keyId</literal> and exactly one is required.
3409
+
</para>
3410
+
</entry>
3411
+
</row>
3412
+
<row>
3413
+
<entry>keyId</entry>
3414
+
<entry><classname>MongoDB\BSON\Binary</classname></entry>
3415
+
<entry>
3416
+
<para>
3417
+
Identifies a data key by <literal>_id</literal>. The value is a UUID
3418
+
(binary subtype 4). This option is mutually exclusive with
3419
+
<literal>keyAltName</literal> and exactly one is required.
3420
+
</para>
3421
+
</entry>
3422
+
</row>
3423
+
<row>
3424
+
<entry>queryType</entry>
3425
+
<entry><type>string</type></entry>
3426
+
<entry>
3427
+
<para>
3428
+
The query type for evaluating queries with indexed, encrypted
3429
+
payloads. Specify one of the following
3430
+
<link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
3431
+
</para>
3432
+
<simplelist>
3433
+
<member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY</constant></member>
3434
+
<member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW</constant></member>
3435
+
</simplelist>
3436
+
<para>This option only applies and may only be specified when
3437
+
<literal>algorithm</literal> is
3438
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
3439
+
or <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW</constant>.
3440
+
</para>
3441
+
</entry>
3442
+
</row>
3443
+
<row>
3444
+
<entry>rangeOpts</entry>
3445
+
<entry><type>array</type></entry>
3446
+
<entry>
3447
+
<para>
3448
+
Index options for a queryable encryption field supporting
3449
+
"rangePreview" queries. The options below must match the values set
3450
+
in the <literal>encryptedFields</literal> of the target collection.
3451
+
For double and decimal128 BSON field types, <literal>min</literal>,
3452
+
<literal>max</literal>, and <literal>precision</literal> must all be
3453
+
set, or all be unset.
3454
+
</para>
3455
+
<para>
3456
+
<table>
3457
+
<title>Range index options</title>
3458
+
<tgroup cols="3">
3459
+
<thead>
3460
+
<row>
3461
+
<entry>Option</entry>
3462
+
<entry>Type</entry>
3463
+
<entry>Description</entry>
3464
+
</row>
3465
+
</thead>
3466
+
<tbody>
3467
+
<row>
3468
+
<entry>min</entry>
3469
+
<entry><type>mixed</type></entry>
3470
+
<entry>Required if <literal>precision</literal> is set.</entry>
3471
+
</row>
3472
+
<row>
3473
+
<entry>max</entry>
3474
+
<entry><type>mixed</type></entry>
3475
+
<entry>Required if <literal>precision</literal> is set.</entry>
3476
+
</row>
3477
+
<row>
3478
+
<entry>sparsity</entry>
3479
+
<entry><type>int</type></entry>
3480
+
<entry>Required.</entry>
3481
+
</row>
3482
+
<row>
3483
+
<entry>precision</entry>
3484
+
<entry><type>int</type></entry>
3485
+
<entry>Optional. May only be set for double or decimal128 BSON field types.</entry>
3486
+
</row>
3487
+
</tbody>
3488
+
</tgroup>
3489
+
</table>
3490
+
</para>
3491
+
</entry>
3492
+
</row>
3493
+
</tbody>
3494
+
</tgroup>
3495
+
</table>
1995
3496
</para>
1996
3497
</listitem>
1997
3498
</varlistentry>
1998
3499
'>
1999
-
<!ENTITY mongodb.parameter.readPreference '
3500
+
<!ENTITY mongodb.parameter.query '
2000
3501
<varlistentry xmlns="http://docbook.org/ns/docbook">
2001
-
<term><parameter>readPreference</parameter> (<type>MongoDB\Driver\ReadPreference</type>)</term>
3502
+
<term><parameter>query</parameter> (<classname>MongoDB\Driver\Query</classname>)</term>
2002
3503
<listitem>
2003
3504
<para>
2004
-
Optionally, a <classname>MongoDB\Driver\ReadPreference</classname> to select the server for this operation. If none is given, the read preference from the <link linkend="mongodb-driver-manager.construct-uri">MongoDB Connection URI</link> will be used.
3505
+
The query to execute.
2005
3506
</para>
2006
3507
</listitem>
2007
3508
</varlistentry>
...
...
@@ -2016,54 +3517,115 @@ used.</para>'>
2016
3517
</listitem>
2017
3518
</varlistentry>
2018
3519
'>
2019
-
<!ENTITY mongodb.parameter.writeConcern '
2020
-
<varlistentry xmlns="http://docbook.org/ns/docbook">
2021
-
<term><parameter>writeConcern</parameter> (<type>MongoDB\Driver\WriteConcern</type>)</term>
2022
-
<listitem>
2023
-
<para>
2024
-
Optionally, a <classname>MongoDB\Driver\WriteConcern</classname> to apply to the write operation. If none is given, the write concern from the <link linkend="mongodb-driver-manager.construct-uri">MongoDB Connection URI</link> will be used.
2025
-
</para>
2026
-
</listitem>
2027
-
</varlistentry>
2028
-
'>
2029
3520
<!ENTITY mongodb.parameter.filter '
2030
3521
<varlistentry xmlns="http://docbook.org/ns/docbook">
2031
-
<term><parameter>filter</parameter> (<type>array|object</type>)</term>
3522
+
<term><parameter>filter</parameter> (<type class="union"><type>array</type><type>object</type></type>)</term>
2032
3523
<listitem>
2033
3524
<para>
2034
-
The search filter.
3525
+
The <link xlink:href="&url.mongodb.docs;tutorial/query-documents/" xmlns:xlink="http://www.w3.org/1999/xlink">query predicate</link>.
3526
+
An empty predicate will match all documents in the collection.
2035
3527
</para>
3528
+
<note>
3529
+
<simpara>
3530
+
When evaluating query criteria, MongoDB compares types and values according to its own <link xlink:href="&url.mongodb.docs;reference/bson-type-comparison-order/" xmlns:xlink="http://www.w3.org/1999/xlink">comparison rules for BSON types</link>, which differs from PHP's <link linkend="types.comparisons">comparison</link> and <link linkend="language.types.type-juggling">type juggling</link> rules. When matching a special BSON type the query criteria should use the respective <link linkend="book.bson">BSON class</link> (e.g. use <classname>MongoDB\BSON\ObjectId</classname> to match an <link xlink:href="&url.mongodb.docs.objectid;" xmlns:xlink="http://www.w3.org/1999/xlink">ObjectId</link>).
3531
+
</simpara>
3532
+
</note>
2036
3533
</listitem>
2037
3534
</varlistentry>
2038
3535
'>
2039
3536
<!ENTITY mongodb.returns.cursor '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\Cursor</classname> on success.</para>'>
2040
3537
<!ENTITY mongodb.returns.writeresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\WriteResult</classname> on success.</para>'>
2041
3538
<!ENTITY mongodb.throws.std '&mongodb.throws.argumentparsing;&mongodb.throws.connection;&mongodb.throws.authentication;'>
3539
+
<!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>'>
3540
+
<!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>'>
2042
3541
<!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>'>
2043
3542
<!ENTITY mongodb.throws.argumentparsing '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> on argument parsing errors.</member>'>
2044
3543
<!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>'>
2045
3544
<!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>'>
2046
-
<!ENTITY mongodb.note.getwriteerrors '
3545
+
<!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>'>
3546
+
3547
+
<!-- Not used in EN anymore -->
3548
+
<!ENTITY mongodb.note.queryable-encryption-preview ''>
3549
+
3550
+
<!ENTITY mongodb.note.decimal128 '
3551
+
<note xmlns="http://docbook.org/ns/docbook">
3552
+
<simpara>
3553
+
<classname>MongoDB\BSON\Decimal128</classname> is only compatible with
3554
+
MongoDB 3.4+. Attempting to use the BSON type with an earlier version of
3555
+
MongoDB will result in an error.
3556
+
</simpara>
3557
+
</note>
3558
+
'>
3559
+
<!ENTITY mongodb.note.extended-json '
3560
+
<note xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3561
+
<simpara>
3562
+
The output is consistent with the <function>MongoDB\BSON\toJSON</function>
3563
+
function, which uses the driver-specific legacy extended JSON format. This
3564
+
does not necessarily match the
3565
+
<link xlink:href="&url.mongodb.specs.extendedjson;#relaxed-extended-json-example">relaxed</link>
3566
+
or <link xlink:href="&url.mongodb.specs.extendedjson;#canonical-extended-json-example">canonical</link>
3567
+
extended JSON representations used by
3568
+
<function>MongoDB\BSON\toRelaxedExtendedJSON</function> and
3569
+
<function>MongoDB\BSON\toCanonicalExtendedJSON</function>, respectively.
3570
+
</simpara>
3571
+
</note>
3572
+
'>
3573
+
<!ENTITY mongodb.note.forking '
3574
+
<note xmlns="http://docbook.org/ns/docbook">
3575
+
<simpara>
3576
+
On Unix platforms, the MongoDB driver is sensitive to scripts that use the
3577
+
fork() system call without also calling exec(). Users are advised not to
3578
+
re-use <classname>MongoDB\Driver\Manager</classname> instances in a forked
3579
+
child process.
3580
+
</simpara>
3581
+
</note>
3582
+
'>
3583
+
3584
+
<!ENTITY mongodb.note.uint32 '
2047
3585
<note xmlns="http://docbook.org/ns/docbook">
2048
-
<para>
2049
-
On write failure,
2050
-
<methodname>MongoDB\Driver\WriteResult::getWriteErrors</methodname> will
2051
-
only ever have one <classname>MongoDB\Driver\WriteError</classname> in the
2052
-
array, and <methodname>MongoDB\Driver\WriteError::getIndex</methodname>
2053
-
will always be 0 (the index of this operation in the batch).
2054
-
</para>
3586
+
<simpara>
3587
+
Because PHP's integer type is signed, some values returned by this
3588
+
method may appear as negative integers on 32-bit platforms. The
3589
+
<literal>"%u"</literal> formatter of <function>sprintf</function> may be
3590
+
used to obtain a string representation of the unsigned decimal value.
3591
+
</simpara>
2055
3592
</note>
2056
3593
'>
2057
-
<!ENTITY mongodb.note.getupsertedids '
3594
+
3595
+
<!ENTITY mongodb.note.server.readpreference '
2058
3596
<note xmlns="http://docbook.org/ns/docbook">
2059
-
<para>
2060
-
<methodname>MongoDB\Driver\WriteResult::getUpsertedIds</methodname> will
2061
-
only ever have one <classname>BSON\ObjectID</classname> in the
2062
-
array, and the index always be 0 (the index of this operation in the batch).
2063
-
</para>
3597
+
<simpara>
3598
+
The <literal>"readPreference"</literal> option does not control the server
3599
+
to which the driver issues the operation; it will always be executed on
3600
+
this server object. Instead, it may be used when issuing the operation to a
3601
+
secondary (from a replica set connection, not standalone) or mongos node to
3602
+
ensure that the driver sets the wire protocol accordingly or adds the read
3603
+
preference to the operation, respectively.
3604
+
</simpara>
3605
+
</note>
3606
+
'>
3607
+
3608
+
<!ENTITY mongodb.note.server.write '
3609
+
<note xmlns="http://docbook.org/ns/docbook">
3610
+
<simpara>
3611
+
It is the caller's responsibility to ensure that the server is capable
3612
+
of executing the write operation. For example, executing a write operation
3613
+
on a secondary (excluding its "local" database) will fail.
3614
+
</simpara>
2064
3615
</note>
2065
3616
'>
2066
3617
3618
+
<!ENTITY mongodb.warning.duplicate-keys '
3619
+
<warning xmlns="http://docbook.org/ns/docbook">
3620
+
<simpara>
3621
+
BSON documents can technically contain duplicate keys because documents are
3622
+
stored as a list of key-value pairs; however, applications should refrain
3623
+
from generating documents with duplicate keys as server and driver behavior
3624
+
may be undefined. Since PHP objects and arrays cannot have duplicate keys,
3625
+
data could also be lost when decoding a BSON document with duplicate keys.
3626
+
</simpara>
3627
+
</warning>
3628
+
'>
2067
3629
2068
3630
<!-- Radius -->
2069
3631
<!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>'>
...
...
@@ -2075,17 +3637,14 @@ used.</para>'>
2075
3637
2076
3638
<!-- posix snippets -->
2077
3639
<!ENTITY posix.parameter.fd '<varlistentry xmlns="http://docbook.org/ns/docbook">
2078
-
<term><parameter>fd</parameter></term>
3640
+
<term><parameter>file_descriptor</parameter></term>
2079
3641
<listitem>
2080
3642
<para>
2081
3643
The file descriptor, which is expected to be either a file
2082
-
<type>resource</type> or an <type>integer</type>. An <type>integer</type>
3644
+
<type>resource</type> or an <type>int</type>. An <type>int</type>
2083
3645
will be assumed to be a file descriptor that can be passed directly to
2084
3646
the underlying system call.
2085
3647
</para>
2086
-
<para>
2087
-
In almost all cases, you will want to provide a file <type>resource</type>.
2088
-
</para>
2089
3648
</listitem>
2090
3649
</varlistentry>'>
2091
3650
...
...
@@ -2106,22 +3665,407 @@ used.</para>'>
2106
3665
</para>
2107
3666
2108
3667
<para xmlns="http://docbook.org/ns/docbook">
2109
-
If omitted, the default value of the <parameter>encoding</parameter> varies
2110
-
depending on the PHP version in use. In PHP 5.6 and later, the
3668
+
If omitted, <parameter>encoding</parameter> defaults to the value of the
2111
3669
<link linkend="ini.default-charset">default_charset</link> configuration
2112
-
option is used as the default value. PHP 5.4 and 5.5 will use
2113
-
<literal>UTF-8</literal> as the default. Earlier versions of PHP use
2114
-
<literal>ISO-8859-1</literal>.
3670
+
option.
2115
3671
</para>
2116
3672
2117
3673
<para xmlns="http://docbook.org/ns/docbook">
2118
3674
Although this argument is technically optional, you are highly encouraged to
2119
-
specify the correct value for your code if you are using PHP 5.5 or earlier,
2120
-
or if your <link linkend="ini.default-charset">default_charset</link>
3675
+
specify the correct value for your code
3676
+
if the <link linkend="ini.default-charset">default_charset</link>
2121
3677
configuration option may be set incorrectly for the given input.
2122
3678
</para>
2123
3679
'>
2124
3680
3681
+
<!ENTITY strings.parameter.format '
3682
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3683
+
<term><parameter>format</parameter></term>
3684
+
<listitem>
3685
+
<para>
3686
+
The format string is composed of zero or more directives:
3687
+
ordinary characters (excluding <literal>%</literal>) that are
3688
+
copied directly to the result and <emphasis>conversion
3689
+
specifications</emphasis>, each of which results in fetching its
3690
+
own parameter.
3691
+
</para>
3692
+
3693
+
<para>
3694
+
A conversion specification follows this prototype:
3695
+
<literal>%[argnum$][flags][width][.precision]specifier</literal>.
3696
+
</para>
3697
+
3698
+
<formalpara>
3699
+
<title>Argnum</title>
3700
+
<para>
3701
+
An integer followed by a dollar sign <literal>$</literal>,
3702
+
to specify which number argument to treat in the conversion.
3703
+
</para>
3704
+
</formalpara>
3705
+
3706
+
<para>
3707
+
<table>
3708
+
<title>Flags</title>
3709
+
<tgroup cols="2">
3710
+
<thead>
3711
+
<row>
3712
+
<entry>Flag</entry>
3713
+
<entry>&Description;</entry>
3714
+
</row>
3715
+
</thead>
3716
+
<tbody>
3717
+
<row>
3718
+
<entry><literal>-</literal></entry>
3719
+
<entry>
3720
+
Left-justify within the given field width;
3721
+
Right justification is the default
3722
+
</entry>
3723
+
</row>
3724
+
<row>
3725
+
<entry><literal>+</literal></entry>
3726
+
<entry>
3727
+
Prefix positive numbers with a plus sign
3728
+
<literal>+</literal>; Default only negative
3729
+
are prefixed with a negative sign.
3730
+
</entry>
3731
+
</row>
3732
+
<row>
3733
+
<entry><literal> </literal>(space)</entry>
3734
+
<entry>
3735
+
Pads the result with spaces.
3736
+
This is the default.
3737
+
</entry>
3738
+
</row>
3739
+
<row>
3740
+
<entry><literal>0</literal></entry>
3741
+
<entry>
3742
+
Only left-pads numbers with zeros.
3743
+
With <literal>s</literal> specifiers this can
3744
+
also right-pad with zeros.
3745
+
</entry>
3746
+
</row>
3747
+
<row>
3748
+
<entry><literal>'</literal>(char)</entry>
3749
+
<entry>
3750
+
Pads the result with the character (char).
3751
+
</entry>
3752
+
</row>
3753
+
</tbody>
3754
+
</tgroup>
3755
+
</table>
3756
+
</para>
3757
+
3758
+
<formalpara>
3759
+
<title>Width</title>
3760
+
<para>
3761
+
Either an integer that says how many characters (minimum)
3762
+
this conversion should result in, or <literal>*</literal>.
3763
+
If <literal>*</literal> is used, then the width is supplied
3764
+
as an additional integer value preceding the one formatted
3765
+
by the specifier.
3766
+
</para>
3767
+
</formalpara>
3768
+
3769
+
<formalpara>
3770
+
<title>Precision</title>
3771
+
<para>
3772
+
A period <literal>.</literal> optionally followed by
3773
+
either an integer or <literal>*</literal>,
3774
+
whose meaning depends on the specifier:
3775
+
<itemizedlist>
3776
+
<listitem>
3777
+
<simpara>
3778
+
For <literal>e</literal>, <literal>E</literal>,
3779
+
<literal>f</literal> and <literal>F</literal>
3780
+
specifiers: this is the number of digits to be printed
3781
+
after the decimal point (by default, this is 6).
3782
+
</simpara>
3783
+
</listitem>
3784
+
<listitem>
3785
+
<simpara>
3786
+
For <literal>g</literal>, <literal>G</literal>,
3787
+
<literal>h</literal> and <literal>H</literal>
3788
+
specifiers: this is the maximum number of significant
3789
+
digits to be printed.
3790
+
</simpara>
3791
+
</listitem>
3792
+
<listitem>
3793
+
<simpara>
3794
+
For <literal>s</literal> specifier: it acts as a cutoff point,
3795
+
setting a maximum character limit to the string.
3796
+
</simpara>
3797
+
</listitem>
3798
+
</itemizedlist>
3799
+
<note>
3800
+
<simpara>
3801
+
If the period is specified without an explicit value for precision,
3802
+
0 is assumed. If <literal>*</literal> is used, the precision is
3803
+
supplied as an additional integer value preceding the one formatted
3804
+
by the specifier.
3805
+
</simpara>
3806
+
</note>
3807
+
</para>
3808
+
</formalpara>
3809
+
3810
+
<para>
3811
+
<table>
3812
+
<title>Specifiers</title>
3813
+
<tgroup cols="2">
3814
+
<thead>
3815
+
<row>
3816
+
<entry>Specifier</entry>
3817
+
<entry>&Description;</entry>
3818
+
</row>
3819
+
</thead>
3820
+
<tbody>
3821
+
<row>
3822
+
<entry><literal>%</literal></entry>
3823
+
<entry>
3824
+
A literal percent character. No argument is required.
3825
+
</entry>
3826
+
</row>
3827
+
<row>
3828
+
<entry><literal>b</literal></entry>
3829
+
<entry>
3830
+
The argument is treated as an integer and presented
3831
+
as a binary number.
3832
+
</entry>
3833
+
</row>
3834
+
<row>
3835
+
<entry><literal>c</literal></entry>
3836
+
<entry>
3837
+
The argument is treated as an integer and presented
3838
+
as the character with that ASCII.
3839
+
</entry>
3840
+
</row>
3841
+
<row>
3842
+
<entry><literal>d</literal></entry>
3843
+
<entry>
3844
+
The argument is treated as an integer and presented
3845
+
as a (signed) decimal number.
3846
+
</entry>
3847
+
</row>
3848
+
<row>
3849
+
<entry><literal>e</literal></entry>
3850
+
<entry>
3851
+
The argument is treated as scientific notation (e.g. 1.2e+2).
3852
+
</entry>
3853
+
</row>
3854
+
<row>
3855
+
<entry><literal>E</literal></entry>
3856
+
<entry>
3857
+
Like the <literal>e</literal> specifier but uses
3858
+
uppercase letter (e.g. 1.2E+2).
3859
+
</entry>
3860
+
</row>
3861
+
<row>
3862
+
<entry><literal>f</literal></entry>
3863
+
<entry>
3864
+
The argument is treated as a float and presented
3865
+
as a floating-point number (locale aware).
3866
+
</entry>
3867
+
</row>
3868
+
<row>
3869
+
<entry><literal>F</literal></entry>
3870
+
<entry>
3871
+
The argument is treated as a float and presented
3872
+
as a floating-point number (non-locale aware).
3873
+
</entry>
3874
+
</row>
3875
+
<row>
3876
+
<entry><literal>g</literal></entry>
3877
+
<entry>
3878
+
<para>
3879
+
General format.
3880
+
</para>
3881
+
<para>
3882
+
Let P equal the precision if nonzero, 6 if the precision is omitted,
3883
+
or 1 if the precision is zero.
3884
+
Then, if a conversion with style E would have an exponent of X:
3885
+
</para>
3886
+
<para>
3887
+
If P > X ≥ −4, the conversion is with style f and precision P − (X + 1).
3888
+
Otherwise, the conversion is with style e and precision P − 1.
3889
+
</para>
3890
+
</entry>
3891
+
</row>
3892
+
<row>
3893
+
<entry><literal>G</literal></entry>
3894
+
<entry>
3895
+
Like the <literal>g</literal> specifier but uses
3896
+
<literal>E</literal> and <literal>f</literal>.
3897
+
</entry>
3898
+
</row>
3899
+
<row>
3900
+
<entry><literal>h</literal></entry>
3901
+
<entry>
3902
+
Like the <literal>g</literal> specifier but uses <literal>F</literal>.
3903
+
Available as of PHP 8.0.0.
3904
+
</entry>
3905
+
</row>
3906
+
<row>
3907
+
<entry><literal>H</literal></entry>
3908
+
<entry>
3909
+
Like the <literal>g</literal> specifier but uses
3910
+
<literal>E</literal> and <literal>F</literal>. Available as of PHP 8.0.0.
3911
+
</entry>
3912
+
</row>
3913
+
<row>
3914
+
<entry><literal>o</literal></entry>
3915
+
<entry>
3916
+
The argument is treated as an integer and presented
3917
+
as an octal number.
3918
+
</entry>
3919
+
</row>
3920
+
<row>
3921
+
<entry><literal>s</literal></entry>
3922
+
<entry>
3923
+
The argument is treated and presented as a string.
3924
+
</entry>
3925
+
</row>
3926
+
<row>
3927
+
<entry><literal>u</literal></entry>
3928
+
<entry>
3929
+
The argument is treated as an integer and presented
3930
+
as an unsigned decimal number.
3931
+
</entry>
3932
+
</row>
3933
+
<row>
3934
+
<entry><literal>x</literal></entry>
3935
+
<entry>
3936
+
The argument is treated as an integer and presented
3937
+
as a hexadecimal number (with lowercase letters).
3938
+
</entry>
3939
+
</row>
3940
+
<row>
3941
+
<entry><literal>X</literal></entry>
3942
+
<entry>
3943
+
The argument is treated as an integer and presented
3944
+
as a hexadecimal number (with uppercase letters).
3945
+
</entry>
3946
+
</row>
3947
+
</tbody>
3948
+
</tgroup>
3949
+
</table>
3950
+
</para>
3951
+
3952
+
<warning>
3953
+
<para>
3954
+
The <literal>c</literal> type specifier ignores padding and width
3955
+
</para>
3956
+
</warning>
3957
+
3958
+
<warning>
3959
+
<para>
3960
+
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
3961
+
</para>
3962
+
</warning>
3963
+
3964
+
<para>
3965
+
Variables will be co-erced to a suitable type for the specifier:
3966
+
<table>
3967
+
<title>Type Handling</title>
3968
+
<tgroup cols="2">
3969
+
<thead>
3970
+
<row>
3971
+
<entry>Type</entry>
3972
+
<entry>Specifiers</entry>
3973
+
</row>
3974
+
</thead>
3975
+
<tbody>
3976
+
<row>
3977
+
<entry><type>string</type></entry>
3978
+
<entry><literal>s</literal></entry>
3979
+
</row>
3980
+
<row>
3981
+
<entry><type>int</type></entry>
3982
+
<entry>
3983
+
<literal>d</literal>,
3984
+
<literal>u</literal>,
3985
+
<literal>c</literal>,
3986
+
<literal>o</literal>,
3987
+
<literal>x</literal>,
3988
+
<literal>X</literal>,
3989
+
<literal>b</literal>
3990
+
</entry>
3991
+
</row>
3992
+
<row>
3993
+
<entry><type>float</type></entry>
3994
+
<entry>
3995
+
<literal>e</literal>,
3996
+
<literal>E</literal>,
3997
+
<literal>f</literal>,
3998
+
<literal>F</literal>,
3999
+
<literal>g</literal>,
4000
+
<literal>G</literal>,
4001
+
<literal>h</literal>,
4002
+
<literal>H</literal>
4003
+
</entry>
4004
+
</row>
4005
+
</tbody>
4006
+
</tgroup>
4007
+
</table>
4008
+
</para>
4009
+
</listitem>
4010
+
</varlistentry>
4011
+
'>
4012
+
4013
+
<!ENTITY strings.scanf.parameter.format '
4014
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
4015
+
<term><parameter>format</parameter></term>
4016
+
<listitem>
4017
+
<para>
4018
+
The interpreted format for <parameter>string</parameter>, which is
4019
+
described in the documentation for <function>sprintf</function> with
4020
+
following differences:
4021
+
<simplelist>
4022
+
<member>
4023
+
Function is not locale-aware.
4024
+
</member>
4025
+
<member>
4026
+
<literal>F</literal>, <literal>g</literal>, <literal>G</literal> and
4027
+
<literal>b</literal> are not supported.
4028
+
</member>
4029
+
<member>
4030
+
<literal>D</literal> stands for decimal number.
4031
+
</member>
4032
+
<member>
4033
+
<literal>i</literal> stands for integer with base detection.
4034
+
</member>
4035
+
<member>
4036
+
<literal>n</literal> stands for number of characters processed so far.
4037
+
</member>
4038
+
<member>
4039
+
<literal>s</literal> stops reading at any whitespace character.
4040
+
</member>
4041
+
<member>
4042
+
<literal>*</literal> instead of <literal>argnum$</literal> suppresses
4043
+
the assignment of this conversion specification.
4044
+
</member>
4045
+
</simplelist>
4046
+
</para>
4047
+
</listitem>
4048
+
</varlistentry>
4049
+
'>
4050
+
4051
+
<!ENTITY strings.parameter.needle.non-string '
4052
+
<para xmlns="http://docbook.org/ns/docbook">
4053
+
Prior to PHP 8.0.0, if <parameter>needle</parameter> is not a string, it is converted
4054
+
to an integer and applied as the ordinal value of a character.
4055
+
This behavior is deprecated as of PHP 7.3.0, and relying on it is highly
4056
+
discouraged. Depending on the intended behavior, the
4057
+
<parameter>needle</parameter> should either be explicitly cast to string,
4058
+
or an explicit call to <function>chr</function> should be performed.
4059
+
</para>
4060
+
'>
4061
+
4062
+
<!ENTITY strings.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
4063
+
<entry>8.0.0</entry>
4064
+
<entry>
4065
+
<parameter>needle</parameter> now accepts an empty string.
4066
+
</entry>
4067
+
</row>'>
4068
+
2125
4069
<!ENTITY strings.changelog.encoding '
2126
4070
<row xmlns="http://docbook.org/ns/docbook">
2127
4071
<entry>5.6.0</entry>
...
...
@@ -2134,6 +4078,163 @@ used.</para>'>
2134
4078
</row>
2135
4079
'>
2136
4080
4081
+
<!ENTITY strings.changelog.ascii-case-conversion '
4082
+
<row xmlns="http://docbook.org/ns/docbook">
4083
+
<entry>8.2.0</entry>
4084
+
<entry>
4085
+
Case conversion no longer depends on the locale set with
4086
+
<function>setlocale</function>. Only ASCII characters will be converted.
4087
+
</entry>
4088
+
</row>
4089
+
'>
4090
+
4091
+
<!ENTITY strings.changelog.ascii-case-folding '
4092
+
<row xmlns="http://docbook.org/ns/docbook">
4093
+
<entry>8.2.0</entry>
4094
+
<entry>
4095
+
Case folding no longer depends on the locale set with
4096
+
<function>setlocale</function>. Only ASCII case folding will be done.
4097
+
Non-ASCII bytes will be compared by their byte value.
4098
+
</entry>
4099
+
</row>
4100
+
'>
4101
+
4102
+
<!ENTITY strings.changelog.sprintf '
4103
+
<informaltable xmlns="http://docbook.org/ns/docbook">
4104
+
<tgroup cols="2">
4105
+
<thead>
4106
+
<row>
4107
+
<entry>&Version;</entry>
4108
+
<entry>&Description;</entry>
4109
+
</row>
4110
+
</thead>
4111
+
<tbody>
4112
+
<row>
4113
+
<entry>8.0.0</entry>
4114
+
<entry>
4115
+
This function no longer returns &false; on failure.
4116
+
</entry>
4117
+
</row>
4118
+
<row>
4119
+
<entry>8.0.0</entry>
4120
+
<entry>
4121
+
Throw a <classname>ValueError</classname> if the number of arguments is zero;
4122
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4123
+
</entry>
4124
+
</row>
4125
+
<row>
4126
+
<entry>8.0.0</entry>
4127
+
<entry>
4128
+
Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4129
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4130
+
</entry>
4131
+
</row>
4132
+
<row>
4133
+
<entry>8.0.0</entry>
4134
+
<entry>
4135
+
Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4136
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4137
+
</entry>
4138
+
</row>
4139
+
<row>
4140
+
<entry>8.0.0</entry>
4141
+
<entry>
4142
+
Throw a <classname>ArgumentCountError</classname> when less arguments are given than required;
4143
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4144
+
</entry>
4145
+
</row>
4146
+
</tbody>
4147
+
</tgroup>
4148
+
</informaltable>
4149
+
'>
4150
+
4151
+
<!ENTITY strings.changelog.vsprintf '
4152
+
<informaltable xmlns="http://docbook.org/ns/docbook">
4153
+
<tgroup cols="2">
4154
+
<thead>
4155
+
<row>
4156
+
<entry>&Version;</entry>
4157
+
<entry>&Description;</entry>
4158
+
</row>
4159
+
</thead>
4160
+
<tbody>
4161
+
<row>
4162
+
<entry>8.0.0</entry>
4163
+
<entry>
4164
+
This function no longer returns &false; on failure.
4165
+
</entry>
4166
+
</row>
4167
+
<row>
4168
+
<entry>8.0.0</entry>
4169
+
<entry>
4170
+
Throw a <classname>ValueError</classname> if the number of arguments is zero;
4171
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4172
+
</entry>
4173
+
</row>
4174
+
<row>
4175
+
<entry>8.0.0</entry>
4176
+
<entry>
4177
+
Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4178
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4179
+
</entry>
4180
+
</row>
4181
+
<row>
4182
+
<entry>8.0.0</entry>
4183
+
<entry>
4184
+
Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4185
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4186
+
</entry>
4187
+
</row>
4188
+
<row>
4189
+
<entry>8.0.0</entry>
4190
+
<entry>
4191
+
Throw a <classname>ValueError</classname> when less arguments are given than required;
4192
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4193
+
</entry>
4194
+
</row>
4195
+
</tbody>
4196
+
</tgroup>
4197
+
</informaltable>
4198
+
'>
4199
+
4200
+
<!ENTITY strings.errors.sprintf '
4201
+
<para xmlns="http://docbook.org/ns/docbook">
4202
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
4203
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4204
+
</para>
4205
+
<para xmlns="http://docbook.org/ns/docbook">
4206
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4207
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4208
+
</para>
4209
+
<para xmlns="http://docbook.org/ns/docbook">
4210
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4211
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4212
+
</para>
4213
+
<para xmlns="http://docbook.org/ns/docbook">
4214
+
As of PHP 8.0.0, a <classname>ArgumentCountError</classname> is thrown when less arguments are given than required.
4215
+
Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
4216
+
</para>
4217
+
'>
4218
+
4219
+
<!ENTITY strings.errors.vsprintf '
4220
+
<para xmlns="http://docbook.org/ns/docbook">
4221
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
4222
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4223
+
</para>
4224
+
<para xmlns="http://docbook.org/ns/docbook">
4225
+
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>.
4226
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4227
+
</para>
4228
+
<para xmlns="http://docbook.org/ns/docbook">
4229
+
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>.
4230
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4231
+
</para>
4232
+
<para xmlns="http://docbook.org/ns/docbook">
4233
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown when less arguments are given than required.
4234
+
Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
4235
+
</para>
4236
+
'>
4237
+
2137
4238
<!-- filter snippets -->
2138
4239
<!ENTITY filter.param.filter '
2139
4240
<varlistentry xmlns="http://docbook.org/ns/docbook">
...
...
@@ -2156,32 +4257,65 @@ used.</para>'>
2156
4257
<!-- csprng snippets -->
2157
4258
<!ENTITY csprng.sources '
2158
4259
<para xmlns="http://docbook.org/ns/docbook">
2159
-
The sources of randomness used for this function are as follows:
4260
+
The sources of randomness in the order of priority are as follows:
2160
4261
</para>
2161
-
<itemizedlist xmlns="http://docbook.org/ns/docbook">
4262
+
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
2162
4263
<listitem>
2163
-
<simpara>
2164
-
On Windows,
2165
-
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.csprng.crypt-gen-random;"><function>CryptGenRandom</function></link>
2166
-
will always be used.
2167
-
</simpara>
4264
+
<para>
4265
+
Linux: <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4266
+
</para>
2168
4267
</listitem>
2169
4268
<listitem>
2170
-
<simpara>
2171
-
On Linux, the
2172
-
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.csprng.get-random-2;">getrandom(2)</link>
2173
-
syscall will be used if available.
2174
-
</simpara>
4269
+
<para>
4270
+
FreeBSD >= 12 (PHP >= 7.3): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4271
+
</para>
4272
+
</listitem>
4273
+
<listitem>
4274
+
<para>
4275
+
Windows (PHP >= 7.2): <link xlink:href="&url.csprng.cng-api;">CNG-API</link>
4276
+
</para>
4277
+
<para>
4278
+
Windows: <link xlink:href="&url.csprng.crypt-gen-random;">CryptGenRandom</link>
4279
+
</para>
4280
+
</listitem>
4281
+
<listitem>
4282
+
<para>
4283
+
macOS (PHP >= 8.2; >= 8.1.9; >= 8.0.22 if CCRandomGenerateBytes is available at compile time): CCRandomGenerateBytes()
4284
+
</para>
4285
+
<para>
4286
+
macOS (PHP >= 8.1; >= 8.0.2): arc4random_buf(), <filename>/dev/urandom</filename>
4287
+
</para>
4288
+
</listitem>
4289
+
<listitem>
4290
+
<para>
4291
+
NetBSD >= 7 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
4292
+
</para>
4293
+
</listitem>
4294
+
<listitem>
4295
+
<para>
4296
+
OpenBSD >= 5.5 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
4297
+
</para>
4298
+
</listitem>
4299
+
<listitem>
4300
+
<para>
4301
+
DragonflyBSD (PHP >= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4302
+
</para>
4303
+
</listitem>
4304
+
<listitem>
4305
+
<para>
4306
+
Solaris (PHP >= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4307
+
</para>
2175
4308
</listitem>
2176
4309
<listitem>
2177
4310
<simpara>
2178
-
On other platforms, <filename>/dev/urandom</filename> will be used.
4311
+
Any combination of operating system and PHP version not previously mentioned: <filename>/dev/urandom</filename>
2179
4312
</simpara>
2180
4313
</listitem>
2181
4314
<listitem>
2182
4315
<simpara>
2183
-
If none of the aforementioned sources are available, then an
2184
-
<classname>Exception</classname> will be thrown.
4316
+
If none of the sources are available or they all fail to generate
4317
+
randomness, then a <classname>Random\RandomException</classname>
4318
+
will be thrown.
2185
4319
</simpara>
2186
4320
</listitem>
2187
4321
</itemizedlist>
...
...
@@ -2190,13 +4324,7 @@ used.</para>'>
2190
4324
<listitem xmlns="http://docbook.org/ns/docbook">
2191
4325
<simpara>
2192
4326
If an appropriate source of randomness cannot be found,
2193
-
an <classname>Exception</classname> will be thrown.
2194
-
</simpara>
2195
-
</listitem>
2196
-
<listitem xmlns="http://docbook.org/ns/docbook">
2197
-
<simpara>
2198
-
If invalid parameters are given, a <classname>TypeError</classname>
2199
-
will be thrown.
4327
+
a <classname>Random\RandomException</classname> will be thrown.
2200
4328
</simpara>
2201
4329
</listitem>
2202
4330
'>
...
...
@@ -2210,6 +4338,61 @@ used.</para>'>
2210
4338
</note>
2211
4339
'>
2212
4340
4341
+
<!-- Random snippets -->
4342
+
<!ENTITY random.engineErrors '
4343
+
<listitem xmlns="http://docbook.org/ns/docbook">
4344
+
<simpara>
4345
+
Any <classname>Throwable</classname>s thrown by the <methodname>Random\Engine::generate</methodname> method
4346
+
of the underlying <link linkend="random-randomizer.props.engine"><literal>Random\Randomizer::$engine</literal></link>.
4347
+
</simpara>
4348
+
</listitem>
4349
+
'>
4350
+
4351
+
<!-- UOPZ snippets -->
4352
+
4353
+
<!ENTITY uopz.warn.removed.function-5-0-0 '<warning
4354
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
4355
+
<emphasis>REMOVED</emphasis> in PECL uopz 5.0.0.</simpara></warning>'>
4356
+
4357
+
<!-- XML snippets -->
4358
+
<!ENTITY xml.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
4359
+
<term><parameter>parser</parameter></term>
4360
+
<listitem>
4361
+
<para>
4362
+
The XML parser.
4363
+
</para>
4364
+
</listitem>
4365
+
</varlistentry>'>
4366
+
4367
+
<!ENTITY xml.handler.description '<para xmlns="http://docbook.org/ns/docbook">
4368
+
If &null; or an empty string is passed, the handler is reset to its default state.
4369
+
</para>
4370
+
<para xmlns="http://docbook.org/ns/docbook">
4371
+
If <parameter>handler</parameter> is a <type>callable</type>,
4372
+
the callable is set as the handler.
4373
+
</para>
4374
+
<para xmlns="http://docbook.org/ns/docbook">
4375
+
If <parameter>handler</parameter> is a <type>string</type>,
4376
+
it can be the name of a method of an object set with
4377
+
<function>xml_set_object</function>.
4378
+
</para>'>
4379
+
4380
+
<!ENTITY xml.handler.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
4381
+
<term><parameter>parser</parameter></term>
4382
+
<listitem>
4383
+
<simpara>
4384
+
The XML parser calling the handler.
4385
+
</simpara>
4386
+
</listitem>
4387
+
</varlistentry>'>
4388
+
4389
+
<!ENTITY xml.changelog.parser-param '<row xmlns="http://docbook.org/ns/docbook">
4390
+
<entry>8.0.0</entry>
4391
+
<entry>
4392
+
<parameter>parser</parameter> expects an <classname>XMLParser</classname>
4393
+
instance now; previously, a valid <literal>xml</literal> <type>resource</type> was expected.
4394
+
</entry>
4395
+
</row>'>
2213
4396
2214
4397
<!-- Migration Guide snippets -->
2215
4398
<!ENTITY migration56.openssl.peer-verification '
2216
4399