language-snippets.ent
21e1338e9721534c00085ff3cff25e2dd2e84dc9
...
...
@@ -18,21 +18,46 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
18
18
highly discouraged.</simpara></warning>'>
19
19

20
20
<!-- Cautions -->
21
-
<!ENTITY caution.cryptographically-insecure '<caution xmlns="http://docbook.org/ns/docbook"><para>This function does not
22
-
generate cryptographically secure values, and should not be used for cryptographic purposes. If you need a
23
-
cryptographically secure value, consider using <function>random_int</function>, <function>random_bytes</function>, or
24
-
<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&#37; probability after less than
43
+
80,000 randomly generated seeds according to the birthday problem. A 10&#37; 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>'>
25
55

26
56
<!-- Notes -->
27
57

28
58
<!ENTITY note.bin-safe '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is
29
59
binary-safe.</simpara></note>'>
30
60

31
-
<!ENTITY note.locale-single-byte '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is locale-aware
32
-
and will handle input according to the currently set locale. However, it only works on single-byte character sets.
33
-
If you need to use multibyte characters (most non-western-European languages) look at the
34
-
<link linkend="book.mbstring">multibyte</link> or <link linkend="book.intl">intl</link> extensions instead.</simpara></note>'>
35
-

36
61
<!ENTITY note.clearstatcache '<note xmlns="http://docbook.org/ns/docbook"><simpara>The results of this
37
62
function are cached. See <function>clearstatcache</function> for
38
63
more details.</simpara></note>'>
...
...
@@ -71,6 +96,13 @@ current scope to determine parameter details, it cannot be used as a
71
96
function parameter in versions prior to 5.3.0. If this value must be passed, the results should be assigned
72
97
to a variable, and that variable should be passed.</para></note>'>
73
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
+

74
106
<!ENTITY note.line-endings '<note xmlns="http://docbook.org/ns/docbook"><simpara>If PHP is not properly recognizing
75
107
the line endings when reading files either on or created by a Macintosh
76
108
computer, enabling the
...
...
@@ -147,6 +179,13 @@ from one file system to another.</para></note>'>
147
179
</note>
148
180
'>
149
181

182
+
<!ENTITY note.reset-index "<note xmlns='http://docbook.org/ns/docbook'>
183
+
<para>
184
+
Resets array's internal pointer to the first element.
185
+
</para>
186
+
</note>
187
+
">
188
+

150
189
<!ENTITY note.resource-migration-8.0-dead-function '<note xmlns="http://docbook.org/ns/docbook">
151
190
<para>
152
191
This function has no effect. Prior to PHP 8.0.0, this function was used to close the resource.
...
...
@@ -295,6 +334,10 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
295
334
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
296
335
is highly discouraged.</simpara></warning>'>
297
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
+

298
341
<!ENTITY warn.deprecated.function-8-0-0 '<warning
299
342
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
300
343
<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0. Relying on this function
...
...
@@ -305,6 +348,21 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
305
348
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
306
349
is highly discouraged.</simpara></warning>'>
307
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
+

308
366
<!ENTITY removed.php.future 'This deprecated feature <emphasis xmlns="http://docbook.org/ns/docbook">will</emphasis>
309
367
certainly be <emphasis xmlns="http://docbook.org/ns/docbook">removed</emphasis> in the future.'>
310
368

...
...
@@ -512,6 +570,15 @@ currently not documented; only its argument list is available.
512
570
</para>
513
571
'>
514
572

573
+
<!ENTITY warn.deprecated.function-8-1-0.alternatives '<warning
574
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
575
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
576
+
is highly discouraged.</simpara></warning>
577
+
<para xmlns="http://docbook.org/ns/docbook">
578
+
Alternatives to this function include:
579
+
</para>
580
+
'>
581
+

515
582
<!-- Misc -->
516
583

517
584
<!ENTITY version.exists.asof 'This exists as of PHP '>
...
...
@@ -548,6 +615,16 @@ currently not documented; only its argument list is available.
548
615

549
616
<!ENTITY example.outputs.80 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.0:</para>'>
550
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
+

551
628
<!ENTITY example.outputs.32bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 32 bit machines:</para>'>
552
629

553
630
<!ENTITY example.outputs.64bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 64 bit machines:</para>'>
...
...
@@ -568,6 +645,22 @@ something similar to:</para>'>
568
645
<function>reset</function> the <type>array</type> pointer of the input array after
569
646
use.</simpara></note>'>
570
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
+

571
664
<!ENTITY seealso.array.sorting 'The <link xmlns="http://docbook.org/ns/docbook" linkend="array.sorting">comparison of array sorting functions</link>'>
572
665

573
666
<!ENTITY sort.flags.parameter '<varlistentry xmlns="http://docbook.org/ns/docbook">
...
...
@@ -617,6 +710,44 @@ use.</simpara></note>'>
617
710
</varlistentry>
618
711
'>
619
712

713
+
<!ENTITY sort.callback.description '<para xmlns="http://docbook.org/ns/docbook">
714
+
&return.callbacksort;
715
+
</para>
716
+
&callback.cmp;
717
+
<caution xmlns="http://docbook.org/ns/docbook">
718
+
<para>
719
+
Returning <emphasis>non-integer</emphasis> values from the comparison
720
+
function, such as <type>float</type>, will result in an internal cast to
721
+
<type>int</type> of the callback&apos;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.
732
+

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
+

620
751
<!ENTITY ini.shorthandbytes '<simpara xmlns="http://docbook.org/ns/docbook">When an <type>int</type> is used, the
621
752
value is measured in bytes. Shorthand notation, as described
622
753
in <link linkend="faq.using.shorthandbytes">this FAQ</link>, may also be used.
...
...
@@ -655,6 +786,8 @@ files from the PHP folder into the Windows system directory also works
655
786

656
787
<!ENTITY foreach '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.foreach">foreach</link>'>
657
788

789
+
<!ENTITY match '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.match">match</link>'>
790
+

658
791
<!ENTITY yield '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.yield">yield</link>'>
659
792

660
793
<!ENTITY parameter.context 'Refer to the <link xmlns="http://docbook.org/ns/docbook" linkend="context">context</link>
...
...
@@ -665,6 +798,13 @@ searched for within the <link xmlns="http://docbook.org/ns/docbook" linkend="ini
665
798

666
799
<!-- Returns -->
667
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
+

668
808
<!ENTITY return.falseforfailure ' or &false; on failure'>
669
809
<!ENTITY return.falseforfailure.style.procedural '&style.procedural; returns &false; on failure.'>
670
810

...
...
@@ -686,6 +826,32 @@ information. Use <link linkend="language.operators.comparison">the ===
686
826
operator</link> for testing the return value of this
687
827
function.</simpara></warning>'>
688
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
+

689
855
<!-- FileInfo -->
690
856
<!ENTITY fileinfo.parameters.finfo '<para xmlns="http://docbook.org/ns/docbook">An <classname>finfo</classname> instance, returned by <function>finfo_open</function>.</para>'>
691
857
<!ENTITY fileinfo.changelog.finfo-object '<row xmlns="http://docbook.org/ns/docbook">
...
...
@@ -737,12 +903,12 @@ PHP is compiled with freetype support (<option role="configure">--with-freetype-
737
903

738
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>'>
739
905

740
-
<!ENTITY gd.image.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
741
-
image</parameter></term><listitem><para>A <classname>GdImage</classname> object, 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,
742
908
such as <function>imagecreatetruecolor</function>.</para></listitem></varlistentry>'>
743
909

744
-
<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
745
-
font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in
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
746
912
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or <classname>GdFont</classname> instance,
747
913
returned by <function>imageloadfont</function>.</para></listitem></varlistentry>'>
748
914

...
...
@@ -890,14 +1056,14 @@ purposes.</simpara></warning>'>
890
1056
<entry>8.0.0</entry>
891
1057
<entry>
892
1058
<parameter>image</parameter> expects a <classname>GdImage</classname>
893
-
instance now; previously, a <type>resource</type> was expected.
1059
+
instance now; previously, a valid <literal>gd</literal> <type>resource</type> was expected.
894
1060
</entry>
895
1061
</row>'>
896
1062

897
1063
<!-- DBM notes -->
898
1064

899
-
<!ENTITY dbm.dbm-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
900
-
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,
901
1067
returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
902
1068

903
1069
<!-- JSON notes -->
...
...
@@ -1023,16 +1189,16 @@ returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
1023
1189
<entry>8.1.0</entry>
1024
1190
<entry>
1025
1191
The <parameter>imap</parameter> parameter expects an <classname>IMAP\Connection</classname>
1026
-
instance now; previously, a &resource; was expected.
1192
+
instance now; previously, a valid <literal>imap</literal> &resource; was expected.
1027
1193
</entry>
1028
1194
</row>'>
1029
1195

1030
-
<!ENTITY imap.imap-parameter.imap '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1031
-
imap</parameter></term><listitem><para>An <classname>IMAP\Connection</classname> instance.</para></listitem></varlistentry>'>
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>'>
1032
1198

1033
1199
<!-- Deprecated -->
1034
-
<!ENTITY imap.imap-stream.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1035
-
imap</parameter></term><listitem><para>An IMAP stream returned by
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
1036
1202
<function>imap_open</function>.</para></listitem></varlistentry>'>
1037
1203

1038
1204
<!ENTITY imap.pattern '<para xmlns="http://docbook.org/ns/docbook">Specifies where in the mailbox hierarchy
...
...
@@ -1061,7 +1227,7 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1061
1227

1062
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>'>
1063
1229

1064
-
<!ENTITY intl.codepoint.return '<para xmlns="http://docbook.org/ns/docbook">The return type will be <type>int</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>'>
1065
1231

1066
1232
<!ENTITY intl.codepoint.example 'Testing different code points'>
1067
1233

...
...
@@ -1098,7 +1264,7 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1098
1264
<entry>8.1.0</entry>
1099
1265
<entry>
1100
1266
The <parameter>ldap</parameter> parameter expects an <classname>LDAP\Connection</classname>
1101
-
instance now; previously, a &resource; was expected.
1267
+
instance now; previously, a valid <literal>ldap link</literal> &resource; was expected.
1102
1268
</entry>
1103
1269
</row>'>
1104
1270

...
...
@@ -1106,7 +1272,7 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1106
1272
<entry>8.1.0</entry>
1107
1273
<entry>
1108
1274
The <parameter>entry</parameter> parameter expects an <classname>LDAP\ResultEntry</classname>
1109
-
instance now; previously, a &resource; was expected.
1275
+
instance now; previously, a valid <literal>ldap result entry</literal> &resource; was expected.
1110
1276
</entry>
1111
1277
</row>'>
1112
1278

...
...
@@ -1114,7 +1280,7 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1114
1280
<entry>8.1.0</entry>
1115
1281
<entry>
1116
1282
The <parameter>result</parameter> parameter expects an <classname>LDAP\Result</classname>
1117
-
instance now; previously, a &resource; was expected.
1283
+
instance now; previously, a valid <literal>ldap result</literal> &resource; was expected.
1118
1284
</entry>
1119
1285
</row>'>
1120
1286

...
...
@@ -1135,6 +1301,14 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1135
1301
</row>'>
1136
1302

1137
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>'>
1138
1312

1139
1313
<!-- mbstring notes -->
1140
1314

...
...
@@ -1178,12 +1352,20 @@ encoding value will be used.</para>'>
1178
1352

1179
1353
<!-- MCVE notes -->
1180
1354

1181
-
<!ENTITY mcve.conn.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1182
-
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
1183
1357
<function>m_initengine</function>.</para></listitem></varlistentry>'>
1184
1358

1185
1359
<!-- memcached notes -->
1186
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
+

1187
1369
<!ENTITY memcached.parameter.expiration 'The expiration time, defaults to 0. See <link
1188
1370
linkend="memcached.expiration" xmlns="http://docbook.org/ns/docbook">Expiration Times</link> for more info.'>
1189
1371

...
...
@@ -1197,6 +1379,19 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
1197
1379

1198
1380
<!ENTITY memcached.result.getresultcode 'Use <methodname xmlns="http://docbook.org/ns/docbook">Memcached::getResultCode</methodname> if necessary.'>
1199
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
+

1200
1395
<!-- password notes -->
1201
1396

1202
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.'>
...
...
@@ -1229,6 +1424,14 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
1229
1424

1230
1425
<!ENTITY pspell.parameter.pspell-config '<para xmlns="http://docbook.org/ns/docbook">An <classname>PSpell\Config</classname> instance.</para>'>
1231
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
+

1232
1435
<!-- socket entities -->
1233
1436

1234
1437
<!ENTITY sockets.changelog.socket-param '<row xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1330,11 +1533,14 @@ returned by <function>date_create</function></para></listitem></varlistentry>'>
1330
1533
returned by <function>date_create</function>.
1331
1534
The function modifies this object.</para></listitem></varlistentry>'>
1332
1535

1333
-
<!ENTITY date.datetimezone.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1334
-
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
1335
1538
returned by <function>timezone_open</function></para></listitem></varlistentry>'>
1336
1539

1337
-
<!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.'>
1338
1544

1339
1545
<!ENTITY date.timezone.dbversion 'This list is based upon the timezone database version'>
1340
1546

...
...
@@ -1363,11 +1569,8 @@ is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">domnode_
1363
1569
<!ENTITY dom.node.inserted 'This node will not show up in the document unless
1364
1570
it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNode::appendChild</function>.'>
1365
1571

1366
-
<!ENTITY dom.allowstatic '<para xmlns="http://docbook.org/ns/docbook">Prior to PHP 8.0.0 this method
1367
-
<emphasis>could</emphasis> be called statically, but would issue an <constant>E_DEPRECATED</constant> error.
1368
-
As of PHP 8.0.0 calling this method statically throws an <classname>Error</classname> exception</para>'>
1369
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&apos;s error handling functions</link> may be used to handle these errors.</para>'>
1370
-
<!ENTITY dom.note.utf8 '<note xmlns="http://docbook.org/ns/docbook"><para>The DOM extension uses UTF-8 encoding. Use <function>utf8_encode</function> and <function>utf8_decode</function> to work with texts in ISO-8859-1 encoding or <link linkend="ref.iconv">iconv</link> for other encodings.</para></note>'>
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>'>
1371
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>'>
1372
1575

1373
1576

...
...
@@ -1406,6 +1609,58 @@ As of PHP 8.0.0 calling this method statically throws an <classname>Error</class
1406
1609
</books>
1407
1610
]]></programlisting>'>
1408
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&#39;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&#39;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>.'>
1409
1664

1410
1665
<!-- FileSystem entities -->
1411
1666
<!ENTITY fs.emits.warning.on.failure '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1613,7 +1868,8 @@ linkend="ini.open-basedir">open_basedir</link>.</para></note>'>
1613
1868

1614
1869
<!ENTITY note.language-construct '<note xmlns="http://docbook.org/ns/docbook"><simpara>Because this is a
1615
1870
language construct and not a function, it cannot be called using
1616
-
<link linkend="functions.variable-functions">variable functions</link>.</simpara>
1871
+
<link linkend="functions.variable-functions">variable functions</link>,
1872
+
or <link linkend="functions.named-arguments">named arguments</link>.</simpara>
1617
1873
</note>'>
1618
1874

1619
1875
<!-- Common pieces in features/safe-mode.xml
...
...
@@ -1665,7 +1921,7 @@ The behaviour of these functions is affected by settings in &php.ini;.
1665
1921
</simpara>'>
1666
1922

1667
1923
<!ENTITY ini.php.constants 'For further details and definitions of the
1668
-
PHP_INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>
1924
+
INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>
1669
1925

1670
1926
<!-- Used in reference/$extname/constants.xml -->
1671
1927
<!ENTITY extension.constants '<simpara xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1701,12 +1957,21 @@ driver, if your code can run against multiple drivers.</simpara>'>
1701
1957

1702
1958
<!ENTITY pdo.errors.exception-not-errmode '<note xmlns="http://docbook.org/ns/docbook"><simpara>An exception is raised even when the <constant>PDO::ATTR_ERRMODE</constant> attribute is not <constant>PDO::ERRMODE_EXCEPTION</constant>.</simpara></note>'>
1703
1959

1960
+
<!-- PDO errors -->
1961
+

1962
+
<!ENTITY pdo.errors '<para xmlns="http://docbook.org/ns/docbook">
1963
+
Emits an error with level <constant>E_WARNING</constant> if the attribute <constant>PDO::ATTR_ERRMODE</constant> is set
1964
+
to <constant>PDO::ERRMODE_WARNING</constant>.
1965
+
</para>
1966
+
<para xmlns="http://docbook.org/ns/docbook">
1967
+
Throws a <classname>PDOException</classname> if the attribute <constant>PDO::ATTR_ERRMODE</constant>
1968
+
is set to <constant>PDO::ERRMODE_EXCEPTION</constant>.
1969
+
</para>'>
1970
+

1704
1971
<!-- PECL entities -->
1705
-
<!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
1706
-
is not bundled with PHP.'>
1972
+
<!ENTITY pecl.moved 'This &link.pecl; extension is not bundled with PHP.'>
1707
1973

1708
-
<!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
1709
-
is bundled with PHP.'>
1974
+
<!ENTITY pecl.bundled 'This &link.pecl; extension is bundled with PHP.'>
1710
1975

1711
1976
<!ENTITY pecl.info 'Information for installing this PECL extension may be
1712
1977
found in the manual chapter titled <link xmlns="http://docbook.org/ns/docbook" linkend="install.pecl">Installation
...
...
@@ -1732,9 +1997,8 @@ for this <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension
1732
1997

1733
1998
<!ENTITY pecl.windows.download.unbundled '&pecl.windows.download;'>
1734
1999

1735
-
<!ENTITY pecl.moved-ver 'This extension has been moved to the
1736
-
<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
1737
-
PHP as of PHP '>
2000
+
<!ENTITY pecl.moved-ver 'This extension has been moved to the &link.pecl;
2001
+
repository and is no longer bundled with PHP as of PHP '>
1738
2002

1739
2003
<!-- PGSQL entities -->
1740
2004

...
...
@@ -1743,18 +2007,28 @@ PHP as of PHP '>
1743
2007
<!ENTITY pgsql.parameter.connection-with-unspecified-default '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.
1744
2008
When <parameter>connection</parameter> is unspecified, the default connection is used.
1745
2009
The default connection is the last connection made by <function>pg_connect</function>
1746
-
or <function>pg_pconnect</function>.</para>'>
2010
+
or <function>pg_pconnect</function>.
2011
+
<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>
1747
2012

1748
2013
<!ENTITY pgsql.parameter.connection-with-nullable-default '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.
1749
2014
When <parameter>connection</parameter> is &null;, the default connection is used.
1750
2015
The default connection is the last connection made by <function>pg_connect</function>
1751
-
or <function>pg_pconnect</function>.</para>'>
2016
+
or <function>pg_pconnect</function>.
2017
+
<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>
1752
2018

1753
2019
<!ENTITY pgsql.parameter.result '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Result</classname> instance, returned by <function>pg_query</function>,
1754
2020
<function>pg_query_params</function> or <function>pg_execute</function>(among others).</para>'>
1755
2021

1756
2022
<!ENTITY pgsql.parameter.lob '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Lob</classname> instance, returned by <function>pg_lo_open</function>.</para>'>
1757
2023

2024
+
<!ENTITY pgsql.parameter.mode '<para xmlns="http://docbook.org/ns/docbook">
2025
+
An optional parameter that controls how the returned <type>array</type> is indexed.
2026
+
<parameter>mode</parameter> is a constant and can take the following values:
2027
+
<constant>PGSQL_ASSOC</constant>, <constant>PGSQL_NUM</constant> and <constant>PGSQL_BOTH</constant>.
2028
+
Using <constant>PGSQL_NUM</constant>, the function will return an array with numerical indices,
2029
+
using <constant>PGSQL_ASSOC</constant> it will return only associative indices
2030
+
while <constant>PGSQL_BOTH</constant> will return both numerical and associative indices.</para>'>
2031
+

1758
2032
<!ENTITY pgsql.changelog.connection-object '<row xmlns="http://docbook.org/ns/docbook">
1759
2033
<entry>8.1.0</entry>
1760
2034
<entry>
...
...
@@ -1800,8 +2074,8 @@ extensions in order to use these functions.</simpara>'>
1800
2074
<!ENTITY sqlsafemode '<link xmlns="http://docbook.org/ns/docbook" linkend="ini.sql.safe-mode">SQL safe mode</link>'>
1801
2075

1802
2076
<!-- APD Notes -->
1803
-
<!ENTITY apd.debug-level.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1804
-
debug_level</parameter></term><listitem><para>An integer which is formed by adding
2077
+
<!ENTITY apd.debug-level.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2078
+
<parameter>debug_level</parameter></term><listitem><para>An integer which is formed by adding
1805
2079
together the <literal>XXX_TRACE</literal> constants.</para><para>It is not recommended
1806
2080
to use <constant>MEMORY_TRACE</constant>. It is very slow and does not appear to be accurate.
1807
2081
<constant>ASSIGNMENT_TRACE</constant> is not implemented yet.</para><para>To turn on all
...
...
@@ -1809,8 +2083,8 @@ functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the val
1809
2083
</listitem></varlistentry>'>
1810
2084

1811
2085
<!-- BCMath Notes -->
1812
-
<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1813
-
scale</parameter></term><listitem><para>This optional parameter is used to set the number
2086
+
<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2087
+
<parameter>scale</parameter></term><listitem><para>This optional parameter is used to set the number
1814
2088
of digits after the decimal place in the result. If omitted, it will default to the scale set
1815
2089
globally with the <function>bcscale</function> function, or fallback to <literal>0</literal> if
1816
2090
this has not been set.</para></listitem></varlistentry>'>
...
...
@@ -1822,6 +2096,14 @@ the ASCII value of a single character (negative values have 256 added in order t
1822
2096
characters in the Extended ASCII range). Any other integer is interpreted as a string
1823
2097
containing the decimal digits of the integer.</para></note>'>
1824
2098

2099
+
<!ENTITY note.ctype.parameter.non-string '<warning xmlns="http://docbook.org/ns/docbook"><para>
2100
+
As of PHP 8.1.0, passing a non-string argument is deprecated.
2101
+
In the future, the argument will be interpreted as a string instead of an ASCII codepoint.
2102
+
Depending on the intended behavior, the argument should either be cast to &string;
2103
+
or an explicit call to <function>chr</function> should be made.</para></warning>'>
2104
+

2105
+
<!ENTITY ctype.result.empty-string 'When called with an empty string the result will always be &false;.'>
2106
+

1825
2107
<!-- FTP Notes -->
1826
2108
<!ENTITY ftp.changelog.ftp-param '<row xmlns="http://docbook.org/ns/docbook">
1827
2109
<entry>8.1.0</entry>
...
...
@@ -1837,16 +2119,16 @@ containing the decimal digits of the integer.</para></note>'>
1837
2119
<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">A <classname>GMP</classname> object, an &integer; or a numeric &string;.</para>'>
1838
2120

1839
2121
<!-- MySQLi Notes -->
1840
-
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1841
-
result</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_result</classname>
2122
+
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2123
+
<parameter>result</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_result</classname>
1842
2124
object returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>,
1843
2125
<function>mysqli_use_result</function> or <function>mysqli_stmt_get_result</function>.</para></listitem></varlistentry>'>
1844
-
<!ENTITY mysqli.link.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1845
-
mysql</parameter></term><listitem><para>Procedural style only: A <classname>mysqli</classname> object
2126
+
<!ENTITY mysqli.link.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2127
+
<parameter>mysql</parameter></term><listitem><para>Procedural style only: A <classname>mysqli</classname> object
1846
2128
returned by <function>mysqli_connect</function> or <function>mysqli_init</function>
1847
2129
</para></listitem></varlistentry>'>
1848
-
<!ENTITY mysqli.stmt.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1849
-
statement</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_stmt</classname> object
2130
+
<!ENTITY mysqli.stmt.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2131
+
<parameter>statement</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_stmt</classname> object
1850
2132
returned by <function>mysqli_stmt_init</function>.</para></listitem></varlistentry>'>
1851
2133
<!ENTITY mysqli.available.mysqlnd 'Available only with <link xmlns="http://docbook.org/ns/docbook"
1852
2134
linkend="book.mysqlnd">mysqlnd</link>.'>
...
...
@@ -1855,6 +2137,9 @@ linkend="book.mysqlnd">mysqlnd</link>.'>
1855
2137
hand-shake/authentication, which mysqlnd will use.</para><para>Libmysqlclient uses the default charset set in the
1856
2138
<filename>my.cnf</filename> or by an explicit call to <function>mysqli_options</function> prior to
1857
2139
calling <function>mysqli_real_connect</function>, but after <function>mysqli_init</function>.</para></note>'>
2140
+
<!ENTITY mysqli.integer.overflow.as.string.note '<note xmlns="http://docbook.org/ns/docbook">
2141
+
<para>If the number of rows is greater than <constant>PHP_INT_MAX</constant>,
2142
+
the number will be returned as a &string;.</para></note>'>
1858
2143
<!ENTITY mysqli.sqlinjection.warning '<warning xmlns="http://docbook.org/ns/docbook">
1859
2144
<title>Security warning: SQL injection</title><para>If the query contains any variable
1860
2145
input then <link linkend="mysqli.quickstart.prepared-statements">parameterized
...
...
@@ -1862,12 +2147,26 @@ prepared statements</link> should be used instead. Alternatively, the
1862
2147
data must be properly formatted and all strings must be escaped using
1863
2148
the <function>mysqli_real_escape_string</function>
1864
2149
function.</para></warning>'>
2150
+
<!ENTITY mysqli.conditionalexception '<para xmlns="http://docbook.org/ns/docbook">
2151
+
If mysqli error reporting is enabled (<constant>MYSQLI_REPORT_ERROR</constant>) and the requested operation fails,
2152
+
a warning is generated. If, in addition, the mode is set to <constant>MYSQLI_REPORT_STRICT</constant>,
2153
+
a <classname>mysqli_sql_exception</classname> is thrown instead.</para>'>
2154
+

2155
+
<!-- Notes for PCRE -->
2156
+
<!ENTITY pcre.pattern.warning '<para xmlns="http://docbook.org/ns/docbook">
2157
+
If the regex pattern passed does not compile to a valid regex, an <constant>E_WARNING</constant> is emitted.
2158
+
</para>'>
1865
2159

1866
2160
<!-- Notes for SAPI/Apache -->
1867
2161
<!ENTITY apache.req.module '<simpara xmlns="http://docbook.org/ns/docbook">This function is supported when PHP
1868
2162
is installed as an Apache module webserver.
1869
2163
</simpara>'>
1870
2164

2165
+
<!-- Notes for SAPI/FPM -->
2166
+
<!ENTITY fpm.intro '<para xmlns="http://docbook.org/ns/docbook">FPM (FastCGI Process Manager) is
2167
+
a primary PHP FastCGI implementation containing some features (mostly) useful for heavy-loaded sites.
2168
+
</para>'>
2169
+

1871
2170
<!-- SimpleXML Notes -->
1872
2171
<!ENTITY simplexml.iteration '<note xmlns="http://docbook.org/ns/docbook"><simpara>SimpleXML has made a rule of adding
1873
2172
iterative properties to most methods. They cannot be viewed using <function>var_dump</function>
...
...
@@ -1912,27 +2211,27 @@ the PHP &null; value.</simpara></note>'>
1912
2211

1913
2212
<!-- MSQL Notes -->
1914
2213
<!-- The msql.*.description entities are used in the parameters refsect1 -->
1915
-
<!ENTITY msql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1916
-
link_identifier</parameter></term><listitem><para>The mSQL connection.
2214
+
<!ENTITY msql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2215
+
<parameter>link_identifier</parameter></term><listitem><para>The mSQL connection.
1917
2216
If not specified, the last link opened by <function>msql_connect</function>
1918
2217
is assumed. If no such link is found, the function will try to establish a
1919
2218
link as if <function>msql_connect</function> was called, and use it.
1920
2219
</para></listitem></varlistentry>'>
1921
2220

1922
-
<!ENTITY msql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1923
-
result</parameter></term><listitem><para>The result <type>resource</type> that
2221
+
<!ENTITY msql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2222
+
<parameter>result</parameter></term><listitem><para>The result <type>resource</type> that
1924
2223
is being evaluated. This result comes from a call to
1925
2224
<function>msql_query</function>.</para></listitem></varlistentry>'>
1926
2225

1927
-
<!ENTITY msql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1928
-
field_offset</parameter></term><listitem><para>The numerical field offset. The
2226
+
<!ENTITY msql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2227
+
<parameter>field_offset</parameter></term><listitem><para>The numerical field offset. The
1929
2228
<parameter>field_offset</parameter> starts at <literal>1</literal>.</para></listitem></varlistentry>'>
1930
2229

1931
2230

1932
2231
<!-- MySQL Notes -->
1933
2232
<!-- The mysql.*.description entities are used in the parameters refsect1 -->
1934
-
<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1935
-
link_identifier</parameter></term><listitem><para>The MySQL connection. If the
2233
+
<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2234
+
<parameter>link_identifier</parameter></term><listitem><para>The MySQL connection. If the
1936
2235
link identifier is not specified, the last link opened by
1937
2236
<function>mysql_connect</function> is assumed. If no such link is found, it
1938
2237
will try to create one as if <function>mysql_connect</function> had been called
...
...
@@ -1941,20 +2240,20 @@ with no arguments. If no connection is found or established, an
1941
2240
</varlistentry>'>
1942
2241

1943
2242
<!ENTITY mysql.linkid-noreopen.description '<varlistentry
1944
-
xmlns="http://docbook.org/ns/docbook"><term><parameter>
1945
-
link_identifier</parameter></term><listitem><para>The MySQL connection. If the
2243
+
xmlns="http://docbook.org/ns/docbook"><term>
2244
+
<parameter>link_identifier</parameter></term><listitem><para>The MySQL connection. If the
1946
2245
link identifier is not specified, the last link opened by
1947
2246
<function>mysql_connect</function> is assumed. If no connection is found or
1948
2247
established, an <constant>E_WARNING</constant> level error is
1949
2248
generated.</para></listitem></varlistentry>'>
1950
2249

1951
-
<!ENTITY mysql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1952
-
result</parameter></term><listitem><para>The result <type>resource</type> that
2250
+
<!ENTITY mysql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2251
+
<parameter>result</parameter></term><listitem><para>The result <type>resource</type> that
1953
2252
is being evaluated. This result comes from a call to
1954
2253
<function>mysql_query</function>.</para></listitem></varlistentry>'>
1955
2254

1956
-
<!ENTITY mysql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1957
-
field_offset</parameter></term><listitem><para>The numerical field offset. The
2255
+
<!ENTITY mysql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2256
+
<parameter>field_offset</parameter></term><listitem><para>The numerical field offset. The
1958
2257
<parameter>field_offset</parameter> starts at <literal>0</literal>. If
1959
2258
<parameter>field_offset</parameter> does not exist, an error of level
1960
2259
<constant>E_WARNING</constant> is also issued.</para></listitem></varlistentry>'>
...
...
@@ -2004,8 +2303,8 @@ using the CT library interface to Sybase, and not with the DB library.
2004
2303
<!ENTITY sybase.db.only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when
2005
2304
using the DB library interface to Sybase, and not with the CT library.</simpara></note>'>
2006
2305

2007
-
<!ENTITY sybase.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
2008
-
link_identifier</parameter></term><listitem><para>The Sybase connection. If the
2306
+
<!ENTITY sybase.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2307
+
<parameter>link_identifier</parameter></term><listitem><para>The Sybase connection. If the
2009
2308
link identifier is not specified, the last link opened by
2010
2309
<function>sybase_connect</function> is assumed. If no such link is found, it
2011
2310
will try to create one as if <function>sybase_connect</function> was called
...
...
@@ -2019,15 +2318,15 @@ determines the unit length. If it is <literal>0</literal> or omitted, the
2019
2318
default unit as specified for the page is used. In other cases, the coordinates
2020
2319
are measured in postscript points, disregarding the current unit.</para>'>
2021
2320

2022
-
<!ENTITY cpdf.mode.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
2023
-
mode</parameter></term><listitem><para>The optional parameter <parameter>mode</parameter>
2321
+
<!ENTITY cpdf.mode.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2322
+
<parameter>mode</parameter></term><listitem><para>The optional parameter <parameter>mode</parameter>
2024
2323
determines the unit length. If it is <literal>0</literal> or omitted, the
2025
2324
default unit as specified for the page is used. In other cases, the coordinates
2026
2325
are measured in postscript points, disregarding the current unit.</para>
2027
2326
</listitem></varlistentry>'>
2028
2327

2029
-
<!ENTITY cpdf.pdf-document.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
2030
-
pdf_document</parameter></term><listitem><para>The document handle, returned by
2328
+
<!ENTITY cpdf.pdf-document.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2329
+
<parameter>pdf_document</parameter></term><listitem><para>The document handle, returned by
2031
2330
<function>cpdf_open</function>.</para></listitem></varlistentry>'>
2032
2331

2033
2332
<!-- Xattr entities -->
...
...
@@ -2080,7 +2379,7 @@ slash may also be necessary for directories.</simpara></note>'>
2080
2379
<!ENTITY Credit.Authors.and.Contributors 'Authors and Contributors'>
2081
2380

2082
2381
<!ENTITY Credit.Introduction '<para xmlns="http://docbook.org/ns/docbook"> We highlight the currently most active
2083
-
people on front page of the manual, but there are many more contributors who
2382
+
people on the front page of the manual, but there are many more contributors who
2084
2383
currently help in our work or have provided a great amount of help to the project
2085
2384
in the past. There are a lot of unnamed people who help out with user
2086
2385
notes on manual pages, which continually get included in the references, the
...
...
@@ -2140,8 +2439,8 @@ using public key authentication, use the
2140
2439
<!ENTITY returns.session.storage.retval 'The return value (usually &true; on success, &false; on failure). Note this value is returned internally to PHP for processing.'>
2141
2440

2142
2441
<!-- XMLWriter Notes -->
2143
-
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
2144
-
writer</parameter></term><listitem><para>Only for procedural calls.
2442
+
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2443
+
<parameter>writer</parameter></term><listitem><para>Only for procedural calls.
2145
2444
The <classname>XMLWriter</classname> instance that is being modified. This object is returned from a call to <function>xmlwriter_open_uri</function> or <function>xmlwriter_open_memory</function>.</para></listitem></varlistentry>'>
2146
2445

2147
2446
<!ENTITY xmlwriter.changelog.writer-param '<row xmlns="http://docbook.org/ns/docbook">
...
...
@@ -2352,6 +2651,34 @@ to be references, then they must be references in the passed argument list.'>
2352
2651

2353
2652
<!ENTITY reflection.export.param.name 'The reflection to export.'>
2354
2653

2654
+
<!ENTITY reflection.getattributes.param.name '<varlistentry xmlns="http://docbook.org/ns/docbook">
2655
+
<term><parameter>name</parameter></term>
2656
+
<listitem>
2657
+
<para>
2658
+
Filter the results to include only <classname>ReflectionAttribute</classname>
2659
+
instances for attributes matching this class name.
2660
+
</para>
2661
+
</listitem>
2662
+
</varlistentry>'>
2663
+

2664
+
<!ENTITY reflection.getattributes.param.flags '<varlistentry xmlns="http://docbook.org/ns/docbook">
2665
+
<term><parameter>flags</parameter></term>
2666
+
<listitem>
2667
+
<para>
2668
+
Flags for determining how to filter the results, if <parameter>name</parameter>
2669
+
is provided.
2670
+
</para>
2671
+
<para>
2672
+
Default is <literal>0</literal> which will only return results for attributes that
2673
+
are of the class <parameter>name</parameter>.
2674
+
</para>
2675
+
<para>
2676
+
The only other option available, is to use <constant>ReflectionAttribute::IS_INSTANCEOF</constant>,
2677
+
which will instead use <literal>instanceof</literal> for filtering.
2678
+
</para>
2679
+
</listitem>
2680
+
</varlistentry>'>
2681
+

2355
2682
<!-- SPL -->
2356
2683
<!ENTITY spl.datastructures.intro.title '<title xmlns="http://docbook.org/ns/docbook">Datastructures</title>'>
2357
2684

...
...
@@ -2594,6 +2921,18 @@ the <link linkend="set.mongodb">MongoDB</link> extension should be
2594
2921
used.</para>'>
2595
2922

2596
2923
<!-- mongodb -->
2924
+
<!ENTITY mongodb.changelog.tentative-return-types '
2925
+
<row xmlns="http://docbook.org/ns/docbook">
2926
+
<entry>PECL mongodb 1.15.0</entry>
2927
+
<entry>
2928
+
Return types for methods are declared as tentative on PHP 8.0 and newer,
2929
+
triggering deprecation notices in code that implements this interface
2930
+
without declaring the appropriate return types. The <code>#[ReturnTypeWillChange]</code>
2931
+
attribute can be added to silence the deprecation notice.
2932
+
</entry>
2933
+
</row>
2934
+
'>
2935
+

2597
2936
<!ENTITY mongodb.option.collation '
2598
2937
<row xmlns="http://docbook.org/ns/docbook">
2599
2938
<entry>collation</entry>
...
...
@@ -2611,6 +2950,20 @@ used.</para>'>
2611
2950
</entry>
2612
2951
</row>
2613
2952
'>
2953
+
<!ENTITY mongodb.option.let '
2954
+
<row xmlns="http://docbook.org/ns/docbook">
2955
+
<entry>let</entry>
2956
+
<entry><type class="union"><type>array</type><type>object</type></type></entry>
2957
+
<entry>
2958
+
<para>
2959
+
Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an aggregate expression context (e.g. <literal>$$var</literal>).
2960
+
</para>
2961
+
<para>
2962
+
This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.
2963
+
</para>
2964
+
</entry>
2965
+
</row>
2966
+
'>
2614
2967
<!ENTITY mongodb.option.encryption.keyVaultClient '
2615
2968
<row xmlns="http://docbook.org/ns/docbook">
2616
2969
<entry>keyVaultClient</entry>
...
...
@@ -2622,16 +2975,22 @@ used.</para>'>
2622
2975
<row xmlns="http://docbook.org/ns/docbook">
2623
2976
<entry>keyVaultNamespace</entry>
2624
2977
<entry><type>string</type></entry>
2625
-
<entry>A fully qualified namespace (e.g. <literal>"databaseName.collectionName"</literal>) denoting the collection that contains all data keys used for encryption and decryption.</entry>
2978
+
<entry>A fully qualified namespace (e.g. <literal>"databaseName.collectionName"</literal>) denoting the collection that contains all data keys used for encryption and decryption. This option is required.</entry>
2626
2979
</row>
2627
2980
'>
2628
2981
<!ENTITY mongodb.option.encryption.kmsProviders '
2629
-
<row xmlns="http://docbook.org/ns/docbook">
2982
+
<row xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
2630
2983
<entry>kmsProviders</entry>
2631
2984
<entry><type>array</type></entry>
2632
2985
<entry>
2633
2986
<para>
2634
-
A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Currently <literal>"aws"</literal>, <literal>"azure"</literal>, <literal>"gcp"</literal>, and <literal>"local"</literal> are supported and at least one must be specified.
2987
+
A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Supported providers include <literal>"aws"</literal>, <literal>"azure"</literal>, <literal>"gcp"</literal>, <literal>"kmip"</literal>, and <literal>"local"</literal> and at least one must be specified.
2988
+
</para>
2989
+
<para>
2990
+
If an empty document is specified for <literal>"aws"</literal>,
2991
+
<literal>"azure"</literal>, or <literal>"gcp"</literal>, the driver
2992
+
will attempt to configure the provider using
2993
+
<link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#automatic-credentials">Automatic Credentials</link>.
2635
2994
</para>
2636
2995
<para>
2637
2996
The format for <literal>"aws"</literal> is as follows:
...
...
@@ -2640,7 +2999,8 @@ used.</para>'>
2640
2999
<![CDATA[
2641
3000
aws: {
2642
3001
accessKeyId: <string>,
2643
-
secretAccessKey: <string>
3002
+
secretAccessKey: <string>,
3003
+
sessionToken: <optional string>
2644
3004
}
2645
3005
]]>
2646
3006
</programlisting>
...
...
@@ -2654,7 +3014,6 @@ azure: {
2654
3014
clientId: <string>,
2655
3015
clientSecret: <string>,
2656
3016
identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
2657
-

2658
3017
}
2659
3018
]]>
2660
3019
</programlisting>
...
...
@@ -2663,11 +3022,20 @@ azure: {
2663
3022
</para>
2664
3023
<programlisting role="javascript">
2665
3024
<![CDATA[
2666
-
aws: {
3025
+
gcp: {
2667
3026
email: <string>,
2668
3027
privateKey: <base64 string>|<MongoDB\BSON\Binary>,
2669
3028
endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
2670
-

3029
+
}
3030
+
]]>
3031
+
</programlisting>
3032
+
<para>
3033
+
The format for <literal>"kmip"</literal> is as follows:
3034
+
</para>
3035
+
<programlisting role="javascript">
3036
+
<![CDATA[
3037
+
kmip: {
3038
+
endpoint: <string>
2671
3039
}
2672
3040
]]>
2673
3041
</programlisting>
...
...
@@ -2685,6 +3053,163 @@ local: {
2685
3053
</entry>
2686
3054
</row>
2687
3055
'>
3056
+
<!ENTITY mongodb.option.encryption.masterKey-options-by-provider '
3057
+
<para xmlns="http://docbook.org/ns/docbook">
3058
+
<table>
3059
+
<title><literal>"aws"</literal> provider options</title>
3060
+
<tgroup cols="3">
3061
+
<thead>
3062
+
<row>
3063
+
<entry>Option</entry>
3064
+
<entry>Type</entry>
3065
+
<entry>Description</entry>
3066
+
</row>
3067
+
</thead>
3068
+
<tbody>
3069
+
<row>
3070
+
<entry>region</entry>
3071
+
<entry>string</entry>
3072
+
<entry>Required.</entry>
3073
+
</row>
3074
+
<row>
3075
+
<entry>key</entry>
3076
+
<entry>string</entry>
3077
+
<entry>Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).</entry>
3078
+
</row>
3079
+
<row>
3080
+
<entry>endpoint</entry>
3081
+
<entry>string</entry>
3082
+
<entry>Optional. An alternate host identifier to send KMS requests to. May include port number.</entry>
3083
+
</row>
3084
+
</tbody>
3085
+
</tgroup>
3086
+
</table>
3087
+
</para>
3088
+
<para xmlns="http://docbook.org/ns/docbook">
3089
+
<table>
3090
+
<title><literal>"azure"</literal> provider options</title>
3091
+
<tgroup cols="3">
3092
+
<thead>
3093
+
<row>
3094
+
<entry>Option</entry>
3095
+
<entry>Type</entry>
3096
+
<entry>Description</entry>
3097
+
</row>
3098
+
</thead>
3099
+
<tbody>
3100
+
<row>
3101
+
<entry>keyVaultEndpoint</entry>
3102
+
<entry>string</entry>
3103
+
<entry>Required. Host with optional port (e.g. "example.vault.azure.net").</entry>
3104
+
</row>
3105
+
<row>
3106
+
<entry>keyName</entry>
3107
+
<entry>string</entry>
3108
+
<entry>Required.</entry>
3109
+
</row>
3110
+
<row>
3111
+
<entry>keyVersion</entry>
3112
+
<entry>string</entry>
3113
+
<entry>Optional. A specific version of the named key. Defaults to using the key&apos;s primary version.</entry>
3114
+
</row>
3115
+
</tbody>
3116
+
</tgroup>
3117
+
</table>
3118
+
</para>
3119
+
<para xmlns="http://docbook.org/ns/docbook">
3120
+
<table>
3121
+
<title><literal>"gcp"</literal> provider options</title>
3122
+
<tgroup cols="3">
3123
+
<thead>
3124
+
<row>
3125
+
<entry>Option</entry>
3126
+
<entry>Type</entry>
3127
+
<entry>Description</entry>
3128
+
</row>
3129
+
</thead>
3130
+
<tbody>
3131
+
<row>
3132
+
<entry>projectId</entry>
3133
+
<entry>string</entry>
3134
+
<entry>Required.</entry>
3135
+
</row>
3136
+
<row>
3137
+
<entry>location</entry>
3138
+
<entry>string</entry>
3139
+
<entry>Required.</entry>
3140
+
</row>
3141
+
<row>
3142
+
<entry>keyRing</entry>
3143
+
<entry>string</entry>
3144
+
<entry>Required.</entry>
3145
+
</row>
3146
+
<row>
3147
+
<entry>keyName</entry>
3148
+
<entry>string</entry>
3149
+
<entry>Required.</entry>
3150
+
</row>
3151
+
<row>
3152
+
<entry>keyVersion</entry>
3153
+
<entry>string</entry>
3154
+
<entry>Optional. A specific version of the named key. Defaults to using the key&apos;s primary version.</entry>
3155
+
</row>
3156
+
<row>
3157
+
<entry>endpoint</entry>
3158
+
<entry>string</entry>
3159
+
<entry>Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".</entry>
3160
+
</row>
3161
+
</tbody>
3162
+
</tgroup>
3163
+
</table>
3164
+
</para>
3165
+
<para xmlns="http://docbook.org/ns/docbook">
3166
+
<table>
3167
+
<title><literal>"kmip"</literal> provider options</title>
3168
+
<tgroup cols="3">
3169
+
<thead>
3170
+
<row>
3171
+
<entry>Option</entry>
3172
+
<entry>Type</entry>
3173
+
<entry>Description</entry>
3174
+
</row>
3175
+
</thead>
3176
+
<tbody>
3177
+
<row>
3178
+
<entry>keyId</entry>
3179
+
<entry>string</entry>
3180
+
<entry>Optional. Unique identifier to a 96-byte KMIP secret data managed object. If unspecified, the driver creates a random 96-byte KMIP secret data managed object.</entry>
3181
+
</row>
3182
+
<row>
3183
+
<entry>endpoint</entry>
3184
+
<entry>string</entry>
3185
+
<entry>Optional. Host with optional port.</entry>
3186
+
</row>
3187
+
</tbody>
3188
+
</tgroup>
3189
+
</table>
3190
+
</para>
3191
+
'>
3192
+
<!ENTITY mongodb.option.encryption.tlsOptions '
3193
+
<row xmlns="http://docbook.org/ns/docbook">
3194
+
<entry>tlsOptions</entry>
3195
+
<entry><type>array</type></entry>
3196
+
<entry>
3197
+
<para>
3198
+
A document containing the TLS configuration for one or more KMS providers. Supported providers include <literal>"aws"</literal>, <literal>"azure"</literal>, <literal>"gcp"</literal>, and <literal>"kmip"</literal>. All providers support the following options:
3199
+
</para>
3200
+
<programlisting role="javascript">
3201
+
<![CDATA[
3202
+
<provider>: {
3203
+
tlsCaFile: <optional string>,
3204
+
tlsCertificateKeyFile: <optional string>,
3205
+
tlsCertificateKeyFilePassword: <optional string>,
3206
+
tlsDisableOCSPEndpointCheck: <optional bool>
3207
+
}
3208
+
]]>
3209
+
</programlisting>
3210
+
</entry>
3211
+
</row>
3212
+
'>
2688
3213
<!ENTITY mongodb.option.maxCommitTimeMS '
2689
3214
<row xmlns="http://docbook.org/ns/docbook">
2690
3215
<entry>maxCommitTimeMS</entry>
...
...
@@ -2803,6 +3328,156 @@ local: {
2803
3328
</listitem>
2804
3329
</varlistentry>
2805
3330
'>
3331
+
<!ENTITY mongodb.parameter.encryptOpts '
3332
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3333
+
<term><parameter>options</parameter></term>
3334
+
<listitem>
3335
+
<para>
3336
+
<table>
3337
+
<title>Encryption options</title>
3338
+
<tgroup cols="3">
3339
+
<thead>
3340
+
<row>
3341
+
<entry>Option</entry>
3342
+
<entry>Type</entry>
3343
+
<entry>Description</entry>
3344
+
</row>
3345
+
</thead>
3346
+
<tbody>
3347
+
<row>
3348
+
<entry>algorithm</entry>
3349
+
<entry><type>string</type></entry>
3350
+
<entry>
3351
+
<para>
3352
+
The encryption algorithm to be used. This option is required.
3353
+
Specify one of the following
3354
+
<link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
3355
+
</para>
3356
+
<simplelist>
3357
+
<member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC</constant></member>
3358
+
<member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM</constant></member>
3359
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant></member>
3360
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED</constant></member>
3361
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW</constant></member>
3362
+
</simplelist>
3363
+
</entry>
3364
+
</row>
3365
+
<row>
3366
+
<entry>contentionFactor</entry>
3367
+
<entry><type>int</type></entry>
3368
+
<entry>
3369
+
<para>
3370
+
The contention factor for evaluating queries with indexed, encrypted
3371
+
payloads.
3372
+
</para>
3373
+
<para>
3374
+
This option only applies and may only be specified when
3375
+
<literal>algorithm</literal> is
3376
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
3377
+
or
3378
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW</constant>.
3379
+
</para>
3380
+
</entry>
3381
+
</row>
3382
+
<row>
3383
+
<entry>keyAltName</entry>
3384
+
<entry><type>string</type></entry>
3385
+
<entry>
3386
+
<para>
3387
+
Identifies a key vault collection document by
3388
+
<literal>keyAltName</literal>. This option is mutually exclusive
3389
+
with <literal>keyId</literal> and exactly one is required.
3390
+
</para>
3391
+
</entry>
3392
+
</row>
3393
+
<row>
3394
+
<entry>keyId</entry>
3395
+
<entry><classname>MongoDB\BSON\Binary</classname></entry>
3396
+
<entry>
3397
+
<para>
3398
+
Identifies a data key by <literal>_id</literal>. The value is a UUID
3399
+
(binary subtype 4). This option is mutually exclusive with
3400
+
<literal>keyAltName</literal> and exactly one is required.
3401
+
</para>
3402
+
</entry>
3403
+
</row>
3404
+
<row>
3405
+
<entry>queryType</entry>
3406
+
<entry><type>string</type></entry>
3407
+
<entry>
3408
+
<para>
3409
+
The query type for evaluating queries with indexed, encrypted
3410
+
payloads. Specify one of the following
3411
+
<link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
3412
+
</para>
3413
+
<simplelist>
3414
+
<member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY</constant></member>
3415
+
<member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW</constant></member>
3416
+
</simplelist>
3417
+
<para>This option only applies and may only be specified when
3418
+
<literal>algorithm</literal> is
3419
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
3420
+
or <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW</constant>.
3421
+
</para>
3422
+
</entry>
3423
+
</row>
3424
+
<row>
3425
+
<entry>rangeOpts</entry>
3426
+
<entry><type>array</type></entry>
3427
+
<entry>
3428
+
<para>
3429
+
Index options for a queryable encryption field supporting
3430
+
"rangePreview" queries. The options below must match the values set
3431
+
in the <literal>encryptedFields</literal> of the target collection.
3432
+
For double and decimal128 BSON field types, <literal>min</literal>,
3433
+
<literal>max</literal>, and <literal>precision</literal> must all be
3434
+
set, or all be unset.
3435
+
</para>
3436
+
<para>
3437
+
<table>
3438
+
<title>Range index options</title>
3439
+
<tgroup cols="3">
3440
+
<thead>
3441
+
<row>
3442
+
<entry>Option</entry>
3443
+
<entry>Type</entry>
3444
+
<entry>Description</entry>
3445
+
</row>
3446
+
</thead>
3447
+
<tbody>
3448
+
<row>
3449
+
<entry>min</entry>
3450
+
<entry><type>mixed</type></entry>
3451
+
<entry>Required if <literal>precision</literal> is set.</entry>
3452
+
</row>
3453
+
<row>
3454
+
<entry>max</entry>
3455
+
<entry><type>mixed</type></entry>
3456
+
<entry>Required if <literal>precision</literal> is set.</entry>
3457
+
</row>
3458
+
<row>
3459
+
<entry>sparsity</entry>
3460
+
<entry><type>int</type></entry>
3461
+
<entry>Required.</entry>
3462
+
</row>
3463
+
<row>
3464
+
<entry>precision</entry>
3465
+
<entry><type>int</type></entry>
3466
+
<entry>Optional. May only be set for double or decimal128 BSON field types.</entry>
3467
+
</row>
3468
+
</tbody>
3469
+
</tgroup>
3470
+
</table>
3471
+
</para>
3472
+
</entry>
3473
+
</row>
3474
+
</tbody>
3475
+
</tgroup>
3476
+
</table>
3477
+
</para>
3478
+
</listitem>
3479
+
</varlistentry>
3480
+
'>
2806
3481
<!ENTITY mongodb.parameter.query '
2807
3482
<varlistentry xmlns="http://docbook.org/ns/docbook">
2808
3483
<term><parameter>query</parameter> (<classname>MongoDB\Driver\Query</classname>)</term>
...
...
@@ -2850,6 +3525,9 @@ local: {
2850
3525
<!ENTITY mongodb.throws.connection '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\ConnectionException</classname> if connection to the server fails (for reasons other than authentication).</member>'>
2851
3526
<!ENTITY mongodb.throws.bson.unexpected '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname> if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected <link xlink:href="&url.mongodb.libbson;" xmlns:xlink="http://www.w3.org/1999/xlink">libbson</link> error.</member>'>
2852
3527

3528
+
<!-- Not used in EN anymore -->
3529
+
<!ENTITY mongodb.note.queryable-encryption-preview ''>
3530
+

2853
3531
<!ENTITY mongodb.note.decimal128 '
2854
3532
<note xmlns="http://docbook.org/ns/docbook">
2855
3533
<simpara>
...
...
@@ -2918,6 +3596,18 @@ local: {
2918
3596
</note>
2919
3597
'>
2920
3598

3599
+
<!ENTITY mongodb.warning.duplicate-keys '
3600
+
<warning xmlns="http://docbook.org/ns/docbook">
3601
+
<simpara>
3602
+
BSON documents can technically contain duplicate keys because documents are
3603
+
stored as a list of key-value pairs; however, applications should refrain
3604
+
from generating documents with duplicate keys as server and driver behavior
3605
+
may be undefined. Since PHP objects and arrays cannot have duplicate keys,
3606
+
data could also be lost when decoding a BSON document with duplicate keys.
3607
+
</simpara>
3608
+
</warning>
3609
+
'>
3610
+

2921
3611
<!-- Radius -->
2922
3612
<!ENTITY radius.request.required '<note xmlns="http://docbook.org/ns/docbook"><para>A request must be created via <function>radius_create_request</function> before this function can be called.</para></note>'>
2923
3613
<!ENTITY radius.parameter.attribute-type '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>type</parameter></term><listitem><para>The attribute type.</para></listitem></varlistentry>'>
...
...
@@ -2928,7 +3618,7 @@ local: {
2928
3618

2929
3619
<!-- posix snippets -->
2930
3620
<!ENTITY posix.parameter.fd '<varlistentry xmlns="http://docbook.org/ns/docbook">
2931
-
<term><parameter>fd</parameter></term>
3621
+
<term><parameter>file_descriptor</parameter></term>
2932
3622
<listitem>
2933
3623
<para>
2934
3624
The file descriptor, which is expected to be either a file
...
...
@@ -2936,9 +3626,6 @@ local: {
2936
3626
will be assumed to be a file descriptor that can be passed directly to
2937
3627
the underlying system call.
2938
3628
</para>
2939
-
<para>
2940
-
In almost all cases, you will want to provide a file <type>resource</type>.
2941
-
</para>
2942
3629
</listitem>
2943
3630
</varlistentry>'>
2944
3631

...
...
@@ -3052,16 +3739,20 @@ local: {
3052
3739
<formalpara>
3053
3740
<title>Width</title>
3054
3741
<para>
3055
-
An integer that says how many characters (minimum)
3056
-
this conversion should result in.
3742
+
Either an integer that says how many characters (minimum)
3743
+
this conversion should result in, or <literal>*</literal>.
3744
+
If <literal>*</literal> is used, then the width is supplied
3745
+
as an additional integer value preceding the one formatted
3746
+
by the specifier.
3057
3747
</para>
3058
3748
</formalpara>
3059
3749

3060
3750
<formalpara>
3061
3751
<title>Precision</title>
3062
3752
<para>
3063
-
A period <literal>.</literal> followed by an integer
3064
-
who&apos;s meaning depends on the specifier:
3753
+
A period <literal>.</literal> optionally followed by
3754
+
either an integer or <literal>*</literal>,
3755
+
whose meaning depends on the specifier:
3065
3756
<itemizedlist>
3066
3757
<listitem>
3067
3758
<simpara>
...
...
@@ -3089,19 +3780,14 @@ local: {
3089
3780
<note>
3090
3781
<simpara>
3091
3782
If the period is specified without an explicit value for precision,
3092
-
0 is assumed.
3783
+
0 is assumed. If <literal>*</literal> is used, the precision is
3784
+
supplied as an additional integer value preceding the one formatted
3785
+
by the specifier.
3093
3786
</simpara>
3094
3787
</note>
3095
3788
</para>
3096
3789
</formalpara>
3097
3790

3098
-
<note>
3099
-
<simpara>
3100
-
Attempting to use a position specifier greater than
3101
-
<constant>PHP_INT_MAX</constant> will generate warnings.
3102
-
</simpara>
3103
-
</note>
3104
-

3105
3791
<para>
3106
3792
<table>
3107
3793
<title>Specifiers</title>
...
...
@@ -3305,6 +3991,44 @@ local: {
3305
3991
</varlistentry>
3306
3992
'>
3307
3993

3994
+
<!ENTITY strings.scanf.parameter.format '
3995
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3996
+
<term><parameter>format</parameter></term>
3997
+
<listitem>
3998
+
<para>
3999
+
The interpreted format for <parameter>string</parameter>, which is
4000
+
described in the documentation for <function>sprintf</function> with
4001
+
following differences:
4002
+
<simplelist>
4003
+
<member>
4004
+
Function is not locale-aware.
4005
+
</member>
4006
+
<member>
4007
+
<literal>F</literal>, <literal>g</literal>, <literal>G</literal> and
4008
+
<literal>b</literal> are not supported.
4009
+
</member>
4010
+
<member>
4011
+
<literal>D</literal> stands for decimal number.
4012
+
</member>
4013
+
<member>
4014
+
<literal>i</literal> stands for integer with base detection.
4015
+
</member>
4016
+
<member>
4017
+
<literal>n</literal> stands for number of characters processed so far.
4018
+
</member>
4019
+
<member>
4020
+
<literal>s</literal> stops reading at any whitespace character.
4021
+
</member>
4022
+
<member>
4023
+
<literal>*</literal> instead of <literal>argnum$</literal> suppresses
4024
+
the assignment of this conversion specification.
4025
+
</member>
4026
+
</simplelist>
4027
+
</para>
4028
+
</listitem>
4029
+
</varlistentry>
4030
+
'>
4031
+

3308
4032
<!ENTITY strings.parameter.needle.non-string '
3309
4033
<para xmlns="http://docbook.org/ns/docbook">
3310
4034
Prior to PHP 8.0.0, if <parameter>needle</parameter> is not a string, it is converted
...
...
@@ -3316,6 +4040,13 @@ local: {
3316
4040
</para>
3317
4041
'>
3318
4042

4043
+
<!ENTITY strings.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
4044
+
<entry>8.0.0</entry>
4045
+
<entry>
4046
+
<parameter>needle</parameter> now accepts an empty string.
4047
+
</entry>
4048
+
</row>'>
4049
+

3319
4050
<!ENTITY strings.changelog.encoding '
3320
4051
<row xmlns="http://docbook.org/ns/docbook">
3321
4052
<entry>5.6.0</entry>
...
...
@@ -3328,6 +4059,163 @@ local: {
3328
4059
</row>
3329
4060
'>
3330
4061

4062
+
<!ENTITY strings.changelog.ascii-case-conversion '
4063
+
<row xmlns="http://docbook.org/ns/docbook">
4064
+
<entry>8.2.0</entry>
4065
+
<entry>
4066
+
Case conversion no longer depends on the locale set with
4067
+
<function>setlocale</function>. Only ASCII characters will be converted.
4068
+
</entry>
4069
+
</row>
4070
+
'>
4071
+

4072
+
<!ENTITY strings.changelog.ascii-case-folding '
4073
+
<row xmlns="http://docbook.org/ns/docbook">
4074
+
<entry>8.2.0</entry>
4075
+
<entry>
4076
+
Case folding no longer depends on the locale set with
4077
+
<function>setlocale</function>. Only ASCII case folding will be done.
4078
+
Non-ASCII bytes will be compared by their byte value.
4079
+
</entry>
4080
+
</row>
4081
+
'>
4082
+

4083
+
<!ENTITY strings.changelog.sprintf '
4084
+
<informaltable xmlns="http://docbook.org/ns/docbook">
4085
+
<tgroup cols="2">
4086
+
<thead>
4087
+
<row>
4088
+
<entry>&Version;</entry>
4089
+
<entry>&Description;</entry>
4090
+
</row>
4091
+
</thead>
4092
+
<tbody>
4093
+
<row>
4094
+
<entry>8.0.0</entry>
4095
+
<entry>
4096
+
This function no longer returns &false; on failure.
4097
+
</entry>
4098
+
</row>
4099
+
<row>
4100
+
<entry>8.0.0</entry>
4101
+
<entry>
4102
+
Throw a <classname>ValueError</classname> if the number of arguments is zero;
4103
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4104
+
</entry>
4105
+
</row>
4106
+
<row>
4107
+
<entry>8.0.0</entry>
4108
+
<entry>
4109
+
Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4110
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4111
+
</entry>
4112
+
</row>
4113
+
<row>
4114
+
<entry>8.0.0</entry>
4115
+
<entry>
4116
+
Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4117
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4118
+
</entry>
4119
+
</row>
4120
+
<row>
4121
+
<entry>8.0.0</entry>
4122
+
<entry>
4123
+
Throw a <classname>ArgumentCountError</classname> when less arguments are given than required;
4124
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4125
+
</entry>
4126
+
</row>
4127
+
</tbody>
4128
+
</tgroup>
4129
+
</informaltable>
4130
+
'>
4131
+

4132
+
<!ENTITY strings.changelog.vsprintf '
4133
+
<informaltable xmlns="http://docbook.org/ns/docbook">
4134
+
<tgroup cols="2">
4135
+
<thead>
4136
+
<row>
4137
+
<entry>&Version;</entry>
4138
+
<entry>&Description;</entry>
4139
+
</row>
4140
+
</thead>
4141
+
<tbody>
4142
+
<row>
4143
+
<entry>8.0.0</entry>
4144
+
<entry>
4145
+
This function no longer returns &false; on failure.
4146
+
</entry>
4147
+
</row>
4148
+
<row>
4149
+
<entry>8.0.0</entry>
4150
+
<entry>
4151
+
Throw a <classname>ValueError</classname> if the number of arguments is zero;
4152
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4153
+
</entry>
4154
+
</row>
4155
+
<row>
4156
+
<entry>8.0.0</entry>
4157
+
<entry>
4158
+
Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4159
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4160
+
</entry>
4161
+
</row>
4162
+
<row>
4163
+
<entry>8.0.0</entry>
4164
+
<entry>
4165
+
Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4166
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4167
+
</entry>
4168
+
</row>
4169
+
<row>
4170
+
<entry>8.0.0</entry>
4171
+
<entry>
4172
+
Throw a <classname>ValueError</classname> when less arguments are given than required;
4173
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4174
+
</entry>
4175
+
</row>
4176
+
</tbody>
4177
+
</tgroup>
4178
+
</informaltable>
4179
+
'>
4180
+

4181
+
<!ENTITY strings.errors.sprintf '
4182
+
<para xmlns="http://docbook.org/ns/docbook">
4183
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
4184
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4185
+
</para>
4186
+
<para xmlns="http://docbook.org/ns/docbook">
4187
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4188
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4189
+
</para>
4190
+
<para xmlns="http://docbook.org/ns/docbook">
4191
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4192
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4193
+
</para>
4194
+
<para xmlns="http://docbook.org/ns/docbook">
4195
+
As of PHP 8.0.0, a <classname>ArgumentCountError</classname> is thrown when less arguments are given than required.
4196
+
Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
4197
+
</para>
4198
+
'>
4199
+

4200
+
<!ENTITY strings.errors.vsprintf '
4201
+
<para xmlns="http://docbook.org/ns/docbook">
4202
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
4203
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4204
+
</para>
4205
+
<para xmlns="http://docbook.org/ns/docbook">
4206
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4207
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4208
+
</para>
4209
+
<para xmlns="http://docbook.org/ns/docbook">
4210
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4211
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4212
+
</para>
4213
+
<para xmlns="http://docbook.org/ns/docbook">
4214
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown when less arguments are given than required.
4215
+
Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
4216
+
</para>
4217
+
'>
4218
+

3331
4219
<!-- filter snippets -->
3332
4220
<!ENTITY filter.param.filter '
3333
4221
<varlistentry xmlns="http://docbook.org/ns/docbook">
...
...
@@ -3350,34 +4238,65 @@ local: {
3350
4238
<!-- csprng snippets -->
3351
4239
<!ENTITY csprng.sources '
3352
4240
<para xmlns="http://docbook.org/ns/docbook">
3353
-
The sources of randomness used for this function are as follows:
4241
+
The sources of randomness in the order of priority are as follows:
3354
4242
</para>
3355
4243
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3356
4244
<listitem>
3357
-
<simpara>
3358
-
On Windows,
3359
-
<link xlink:href="&url.csprng.crypt-gen-random;"><function>CryptGenRandom</function></link>
3360
-
will always be used. As of PHP 7.2.0, the
3361
-
<link xlink:href="&url.csprng.cng-api;">CNG-API</link>
3362
-
will always be used instead.
3363
-
</simpara>
4245
+
<para>
4246
+
Linux: <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4247
+
</para>
3364
4248
</listitem>
3365
4249
<listitem>
3366
-
<simpara>
3367
-
On Linux, the
3368
-
<link xlink:href="&url.csprng.get-random-2;">getrandom(2)</link>
3369
-
syscall will be used if available.
3370
-
</simpara>
4250
+
<para>
4251
+
FreeBSD &gt;= 12 (PHP &gt;= 7.3): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4252
+
</para>
4253
+
</listitem>
4254
+
<listitem>
4255
+
<para>
4256
+
Windows (PHP &gt;= 7.2): <link xlink:href="&url.csprng.cng-api;">CNG-API</link>
4257
+
</para>
4258
+
<para>
4259
+
Windows: <link xlink:href="&url.csprng.crypt-gen-random;">CryptGenRandom</link>
4260
+
</para>
4261
+
</listitem>
4262
+
<listitem>
4263
+
<para>
4264
+
macOS (PHP &gt;= 8.2; &gt;= 8.1.9; &gt;= 8.0.22 if CCRandomGenerateBytes is available at compile time): CCRandomGenerateBytes()
4265
+
</para>
4266
+
<para>
4267
+
macOS (PHP &gt;= 8.1; &gt;= 8.0.2): arc4random_buf(), <filename>/dev/urandom</filename>
4268
+
</para>
4269
+
</listitem>
4270
+
<listitem>
4271
+
<para>
4272
+
NetBSD &gt;= 7 (PHP &gt;= 7.1; &gt;= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
4273
+
</para>
4274
+
</listitem>
4275
+
<listitem>
4276
+
<para>
4277
+
OpenBSD &gt;= 5.5 (PHP &gt;= 7.1; &gt;= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
4278
+
</para>
4279
+
</listitem>
4280
+
<listitem>
4281
+
<para>
4282
+
DragonflyBSD (PHP &gt;= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4283
+
</para>
4284
+
</listitem>
4285
+
<listitem>
4286
+
<para>
4287
+
Solaris (PHP &gt;= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4288
+
</para>
3371
4289
</listitem>
3372
4290
<listitem>
3373
4291
<simpara>
3374
-
On other platforms, <filename>/dev/urandom</filename> will be used.
4292
+
Any combination of operating system and PHP version not previously mentioned: <filename>/dev/urandom</filename>
3375
4293
</simpara>
3376
4294
</listitem>
3377
4295
<listitem>
3378
4296
<simpara>
3379
-
If none of the aforementioned sources are available, then an
3380
-
<classname>Exception</classname> will be thrown.
4297
+
If none of the sources are available or they all fail to generate
4298
+
randomness, then a <classname>Random\RandomException</classname>
4299
+
will be thrown.
3381
4300
</simpara>
3382
4301
</listitem>
3383
4302
</itemizedlist>
...
...
@@ -3386,13 +4305,7 @@ local: {
3386
4305
<listitem xmlns="http://docbook.org/ns/docbook">
3387
4306
<simpara>
3388
4307
If an appropriate source of randomness cannot be found,
3389
-
an <classname>Exception</classname> will be thrown.
3390
-
</simpara>
3391
-
</listitem>
3392
-
<listitem xmlns="http://docbook.org/ns/docbook">
3393
-
<simpara>
3394
-
If invalid parameters are given, a <classname>TypeError</classname>
3395
-
will be thrown.
4308
+
a <classname>Random\RandomException</classname> will be thrown.
3396
4309
</simpara>
3397
4310
</listitem>
3398
4311
'>
...
...
@@ -3406,6 +4319,15 @@ local: {
3406
4319
</note>
3407
4320
'>
3408
4321

4322
+
<!-- Random snippets -->
4323
+
<!ENTITY random.engineErrors '
4324
+
<listitem xmlns="http://docbook.org/ns/docbook">
4325
+
<simpara>
4326
+
Any <classname>Throwable</classname>s thrown by the <methodname>Random\Engine::generate</methodname> method
4327
+
of the underlying <link linkend="random-randomizer.props.engine"><literal>Random\Randomizer::$engine</literal></link>.
4328
+
</simpara>
4329
+
</listitem>
4330
+
'>
3409
4331

3410
4332
<!-- UOPZ snippets -->
3411
4333

...
...
@@ -3414,12 +4336,42 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
3414
4336
<emphasis>REMOVED</emphasis> in PECL uopz 5.0.0.</simpara></warning>'>
3415
4337

3416
4338
<!-- XML snippets -->
4339
+
<!ENTITY xml.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
4340
+
<term><parameter>parser</parameter></term>
4341
+
<listitem>
4342
+
<para>
4343
+
The XML parser.
4344
+
</para>
4345
+
</listitem>
4346
+
</varlistentry>'>
4347
+

4348
+
<!ENTITY xml.handler.description '<para xmlns="http://docbook.org/ns/docbook">
4349
+
If &null; or an empty string is passed, the handler is reset to its default state.
4350
+
</para>
4351
+
<para xmlns="http://docbook.org/ns/docbook">
4352
+
If <parameter>handler</parameter> is a <type>callable</type>,
4353
+
the callable is set as the handler.
4354
+
</para>
4355
+
<para xmlns="http://docbook.org/ns/docbook">
4356
+
If <parameter>handler</parameter> is a <type>string</type>,
4357
+
it can be the name of a method of an object set with
4358
+
<function>xml_set_object</function>.
4359
+
</para>'>
4360
+

4361
+
<!ENTITY xml.handler.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
4362
+
<term><parameter>parser</parameter></term>
4363
+
<listitem>
4364
+
<simpara>
4365
+
The XML parser calling the handler.
4366
+
</simpara>
4367
+
</listitem>
4368
+
</varlistentry>'>
3417
4369

3418
4370
<!ENTITY xml.changelog.parser-param '<row xmlns="http://docbook.org/ns/docbook">
3419
4371
<entry>8.0.0</entry>
3420
4372
<entry>
3421
4373
<parameter>parser</parameter> expects an <classname>XMLParser</classname>
3422
-
instance now; previously, a <type>resource</type> was expected.
4374
+
instance now; previously, a valid <literal>xml</literal> <type>resource</type> was expected.
3423
4375
</entry>
3424
4376
</row>'>
3425
4377

3426
4378