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>'>
...
...
@@ -49,6 +74,11 @@ will cause PHP to hang until the execution of the program ends.</para></note>'>
49
74
will first start cmd.exe to launch the command. If you want to start an external program without starting cmd.exe
50
75
use <function>proc_open</function> with the <parameter>bypass_shell</parameter> option set.</para></note>'>
51
76

77
+
<!ENTITY note.extractto-windows '<note xmlns="http://docbook.org/ns/docbook"><para>Windows NTFS file systems
78
+
do not support some characters in filenames, namely <literal>&lt;|&gt;*?":</literal>. Filenames with a trailing dot
79
+
are not supported either. Contrary to some extraction tools, this method does not replace these characters with
80
+
an underscore, but instead fails to extract such files.</para></note>'>
81
+

52
82
<!ENTITY note.func-callback '<note xmlns="http://docbook.org/ns/docbook"><simpara>Instead of a function name, an
53
83
array containing an object reference and a method name can also be
54
84
supplied.</simpara></note>'>
...
...
@@ -66,6 +96,13 @@ current scope to determine parameter details, it cannot be used as a
66
96
function parameter in versions prior to 5.3.0. If this value must be passed, the results should be assigned
67
97
to a variable, and that variable should be passed.</para></note>'>
68
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
+

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

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

189
+
<!ENTITY note.resource-migration-8.0-dead-function '<note xmlns="http://docbook.org/ns/docbook">
190
+
<para>
191
+
This function has no effect. Prior to PHP 8.0.0, this function was used to close the resource.
192
+
</para>
193
+
</note>
194
+
'>
195
+

145
196
<!-- Tips -->
146
197

147
198
<!ENTITY tip.fopen-wrapper '<tip xmlns="http://docbook.org/ns/docbook"><simpara>A URL can be used as a
...
...
@@ -221,6 +272,12 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
221
272
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0. Relying on this function
222
273
is highly discouraged.</simpara></warning>'>
223
274

275
+
<!ENTITY warn.deprecated.function-7-0-0.removed-8-0-0 '<warning
276
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
277
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.0.0 and
278
+
<emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
279
+
is highly discouraged.</simpara></warning>'>
280
+

224
281
<!ENTITY warn.deprecated.function-7-1-0.removed-7-2-0 '<warning
225
282
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
226
283
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0 and
...
...
@@ -277,11 +334,35 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
277
334
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
278
335
is highly discouraged.</simpara></warning>'>
279
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
+

280
341
<!ENTITY warn.deprecated.function-8-0-0 '<warning
281
342
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
282
343
<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0. Relying on this function
283
344
is highly discouraged.</simpara></warning>'>
284
345

346
+
<!ENTITY warn.deprecated.function-8-1-0 '<warning
347
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
348
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
349
+
is highly discouraged.</simpara></warning>'>
350
+

351
+
<!ENTITY warn.deprecated.function-8-2-0 '<warning
352
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
353
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.2.0. Relying on this function
354
+
is highly discouraged.</simpara></warning>'>
355
+

356
+
<!ENTITY warn.deprecated.feature-8-3-0 '<warning
357
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
358
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this feature
359
+
is highly discouraged.</simpara></warning>'>
360
+

361
+
<!ENTITY warn.deprecated.function-8-3-0 '<warning
362
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
363
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this function
364
+
is highly discouraged.</simpara></warning>'>
365
+

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

...
...
@@ -489,6 +570,15 @@ currently not documented; only its argument list is available.
489
570
</para>
490
571
'>
491
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
+

492
582
<!-- Misc -->
493
583

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

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

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

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

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

550
666
<!ENTITY sort.flags.parameter '<varlistentry xmlns="http://docbook.org/ns/docbook">
...
...
@@ -594,6 +710,44 @@ use.</simpara></note>'>
594
710
</varlistentry>
595
711
'>
596
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
+

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

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

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

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

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

643
799
<!-- Returns -->
644
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
+

645
808
<!ENTITY return.falseforfailure ' or &false; on failure'>
646
809
<!ENTITY return.falseforfailure.style.procedural '&style.procedural; returns &false; on failure.'>
647
810

...
...
@@ -663,6 +826,42 @@ information. Use <link linkend="language.operators.comparison">the ===
663
826
operator</link> for testing the return value of this
664
827
function.</simpara></warning>'>
665
828

829
+
<!-- Standard -->
830
+
<!ENTITY standard.changelog.calling-on-objects '<row xmlns="http://docbook.org/ns/docbook">
831
+
<entry>8.1.0</entry>
832
+
<entry>
833
+
Calling this function on &object;s is deprecated.
834
+
Either convert the &object; to an &array; using <function>get_mangled_object_vars</function> first, or use the methods
835
+
provided by a class that implements <interfacename>Iterator</interfacename>, such as <classname>ArrayIterator</classname>, instead.
836
+
</entry>
837
+
</row>
838
+
<row xmlns="http://docbook.org/ns/docbook">
839
+
<entry>7.4.0</entry>
840
+
<entry>
841
+
Instances of <link xmlns="http://docbook.org/ns/docbook" linkend="book.spl">SPL</link> classes are now treated like empty objects that have no properties instead of calling the <interfacename>Iterator</interfacename> method with the same name as this function.
842
+
</entry>
843
+
</row>
844
+
'>
845
+

846
+
<!ENTITY standard.changelog.binary-safe-string-comparison '<row xmlns="http://docbook.org/ns/docbook">
847
+
<entry>8.2.0</entry>
848
+
<entry>
849
+
This function now returns <literal>-1</literal> or <literal>1</literal>,
850
+
where it previously returned a negative or positive number.
851
+
</entry>
852
+
</row>
853
+
'>
854
+

855
+
<!-- FileInfo -->
856
+
<!ENTITY fileinfo.parameters.finfo '<para xmlns="http://docbook.org/ns/docbook">An <classname>finfo</classname> instance, returned by <function>finfo_open</function>.</para>'>
857
+
<!ENTITY fileinfo.changelog.finfo-object '<row xmlns="http://docbook.org/ns/docbook">
858
+
<entry>8.1.0</entry>
859
+
<entry>
860
+
The <parameter>finfo</parameter> parameter expects an <classname>finfo</classname>
861
+
instance now; previously, a &resource; was expected.
862
+
</entry>
863
+
</row>'>
864
+

666
865
<!-- OpenSSL -->
667
866
<!ENTITY openssl.param.x509 '<varlistentry xmlns="http://docbook.org/ns/docbook">
668
867
<term><parameter>x509</parameter></term>
...
...
@@ -704,15 +903,22 @@ PHP is compiled with freetype support (<option role="configure">--with-freetype-
704
903

705
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>'>
706
905

707
-
<!ENTITY gd.image.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
708
-
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,
709
908
such as <function>imagecreatetruecolor</function>.</para></listitem></varlistentry>'>
710
909

711
-
<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
712
-
font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in
713
-
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or any of your
714
-
own font identifiers registered with <function>imageloadfont</function>.
715
-
</para></listitem></varlistentry>'>
910
+
<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
911
+
<parameter>font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in
912
+
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or <classname>GdFont</classname> instance,
913
+
returned by <function>imageloadfont</function>.</para></listitem></varlistentry>'>
914
+

915
+
<!ENTITY gd.changelog.gdfont-instance '<row xmlns="http://docbook.org/ns/docbook">
916
+
<entry>8.1.0</entry>
917
+
<entry>
918
+
The <parameter>font</parameter> parameter now accepts both an <classname>GdFont</classname> instance
919
+
and an &integer;; previously only &integer; was accepted.
920
+
</entry>
921
+
</row>'>
716
922

717
923
<!ENTITY gd.ttf.fontfile "
718
924
<varlistentry xmlns='http://docbook.org/ns/docbook'>
...
...
@@ -850,14 +1056,14 @@ purposes.</simpara></warning>'>
850
1056
<entry>8.0.0</entry>
851
1057
<entry>
852
1058
<parameter>image</parameter> expects a <classname>GdImage</classname>
853
-
instance now; previously, a <type>resource</type> was expected.
1059
+
instance now; previously, a valid <literal>gd</literal> <type>resource</type> was expected.
854
1060
</entry>
855
1061
</row>'>
856
1062

857
1063
<!-- DBM notes -->
858
1064

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

863
1069
<!-- JSON notes -->
...
...
@@ -979,8 +1185,20 @@ returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
979
1185

980
1186
<!-- IMAP notes -->
981
1187

982
-
<!ENTITY imap.imap-stream.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
983
-
imap</parameter></term><listitem><para>An IMAP stream returned by
1188
+
<!ENTITY imap.changelog.imap-param '<row xmlns="http://docbook.org/ns/docbook">
1189
+
<entry>8.1.0</entry>
1190
+
<entry>
1191
+
The <parameter>imap</parameter> parameter expects an <classname>IMAP\Connection</classname>
1192
+
instance now; previously, a valid <literal>imap</literal> &resource; was expected.
1193
+
</entry>
1194
+
</row>'>
1195
+

1196
+
<!ENTITY imap.imap-parameter.imap '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1197
+
<parameter>imap</parameter></term><listitem><para>An <classname>IMAP\Connection</classname> instance.</para></listitem></varlistentry>'>
1198
+

1199
+
<!-- Deprecated -->
1200
+
<!ENTITY imap.imap-stream.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1201
+
<parameter>imap</parameter></term><listitem><para>An IMAP stream returned by
984
1202
<function>imap_open</function>.</para></listitem></varlistentry>'>
985
1203

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

1004
1222
<!-- intl notes -->
1005
1223

1224
+
<!ENTITY intl.parameter.intl-calendar '<para xmlns="http://docbook.org/ns/docbook">An <classname>IntlCalendar</classname> instance.</para>'>
1225
+

1226
+
<!ENTITY intl.error.intl-calendar '<para xmlns="http://docbook.org/ns/docbook">On failure &false; is also returned. To detect error conditions use <function>intl_get_error_code</function>, or set up Intl to throw <link linkend="ini.intl.use-exceptions">exceptions</link>.</para>'>
1227
+

1006
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>'>
1007
1229

1008
-
<!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>'>
1009
1231

1010
1232
<!ENTITY intl.codepoint.example 'Testing different code points'>
1011
1233

...
...
@@ -1017,9 +1239,11 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1017
1239

1018
1240
<!-- LDAP notes -->
1019
1241

1020
-
<!ENTITY ldap.parameter.ldap 'An LDAP resource, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_connect</function>.'>
1242
+
<!ENTITY ldap.parameter.ldap 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\Connection</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_connect</function>.'>
1243
+

1244
+
<!ENTITY ldap.parameter.result 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_list</function> or <function xmlns="http://docbook.org/ns/docbook">ldap_search</function>.'>
1021
1245

1022
-
<!ENTITY ldap.parameter.result 'An LDAP result resource, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_list</function> or <function xmlns="http://docbook.org/ns/docbook">ldap_search</function>.'>
1246
+
<!ENTITY ldap.parameter.entry 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\ResultEntry</classname> instance.'>
1023
1247

1024
1248
<!ENTITY ldap.warn.control-paged '<warning xmlns="http://docbook.org/ns/docbook">
1025
1249
<simpara>
...
...
@@ -1036,6 +1260,56 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1036
1260
</entry>
1037
1261
</row>'>
1038
1262

1263
+
<!ENTITY ldap.changelog.ldap-object '<row xmlns="http://docbook.org/ns/docbook">
1264
+
<entry>8.1.0</entry>
1265
+
<entry>
1266
+
The <parameter>ldap</parameter> parameter expects an <classname>LDAP\Connection</classname>
1267
+
instance now; previously, a valid <literal>ldap link</literal> &resource; was expected.
1268
+
</entry>
1269
+
</row>'>
1270
+

1271
+
<!ENTITY ldap.changelog.entry-object '<row xmlns="http://docbook.org/ns/docbook">
1272
+
<entry>8.1.0</entry>
1273
+
<entry>
1274
+
The <parameter>entry</parameter> parameter expects an <classname>LDAP\ResultEntry</classname>
1275
+
instance now; previously, a valid <literal>ldap result entry</literal> &resource; was expected.
1276
+
</entry>
1277
+
</row>'>
1278
+

1279
+
<!ENTITY ldap.changelog.result-object '<row xmlns="http://docbook.org/ns/docbook">
1280
+
<entry>8.1.0</entry>
1281
+
<entry>
1282
+
The <parameter>result</parameter> parameter expects an <classname>LDAP\Result</classname>
1283
+
instance now; previously, a valid <literal>ldap result</literal> &resource; was expected.
1284
+
</entry>
1285
+
</row>'>
1286
+

1287
+
<!ENTITY ldap.changelog.return-result-object '<row xmlns="http://docbook.org/ns/docbook">
1288
+
<entry>8.1.0</entry>
1289
+
<entry>
1290
+
Returns an <classname>LDAP\Result</classname> instance now;
1291
+
previously, a &resource; was returned.
1292
+
</entry>
1293
+
</row>'>
1294
+

1295
+
<!ENTITY ldap.changelog.return-result-entry-object '<row xmlns="http://docbook.org/ns/docbook">
1296
+
<entry>8.1.0</entry>
1297
+
<entry>
1298
+
Returns an <classname>LDAP\ResultEntry</classname> instance now;
1299
+
previously, a &resource; was returned.
1300
+
</entry>
1301
+
</row>'>
1302
+

1303
+
<!ENTITY ldap.return-result 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance,&return.falseforfailure;.'>
1304
+
<!ENTITY ldap.return-result-array 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance, an array of <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instances,&return.falseforfailure;.'>
1305
+

1306
+
<!ENTITY ldap.return-result-array-info '<para xmlns="http://docbook.org/ns/docbook">It is also possible to perform parallel searches. In this case, the first argument should be an array of
1307
+
<classname>LDAP\Connection</classname> instances, rather than a single one.
1308
+
If the searches should not all use the same base DN and filter, an array of base DNs and/or an array of filters can be passed as arguments instead.
1309
+
These arrays must be of the same size as the <classname>LDAP\Connection</classname> instances array,
1310
+
since the first entries of the arrays are used for one search, the second entries are used for another, and so on.
1311
+
When doing parallel searches an array of <classname>LDAP\Result</classname> instances is returned, except in case of error, when the return value will be &false;.</para>'>
1312
+

1039
1313
<!-- mbstring notes -->
1040
1314

1041
1315
<!ENTITY note.mbstring.encoding.internal '<note xmlns="http://docbook.org/ns/docbook"><para>The internal encoding or the
...
...
@@ -1059,6 +1333,13 @@ encoding value will be used.</para>'>
1059
1333
</entry>
1060
1334
</row>'>
1061
1335

1336
+
<!ENTITY mbstring.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
1337
+
<entry>8.0.0</entry>
1338
+
<entry>
1339
+
<parameter>needle</parameter> now accepts an empty string.
1340
+
</entry>
1341
+
</row>'>
1342
+

1062
1343
<!-- mcrypt notes -->
1063
1344

1064
1345
<!ENTITY mcrypt.parameter.cipher '<para xmlns="http://docbook.org/ns/docbook">One of the <constant>MCRYPT_ciphername</constant> constants, or the name of the algorithm as string.</para>'>
...
...
@@ -1071,12 +1352,20 @@ encoding value will be used.</para>'>
1071
1352

1072
1353
<!-- MCVE notes -->
1073
1354

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

1078
1359
<!-- memcached notes -->
1079
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
+

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

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

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

1093
1395
<!-- password notes -->
1094
1396

1095
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.'>
...
...
@@ -1100,6 +1402,36 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
1100
1402

1101
1403
<!ENTITY password.parameter.password 'The user&apos;s password.'>
1102
1404

1405
+
<!-- pspell notes -->
1406
+

1407
+
<!ENTITY pspell.changelog.pspell-dictionary '<row xmlns="http://docbook.org/ns/docbook">
1408
+
<entry>8.1.0</entry>
1409
+
<entry>
1410
+
The <parameter>dictionary</parameter> parameter expects an <classname>PSpell\Dictionary</classname>
1411
+
instance now; previously, a &resource; was expected.
1412
+
</entry>
1413
+
</row>'>
1414
+

1415
+
<!ENTITY pspell.changelog.pspell-config '<row xmlns="http://docbook.org/ns/docbook">
1416
+
<entry>8.1.0</entry>
1417
+
<entry>
1418
+
The <parameter>config</parameter> parameter expects an <classname>PSpell\Config</classname>
1419
+
instance now; previously, a &resource; was expected.
1420
+
</entry>
1421
+
</row>'>
1422
+

1423
+
<!ENTITY pspell.parameter.pspell-dictionary '<para xmlns="http://docbook.org/ns/docbook">An <classname>PSpell\Dictionary</classname> instance.</para>'>
1424
+

1425
+
<!ENTITY pspell.parameter.pspell-config '<para xmlns="http://docbook.org/ns/docbook">An <classname>PSpell\Config</classname> instance.</para>'>
1426
+

1427
+
<!-- RNP -->
1428
+

1429
+
<!ENTITY rnp.parameter.ffi-description 'The FFI object returned by rnp_ffi_create.'>
1430
+

1431
+
<!ENTITY rnp.parameter.key-format 'The key format of the data (GPG, KBX, G10).'>
1432
+

1433
+
<!ENTITY rnp.parameter.loadsave-flags 'See RNP_LOAD_SAVE_* flags description.'>
1434
+

1103
1435
<!-- socket entities -->
1104
1436

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

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

1208
-
<!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.'>
1209
1544

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

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

1237
-
<!ENTITY dom.allowstatic '<para xmlns="http://docbook.org/ns/docbook">Prior to PHP 8.0.0 this method
1238
-
<emphasis>could</emphasis> be called statically, but would issue an <constant>E_DEPRECATED</constant> error.
1239
-
As of PHP 8.0.0 calling this method statically throws an <classname>Error</classname> exception</para>'>
1240
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>'>
1241
-
<!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>'>
1242
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>'>
1243
1575

1244
1576

...
...
@@ -1277,6 +1609,58 @@ As of PHP 8.0.0 calling this method statically throws an <classname>Error</class
1277
1609
</books>
1278
1610
]]></programlisting>'>
1279
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>.'>
1280
1664

1281
1665
<!-- FileSystem entities -->
1282
1666
<!ENTITY fs.emits.warning.on.failure '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1343,7 +1727,7 @@ string</link>, or a Connect Name from
1343
1727
the <filename>tnsnames.ora</filename> file, or the name of a local
1344
1728
Oracle instance.
1345
1729
</para>
1346
-
<para xmlns='http://docbook.org/ns/docbook'>If not specified, PHP uses
1730
+
<para xmlns='http://docbook.org/ns/docbook'>If not specified or &null;, PHP uses
1347
1731
environment variables such as <constant>TWO_TASK</constant> (on Linux)
1348
1732
or <constant>LOCAL</constant> (on Windows)
1349
1733
and <constant>ORACLE_SID</constant> to determine the
...
...
@@ -1484,7 +1868,8 @@ linkend="ini.open-basedir">open_basedir</link>.</para></note>'>
1484
1868

1485
1869
<!ENTITY note.language-construct '<note xmlns="http://docbook.org/ns/docbook"><simpara>Because this is a
1486
1870
language construct and not a function, it cannot be called using
1487
-
<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>
1488
1873
</note>'>
1489
1874

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

1538
1923
<!ENTITY ini.php.constants 'For further details and definitions of the
1539
-
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"/>.'>
1540
1925

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

1573
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>'>
1574
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
+

1575
1971
<!-- PECL entities -->
1576
-
<!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
1577
-
is not bundled with PHP.'>
1972
+
<!ENTITY pecl.moved 'This &link.pecl; extension is not bundled with PHP.'>
1578
1973

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

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

1604
1998
<!ENTITY pecl.windows.download.unbundled '&pecl.windows.download;'>
1605
1999

1606
-
<!ENTITY pecl.moved-ver 'This extension has been moved to the
1607
-
<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
1608
-
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 '>
2002
+

2003
+
<!-- PGSQL entities -->
2004
+

2005
+
<!ENTITY pgsql.parameter.connection '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.</para>'>
2006
+

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

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

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

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

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

2032
+
<!ENTITY pgsql.changelog.connection-object '<row xmlns="http://docbook.org/ns/docbook">
2033
+
<entry>8.1.0</entry>
2034
+
<entry>
2035
+
The <parameter>connection</parameter> parameter expects an <classname>PgSql\Connection</classname>
2036
+
instance now; previously, a &resource; was expected.
2037
+
</entry>
2038
+
</row>'>
2039
+

2040
+
<!ENTITY pgsql.changelog.result-object '<row xmlns="http://docbook.org/ns/docbook">
2041
+
<entry>8.1.0</entry>
2042
+
<entry>
2043
+
The <parameter>result</parameter> parameter expects an <classname>PgSql\Result</classname>
2044
+
instance now; previously, a &resource; was expected.
2045
+
</entry>
2046
+
</row>'>
2047
+

2048
+
<!ENTITY pgsql.changelog.lob-object '<row xmlns="http://docbook.org/ns/docbook">
2049
+
<entry>8.1.0</entry>
2050
+
<entry>
2051
+
The <parameter>lob</parameter> parameter expects an <classname>PgSql\Lob</classname>
2052
+
instance now; previously, a &resource; was expected.
2053
+
</entry>
2054
+
</row>'>
2055
+

2056
+
<!ENTITY pgsql.changelog.return-result-object '<row xmlns="http://docbook.org/ns/docbook">
2057
+
<entry>8.1.0</entry>
2058
+
<entry>
2059
+
Returns an <classname>PgSql\Result</classname> instance now;
2060
+
previously, a &resource; was returned.
2061
+
</entry>
2062
+
</row>'>
1609
2063

1610
2064
<!-- Common pieces for reference part END -->
1611
2065

...
...
@@ -1620,8 +2074,8 @@ extensions in order to use these functions.</simpara>'>
1620
2074
<!ENTITY sqlsafemode '<link xmlns="http://docbook.org/ns/docbook" linkend="ini.sql.safe-mode">SQL safe mode</link>'>
1621
2075

1622
2076
<!-- APD Notes -->
1623
-
<!ENTITY apd.debug-level.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1624
-
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
1625
2079
together the <literal>XXX_TRACE</literal> constants.</para><para>It is not recommended
1626
2080
to use <constant>MEMORY_TRACE</constant>. It is very slow and does not appear to be accurate.
1627
2081
<constant>ASSIGNMENT_TRACE</constant> is not implemented yet.</para><para>To turn on all
...
...
@@ -1629,8 +2083,8 @@ functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the val
1629
2083
</listitem></varlistentry>'>
1630
2084

1631
2085
<!-- BCMath Notes -->
1632
-
<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1633
-
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
1634
2088
of digits after the decimal place in the result. If omitted, it will default to the scale set
1635
2089
globally with the <function>bcscale</function> function, or fallback to <literal>0</literal> if
1636
2090
this has not been set.</para></listitem></varlistentry>'>
...
...
@@ -1642,21 +2096,39 @@ the ASCII value of a single character (negative values have 256 added in order t
1642
2096
characters in the Extended ASCII range). Any other integer is interpreted as a string
1643
2097
containing the decimal digits of the integer.</para></note>'>
1644
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
+

2107
+
<!-- FTP Notes -->
2108
+
<!ENTITY ftp.changelog.ftp-param '<row xmlns="http://docbook.org/ns/docbook">
2109
+
<entry>8.1.0</entry>
2110
+
<entry>
2111
+
The <parameter>ftp</parameter> parameter expects an <classname>FTP\Connection</classname>
2112
+
instance now; previously, a &resource; was expected.
2113
+
</entry>
2114
+
</row>'>
2115
+
<!ENTITY ftp.parameter.ftp '<para xmlns="http://docbook.org/ns/docbook">An <classname>FTP\Connection</classname> instance.</para>'>
2116
+

1645
2117
<!-- GMP Notes -->
1646
2118
<!ENTITY gmp.return 'A <classname xmlns="http://docbook.org/ns/docbook">GMP</classname> object.'>
1647
2119
<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">A <classname>GMP</classname> object, an &integer; or a numeric &string;.</para>'>
1648
2120

1649
2121
<!-- MySQLi Notes -->
1650
-
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1651
-
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>
1652
2124
object returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>,
1653
2125
<function>mysqli_use_result</function> or <function>mysqli_stmt_get_result</function>.</para></listitem></varlistentry>'>
1654
-
<!ENTITY mysqli.link.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1655
-
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
1656
2128
returned by <function>mysqli_connect</function> or <function>mysqli_init</function>
1657
2129
</para></listitem></varlistentry>'>
1658
-
<!ENTITY mysqli.stmt.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1659
-
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
1660
2132
returned by <function>mysqli_stmt_init</function>.</para></listitem></varlistentry>'>
1661
2133
<!ENTITY mysqli.available.mysqlnd 'Available only with <link xmlns="http://docbook.org/ns/docbook"
1662
2134
linkend="book.mysqlnd">mysqlnd</link>.'>
...
...
@@ -1665,6 +2137,9 @@ linkend="book.mysqlnd">mysqlnd</link>.'>
1665
2137
hand-shake/authentication, which mysqlnd will use.</para><para>Libmysqlclient uses the default charset set in the
1666
2138
<filename>my.cnf</filename> or by an explicit call to <function>mysqli_options</function> prior to
1667
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>'>
1668
2143
<!ENTITY mysqli.sqlinjection.warning '<warning xmlns="http://docbook.org/ns/docbook">
1669
2144
<title>Security warning: SQL injection</title><para>If the query contains any variable
1670
2145
input then <link linkend="mysqli.quickstart.prepared-statements">parameterized
...
...
@@ -1672,12 +2147,26 @@ prepared statements</link> should be used instead. Alternatively, the
1672
2147
data must be properly formatted and all strings must be escaped using
1673
2148
the <function>mysqli_real_escape_string</function>
1674
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>'>
1675
2159

1676
2160
<!-- Notes for SAPI/Apache -->
1677
2161
<!ENTITY apache.req.module '<simpara xmlns="http://docbook.org/ns/docbook">This function is supported when PHP
1678
2162
is installed as an Apache module webserver.
1679
2163
</simpara>'>
1680
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
+

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

1723
2212
<!-- MSQL Notes -->
1724
2213
<!-- The msql.*.description entities are used in the parameters refsect1 -->
1725
-
<!ENTITY msql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1726
-
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.
1727
2216
If not specified, the last link opened by <function>msql_connect</function>
1728
2217
is assumed. If no such link is found, the function will try to establish a
1729
2218
link as if <function>msql_connect</function> was called, and use it.
1730
2219
</para></listitem></varlistentry>'>
1731
2220

1732
-
<!ENTITY msql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1733
-
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
1734
2223
is being evaluated. This result comes from a call to
1735
2224
<function>msql_query</function>.</para></listitem></varlistentry>'>
1736
2225

1737
-
<!ENTITY msql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1738
-
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
1739
2228
<parameter>field_offset</parameter> starts at <literal>1</literal>.</para></listitem></varlistentry>'>
1740
2229

1741
2230

1742
2231
<!-- MySQL Notes -->
1743
2232
<!-- The mysql.*.description entities are used in the parameters refsect1 -->
1744
-
<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1745
-
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
1746
2235
link identifier is not specified, the last link opened by
1747
2236
<function>mysql_connect</function> is assumed. If no such link is found, it
1748
2237
will try to create one as if <function>mysql_connect</function> had been called
...
...
@@ -1751,20 +2240,20 @@ with no arguments. If no connection is found or established, an
1751
2240
</varlistentry>'>
1752
2241

1753
2242
<!ENTITY mysql.linkid-noreopen.description '<varlistentry
1754
-
xmlns="http://docbook.org/ns/docbook"><term><parameter>
1755
-
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
1756
2245
link identifier is not specified, the last link opened by
1757
2246
<function>mysql_connect</function> is assumed. If no connection is found or
1758
2247
established, an <constant>E_WARNING</constant> level error is
1759
2248
generated.</para></listitem></varlistentry>'>
1760
2249

1761
-
<!ENTITY mysql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1762
-
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
1763
2252
is being evaluated. This result comes from a call to
1764
2253
<function>mysql_query</function>.</para></listitem></varlistentry>'>
1765
2254

1766
-
<!ENTITY mysql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1767
-
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
1768
2257
<parameter>field_offset</parameter> starts at <literal>0</literal>. If
1769
2258
<parameter>field_offset</parameter> does not exist, an error of level
1770
2259
<constant>E_WARNING</constant> is also issued.</para></listitem></varlistentry>'>
...
...
@@ -1814,8 +2303,8 @@ using the CT library interface to Sybase, and not with the DB library.
1814
2303
<!ENTITY sybase.db.only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when
1815
2304
using the DB library interface to Sybase, and not with the CT library.</simpara></note>'>
1816
2305

1817
-
<!ENTITY sybase.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1818
-
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
1819
2308
link identifier is not specified, the last link opened by
1820
2309
<function>sybase_connect</function> is assumed. If no such link is found, it
1821
2310
will try to create one as if <function>sybase_connect</function> was called
...
...
@@ -1829,15 +2318,15 @@ determines the unit length. If it is <literal>0</literal> or omitted, the
1829
2318
default unit as specified for the page is used. In other cases, the coordinates
1830
2319
are measured in postscript points, disregarding the current unit.</para>'>
1831
2320

1832
-
<!ENTITY cpdf.mode.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1833
-
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>
1834
2323
determines the unit length. If it is <literal>0</literal> or omitted, the
1835
2324
default unit as specified for the page is used. In other cases, the coordinates
1836
2325
are measured in postscript points, disregarding the current unit.</para>
1837
2326
</listitem></varlistentry>'>
1838
2327

1839
-
<!ENTITY cpdf.pdf-document.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1840
-
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
1841
2330
<function>cpdf_open</function>.</para></listitem></varlistentry>'>
1842
2331

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

1892
2381
<!ENTITY Credit.Introduction '<para xmlns="http://docbook.org/ns/docbook"> We highlight the currently most active
1893
-
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
1894
2383
currently help in our work or have provided a great amount of help to the project
1895
2384
in the past. There are a lot of unnamed people who help out with user
1896
2385
notes on manual pages, which continually get included in the references, the
...
...
@@ -1950,8 +2439,8 @@ using public key authentication, use the
1950
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.'>
1951
2440

1952
2441
<!-- XMLWriter Notes -->
1953
-
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>
1954
-
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.
1955
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>'>
1956
2445

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

2163
2652
<!ENTITY reflection.export.param.name 'The reflection to export.'>
2164
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
+

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

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

2406
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
+

2407
2936
<!ENTITY mongodb.option.collation '
2408
2937
<row xmlns="http://docbook.org/ns/docbook">
2409
2938
<entry>collation</entry>
...
...
@@ -2421,6 +2950,20 @@ used.</para>'>
2421
2950
</entry>
2422
2951
</row>
2423
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
+
'>
2424
2967
<!ENTITY mongodb.option.encryption.keyVaultClient '
2425
2968
<row xmlns="http://docbook.org/ns/docbook">
2426
2969
<entry>keyVaultClient</entry>
...
...
@@ -2432,16 +2975,22 @@ used.</para>'>
2432
2975
<row xmlns="http://docbook.org/ns/docbook">
2433
2976
<entry>keyVaultNamespace</entry>
2434
2977
<entry><type>string</type></entry>
2435
-
<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>
2436
2979
</row>
2437
2980
'>
2438
2981
<!ENTITY mongodb.option.encryption.kmsProviders '
2439
-
<row xmlns="http://docbook.org/ns/docbook">
2982
+
<row xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
2440
2983
<entry>kmsProviders</entry>
2441
2984
<entry><type>array</type></entry>
2442
2985
<entry>
2443
2986
<para>
2444
-
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>.
2445
2994
</para>
2446
2995
<para>
2447
2996
The format for <literal>"aws"</literal> is as follows:
...
...
@@ -2450,7 +2999,8 @@ used.</para>'>
2450
2999
<![CDATA[
2451
3000
aws: {
2452
3001
accessKeyId: <string>,
2453
-
secretAccessKey: <string>
3002
+
secretAccessKey: <string>,
3003
+
sessionToken: <optional string>
2454
3004
}
2455
3005
]]>
2456
3006
</programlisting>
...
...
@@ -2464,7 +3014,6 @@ azure: {
2464
3014
clientId: <string>,
2465
3015
clientSecret: <string>,
2466
3016
identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
2467
-

2468
3017
}
2469
3018
]]>
2470
3019
</programlisting>
...
...
@@ -2473,11 +3022,20 @@ azure: {
2473
3022
</para>
2474
3023
<programlisting role="javascript">
2475
3024
<![CDATA[
2476
-
aws: {
3025
+
gcp: {
2477
3026
email: <string>,
2478
3027
privateKey: <base64 string>|<MongoDB\BSON\Binary>,
2479
3028
endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
2480
-

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>
2481
3039
}
2482
3040
]]>
2483
3041
</programlisting>
...
...
@@ -2495,6 +3053,163 @@ local: {
2495
3053
</entry>
2496
3054
</row>
2497
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
+
'>
2498
3213
<!ENTITY mongodb.option.maxCommitTimeMS '
2499
3214
<row xmlns="http://docbook.org/ns/docbook">
2500
3215
<entry>maxCommitTimeMS</entry>
...
...
@@ -2613,6 +3328,156 @@ local: {
2613
3328
</listitem>
2614
3329
</varlistentry>
2615
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
+
'>
2616
3481
<!ENTITY mongodb.parameter.query '
2617
3482
<varlistentry xmlns="http://docbook.org/ns/docbook">
2618
3483
<term><parameter>query</parameter> (<classname>MongoDB\Driver\Query</classname>)</term>
...
...
@@ -2660,6 +3525,9 @@ local: {
2660
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>'>
2661
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>'>
2662
3527

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

2663
3531
<!ENTITY mongodb.note.decimal128 '
2664
3532
<note xmlns="http://docbook.org/ns/docbook">
2665
3533
<simpara>
...
...
@@ -2728,6 +3596,18 @@ local: {
2728
3596
</note>
2729
3597
'>
2730
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
+

2731
3611
<!-- Radius -->
2732
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>'>
2733
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>'>
...
...
@@ -2738,7 +3618,7 @@ local: {
2738
3618

2739
3619
<!-- posix snippets -->
2740
3620
<!ENTITY posix.parameter.fd '<varlistentry xmlns="http://docbook.org/ns/docbook">
2741
-
<term><parameter>fd</parameter></term>
3621
+
<term><parameter>file_descriptor</parameter></term>
2742
3622
<listitem>
2743
3623
<para>
2744
3624
The file descriptor, which is expected to be either a file
...
...
@@ -2746,9 +3626,6 @@ local: {
2746
3626
will be assumed to be a file descriptor that can be passed directly to
2747
3627
the underlying system call.
2748
3628
</para>
2749
-
<para>
2750
-
In almost all cases, you will want to provide a file <type>resource</type>.
2751
-
</para>
2752
3629
</listitem>
2753
3630
</varlistentry>'>
2754
3631

...
...
@@ -2862,16 +3739,20 @@ local: {
2862
3739
<formalpara>
2863
3740
<title>Width</title>
2864
3741
<para>
2865
-
An integer that says how many characters (minimum)
2866
-
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.
2867
3747
</para>
2868
3748
</formalpara>
2869
3749

2870
3750
<formalpara>
2871
3751
<title>Precision</title>
2872
3752
<para>
2873
-
A period <literal>.</literal> followed by an integer
2874
-
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:
2875
3756
<itemizedlist>
2876
3757
<listitem>
2877
3758
<simpara>
...
...
@@ -2899,19 +3780,14 @@ local: {
2899
3780
<note>
2900
3781
<simpara>
2901
3782
If the period is specified without an explicit value for precision,
2902
-
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.
2903
3786
</simpara>
2904
3787
</note>
2905
3788
</para>
2906
3789
</formalpara>
2907
3790

2908
-
<note>
2909
-
<simpara>
2910
-
Attempting to use a position specifier greater than
2911
-
<constant>PHP_INT_MAX</constant> will generate warnings.
2912
-
</simpara>
2913
-
</note>
2914
-

2915
3791
<para>
2916
3792
<table>
2917
3793
<title>Specifiers</title>
...
...
@@ -3115,6 +3991,44 @@ local: {
3115
3991
</varlistentry>
3116
3992
'>
3117
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
+

3118
4032
<!ENTITY strings.parameter.needle.non-string '
3119
4033
<para xmlns="http://docbook.org/ns/docbook">
3120
4034
Prior to PHP 8.0.0, if <parameter>needle</parameter> is not a string, it is converted
...
...
@@ -3126,6 +4040,13 @@ local: {
3126
4040
</para>
3127
4041
'>
3128
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
+

3129
4050
<!ENTITY strings.changelog.encoding '
3130
4051
<row xmlns="http://docbook.org/ns/docbook">
3131
4052
<entry>5.6.0</entry>
...
...
@@ -3138,6 +4059,163 @@ local: {
3138
4059
</row>
3139
4060
'>
3140
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
+

3141
4219
<!-- filter snippets -->
3142
4220
<!ENTITY filter.param.filter '
3143
4221
<varlistentry xmlns="http://docbook.org/ns/docbook">
...
...
@@ -3160,34 +4238,65 @@ local: {
3160
4238
<!-- csprng snippets -->
3161
4239
<!ENTITY csprng.sources '
3162
4240
<para xmlns="http://docbook.org/ns/docbook">
3163
-
The sources of randomness used for this function are as follows:
4241
+
The sources of randomness in the order of priority are as follows:
3164
4242
</para>
3165
4243
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3166
4244
<listitem>
3167
-
<simpara>
3168
-
On Windows,
3169
-
<link xlink:href="&url.csprng.crypt-gen-random;"><function>CryptGenRandom</function></link>
3170
-
will always be used. As of PHP 7.2.0, the
3171
-
<link xlink:href="&url.csprng.cng-api;">CNG-API</link>
3172
-
will always be used instead.
3173
-
</simpara>
4245
+
<para>
4246
+
Linux: <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4247
+
</para>
3174
4248
</listitem>
3175
4249
<listitem>
3176
-
<simpara>
3177
-
On Linux, the
3178
-
<link xlink:href="&url.csprng.get-random-2;">getrandom(2)</link>
3179
-
syscall will be used if available.
3180
-
</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>
3181
4289
</listitem>
3182
4290
<listitem>
3183
4291
<simpara>
3184
-
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>
3185
4293
</simpara>
3186
4294
</listitem>
3187
4295
<listitem>
3188
4296
<simpara>
3189
-
If none of the aforementioned sources are available, then an
3190
-
<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.
3191
4300
</simpara>
3192
4301
</listitem>
3193
4302
</itemizedlist>
...
...
@@ -3196,13 +4305,7 @@ local: {
3196
4305
<listitem xmlns="http://docbook.org/ns/docbook">
3197
4306
<simpara>
3198
4307
If an appropriate source of randomness cannot be found,
3199
-
an <classname>Exception</classname> will be thrown.
3200
-
</simpara>
3201
-
</listitem>
3202
-
<listitem xmlns="http://docbook.org/ns/docbook">
3203
-
<simpara>
3204
-
If invalid parameters are given, a <classname>TypeError</classname>
3205
-
will be thrown.
4308
+
a <classname>Random\RandomException</classname> will be thrown.
3206
4309
</simpara>
3207
4310
</listitem>
3208
4311
'>
...
...
@@ -3216,6 +4319,15 @@ local: {
3216
4319
</note>
3217
4320
'>
3218
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
+
'>
3219
4331

3220
4332
<!-- UOPZ snippets -->
3221
4333

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

3226
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>'>
3227
4369

3228
4370
<!ENTITY xml.changelog.parser-param '<row xmlns="http://docbook.org/ns/docbook">
3229
4371
<entry>8.0.0</entry>
3230
4372
<entry>
3231
4373
<parameter>parser</parameter> expects an <classname>XMLParser</classname>
3232
-
instance now; previously, a <type>resource</type> was expected.
4374
+
instance now; previously, a valid <literal>xml</literal> <type>resource</type> was expected.
3233
4375
</entry>
3234
4376
</row>'>
3235
4377

3236
4378