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>'>
...
...
@@ -309,6 +334,10 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
309
334
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
310
335
is highly discouraged.</simpara></warning>'>
311
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
+

312
341
<!ENTITY warn.deprecated.function-8-0-0 '<warning
313
342
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
314
343
<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0. Relying on this function
...
...
@@ -324,6 +353,16 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
324
353
<emphasis>DEPRECATED</emphasis> as of PHP 8.2.0. Relying on this function
325
354
is highly discouraged.</simpara></warning>'>
326
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
+

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

...
...
@@ -580,6 +619,12 @@ is highly discouraged.</simpara></warning>
580
619

581
620
<!ENTITY example.outputs.82 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.2:</para>'>
582
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
+

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

585
630
<!ENTITY example.outputs.64bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 64 bit machines:</para>'>
...
...
@@ -665,6 +710,44 @@ use.</simpara></note>'>
665
710
</varlistentry>
666
711
'>
667
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
+

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

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

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

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

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

714
799
<!-- Returns -->
715
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
+

716
808
<!ENTITY return.falseforfailure ' or &false; on failure'>
717
809
<!ENTITY return.falseforfailure.style.procedural '&style.procedural; returns &false; on failure.'>
718
810

...
...
@@ -739,7 +831,23 @@ function.</simpara></warning>'>
739
831
<entry>8.1.0</entry>
740
832
<entry>
741
833
Calling this function on &object;s is deprecated.
742
-
Either use <function>get_mangled_object_vars</function> on the &object; first, or use <classname>ArrayIterator</classname>.
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.
743
851
</entry>
744
852
</row>
745
853
'>
...
...
@@ -948,7 +1056,7 @@ purposes.</simpara></warning>'>
948
1056
<entry>8.0.0</entry>
949
1057
<entry>
950
1058
<parameter>image</parameter> expects a <classname>GdImage</classname>
951
-
instance now; previously, a <type>resource</type> was expected.
1059
+
instance now; previously, a valid <literal>gd</literal> <type>resource</type> was expected.
952
1060
</entry>
953
1061
</row>'>
954
1062

...
...
@@ -1081,7 +1189,7 @@ returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
1081
1189
<entry>8.1.0</entry>
1082
1190
<entry>
1083
1191
The <parameter>imap</parameter> parameter expects an <classname>IMAP\Connection</classname>
1084
-
instance now; previously, a &resource; was expected.
1192
+
instance now; previously, a valid <literal>imap</literal> &resource; was expected.
1085
1193
</entry>
1086
1194
</row>'>
1087
1195

...
...
@@ -1156,7 +1264,7 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1156
1264
<entry>8.1.0</entry>
1157
1265
<entry>
1158
1266
The <parameter>ldap</parameter> parameter expects an <classname>LDAP\Connection</classname>
1159
-
instance now; previously, a &resource; was expected.
1267
+
instance now; previously, a valid <literal>ldap link</literal> &resource; was expected.
1160
1268
</entry>
1161
1269
</row>'>
1162
1270

...
...
@@ -1164,7 +1272,7 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1164
1272
<entry>8.1.0</entry>
1165
1273
<entry>
1166
1274
The <parameter>entry</parameter> parameter expects an <classname>LDAP\ResultEntry</classname>
1167
-
instance now; previously, a &resource; was expected.
1275
+
instance now; previously, a valid <literal>ldap result entry</literal> &resource; was expected.
1168
1276
</entry>
1169
1277
</row>'>
1170
1278

...
...
@@ -1172,7 +1280,7 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1172
1280
<entry>8.1.0</entry>
1173
1281
<entry>
1174
1282
The <parameter>result</parameter> parameter expects an <classname>LDAP\Result</classname>
1175
-
instance now; previously, a &resource; was expected.
1283
+
instance now; previously, a valid <literal>ldap result</literal> &resource; was expected.
1176
1284
</entry>
1177
1285
</row>'>
1178
1286

...
...
@@ -1250,6 +1358,14 @@ encoding value will be used.</para>'>
1250
1358

1251
1359
<!-- memcached notes -->
1252
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
+

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

...
...
@@ -1263,6 +1379,19 @@ encoding value will be used.</para>'>
1263
1379

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

1266
1395
<!-- password notes -->
1267
1396

1268
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.'>
...
...
@@ -1295,6 +1424,14 @@ encoding value will be used.</para>'>
1295
1424

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

1298
1435
<!-- socket entities -->
1299
1436

1300
1437
<!ENTITY sockets.changelog.socket-param '<row xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1401,7 +1538,9 @@ The function modifies this object.</para></listitem></varlistentry>'>
1401
1538
returned by <function>timezone_open</function></para></listitem></varlistentry>'>
1402
1539

1403
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.'>
1404
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.'>
1405
1544

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

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

1433
-
<!ENTITY dom.allowstatic '<para xmlns="http://docbook.org/ns/docbook">Prior to PHP 8.0.0 this method
1434
-
<emphasis>could</emphasis> be called statically, but would issue an <constant>E_DEPRECATED</constant> error.
1435
-
As of PHP 8.0.0 calling this method statically throws an <classname>Error</classname> exception</para>'>
1436
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>'>
1437
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>'>
1438
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>'>
...
...
@@ -1473,6 +1609,58 @@ As of PHP 8.0.0 calling this method statically throws an <classname>Error</class
1473
1609
</books>
1474
1610
]]></programlisting>'>
1475
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>.'>
1476
1664

1477
1665
<!-- FileSystem entities -->
1478
1666
<!ENTITY fs.emits.warning.on.failure '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1733,7 +1921,7 @@ The behaviour of these functions is affected by settings in &php.ini;.
1733
1921
</simpara>'>
1734
1922

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

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

1770
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>'>
1771
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
+

1772
1971
<!-- PECL entities -->
1773
-
<!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
1774
-
is not bundled with PHP.'>
1972
+
<!ENTITY pecl.moved 'This &link.pecl; extension is not bundled with PHP.'>
1775
1973

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

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

1801
1998
<!ENTITY pecl.windows.download.unbundled '&pecl.windows.download;'>
1802
1999

1803
-
<!ENTITY pecl.moved-ver 'This extension has been moved to the
1804
-
<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
1805
-
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 '>
1806
2002

1807
2003
<!-- PGSQL entities -->
1808
2004

...
...
@@ -1951,6 +2147,10 @@ prepared statements</link> should be used instead. Alternatively, the
1951
2147
data must be properly formatted and all strings must be escaped using
1952
2148
the <function>mysqli_real_escape_string</function>
1953
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>'>
1954
2154

1955
2155
<!-- Notes for PCRE -->
1956
2156
<!ENTITY pcre.pattern.warning '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -2451,6 +2651,34 @@ to be references, then they must be references in the passed argument list.'>
2451
2651

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

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

...
...
@@ -2747,11 +2975,11 @@ used.</para>'>
2747
2975
<row xmlns="http://docbook.org/ns/docbook">
2748
2976
<entry>keyVaultNamespace</entry>
2749
2977
<entry><type>string</type></entry>
2750
-
<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>
2751
2979
</row>
2752
2980
'>
2753
2981
<!ENTITY mongodb.option.encryption.kmsProviders '
2754
-
<row xmlns="http://docbook.org/ns/docbook">
2982
+
<row xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
2755
2983
<entry>kmsProviders</entry>
2756
2984
<entry><type>array</type></entry>
2757
2985
<entry>
...
...
@@ -2759,13 +2987,20 @@ used.</para>'>
2759
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.
2760
2988
</para>
2761
2989
<para>
2990
+
If an empty document is specified for <literal>"aws"</literal>,
2991
+
<literal>"azure"</literal>, or <literal>"gcp"</literal>, the driver
2992
+
will attempt to configure the provider using
2993
+
<link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#automatic-credentials">Automatic Credentials</link>.
2994
+
</para>
2995
+
<para>
2762
2996
The format for <literal>"aws"</literal> is as follows:
2763
2997
</para>
2764
2998
<programlisting role="javascript">
2765
2999
<![CDATA[
2766
3000
aws: {
2767
3001
accessKeyId: <string>,
2768
-
secretAccessKey: <string>
3002
+
secretAccessKey: <string>,
3003
+
sessionToken: <optional string>
2769
3004
}
2770
3005
]]>
2771
3006
</programlisting>
...
...
@@ -2818,6 +3053,142 @@ local: {
2818
3053
</entry>
2819
3054
</row>
2820
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
+
'>
2821
3192
<!ENTITY mongodb.option.encryption.tlsOptions '
2822
3193
<row xmlns="http://docbook.org/ns/docbook">
2823
3194
<entry>tlsOptions</entry>
...
...
@@ -2831,7 +3202,8 @@ local: {
2831
3202
<provider>: {
2832
3203
tlsCaFile: <optional string>,
2833
3204
tlsCertificateKeyFile: <optional string>,
2834
-
tlsCertificateKeyFilePassword: <optional string>
3205
+
tlsCertificateKeyFilePassword: <optional string>,
3206
+
tlsDisableOCSPEndpointCheck: <optional bool>
2835
3207
}
2836
3208
]]>
2837
3209
</programlisting>
...
...
@@ -2956,6 +3328,156 @@ local: {
2956
3328
</listitem>
2957
3329
</varlistentry>
2958
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
+
'>
2959
3481
<!ENTITY mongodb.parameter.query '
2960
3482
<varlistentry xmlns="http://docbook.org/ns/docbook">
2961
3483
<term><parameter>query</parameter> (<classname>MongoDB\Driver\Query</classname>)</term>
...
...
@@ -3003,15 +3525,8 @@ local: {
3003
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>'>
3004
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>'>
3005
3527

3006
-
<!ENTITY mongodb.note.queryable-encryption-preview '
3007
-
<note xmlns="http://docbook.org/ns/docbook">
3008
-
<simpara>
3009
-
Queryable Encryption is in public preview and available for evaluation
3010
-
purposes. It is not yet recommended for production deployments as breaking
3011
-
changes may be introduced. See the <link xlink:href="https://www.mongodb.com/blog/post/mongodb-releases-queryable-encryption-preview/" xmlns:xlink="http://www.w3.org/1999/xlink">Queryable Encryption Preview</link> blog post for more information.
3012
-
</simpara>
3013
-
</note>
3014
-
'>
3528
+
<!-- Not used in EN anymore -->
3529
+
<!ENTITY mongodb.note.queryable-encryption-preview ''>
3015
3530

3016
3531
<!ENTITY mongodb.note.decimal128 '
3017
3532
<note xmlns="http://docbook.org/ns/docbook">
...
...
@@ -3103,7 +3618,7 @@ local: {
3103
3618

3104
3619
<!-- posix snippets -->
3105
3620
<!ENTITY posix.parameter.fd '<varlistentry xmlns="http://docbook.org/ns/docbook">
3106
-
<term><parameter>fd</parameter></term>
3621
+
<term><parameter>file_descriptor</parameter></term>
3107
3622
<listitem>
3108
3623
<para>
3109
3624
The file descriptor, which is expected to be either a file
...
...
@@ -3111,9 +3626,6 @@ local: {
3111
3626
will be assumed to be a file descriptor that can be passed directly to
3112
3627
the underlying system call.
3113
3628
</para>
3114
-
<para>
3115
-
In almost all cases, you will want to provide a file <type>resource</type>.
3116
-
</para>
3117
3629
</listitem>
3118
3630
</varlistentry>'>
3119
3631

...
...
@@ -3227,16 +3739,20 @@ local: {
3227
3739
<formalpara>
3228
3740
<title>Width</title>
3229
3741
<para>
3230
-
An integer that says how many characters (minimum)
3231
-
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.
3232
3747
</para>
3233
3748
</formalpara>
3234
3749

3235
3750
<formalpara>
3236
3751
<title>Precision</title>
3237
3752
<para>
3238
-
A period <literal>.</literal> followed by an integer
3239
-
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:
3240
3756
<itemizedlist>
3241
3757
<listitem>
3242
3758
<simpara>
...
...
@@ -3264,19 +3780,14 @@ local: {
3264
3780
<note>
3265
3781
<simpara>
3266
3782
If the period is specified without an explicit value for precision,
3267
-
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.
3268
3786
</simpara>
3269
3787
</note>
3270
3788
</para>
3271
3789
</formalpara>
3272
3790

3273
-
<note>
3274
-
<simpara>
3275
-
Attempting to use a position specifier greater than
3276
-
<constant>PHP_INT_MAX</constant> will generate warnings.
3277
-
</simpara>
3278
-
</note>
3279
-

3280
3791
<para>
3281
3792
<table>
3282
3793
<title>Specifiers</title>
...
...
@@ -3529,6 +4040,13 @@ local: {
3529
4040
</para>
3530
4041
'>
3531
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
+

3532
4050
<!ENTITY strings.changelog.encoding '
3533
4051
<row xmlns="http://docbook.org/ns/docbook">
3534
4052
<entry>5.6.0</entry>
...
...
@@ -3541,6 +4059,163 @@ local: {
3541
4059
</row>
3542
4060
'>
3543
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
+

3544
4219
<!-- filter snippets -->
3545
4220
<!ENTITY filter.param.filter '
3546
4221
<varlistentry xmlns="http://docbook.org/ns/docbook">
...
...
@@ -3563,34 +4238,65 @@ local: {
3563
4238
<!-- csprng snippets -->
3564
4239
<!ENTITY csprng.sources '
3565
4240
<para xmlns="http://docbook.org/ns/docbook">
3566
-
The sources of randomness used for this function are as follows:
4241
+
The sources of randomness in the order of priority are as follows:
3567
4242
</para>
3568
4243
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3569
4244
<listitem>
3570
-
<simpara>
3571
-
On Windows,
3572
-
<link xlink:href="&url.csprng.crypt-gen-random;"><function>CryptGenRandom</function></link>
3573
-
will always be used. As of PHP 7.2.0, the
3574
-
<link xlink:href="&url.csprng.cng-api;">CNG-API</link>
3575
-
will always be used instead.
3576
-
</simpara>
4245
+
<para>
4246
+
Linux: <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4247
+
</para>
3577
4248
</listitem>
3578
4249
<listitem>
3579
-
<simpara>
3580
-
On Linux, the
3581
-
<link xlink:href="&url.csprng.get-random-2;">getrandom(2)</link>
3582
-
syscall will be used if available.
3583
-
</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>
3584
4289
</listitem>
3585
4290
<listitem>
3586
4291
<simpara>
3587
-
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>
3588
4293
</simpara>
3589
4294
</listitem>
3590
4295
<listitem>
3591
4296
<simpara>
3592
-
If none of the aforementioned sources are available, then a
3593
-
<classname>\Random\RandomException</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.
3594
4300
</simpara>
3595
4301
</listitem>
3596
4302
</itemizedlist>
...
...
@@ -3599,13 +4305,7 @@ local: {
3599
4305
<listitem xmlns="http://docbook.org/ns/docbook">
3600
4306
<simpara>
3601
4307
If an appropriate source of randomness cannot be found,
3602
-
a <classname>\Random\RandomException</classname> will be thrown.
3603
-
</simpara>
3604
-
</listitem>
3605
-
<listitem xmlns="http://docbook.org/ns/docbook">
3606
-
<simpara>
3607
-
If invalid parameters are given, a <classname>TypeError</classname>
3608
-
will be thrown.
4308
+
a <classname>Random\RandomException</classname> will be thrown.
3609
4309
</simpara>
3610
4310
</listitem>
3611
4311
'>
...
...
@@ -3619,6 +4319,15 @@ local: {
3619
4319
</note>
3620
4320
'>
3621
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
+
'>
3622
4331

3623
4332
<!-- UOPZ snippets -->
3624
4333

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

3629
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>'>
3630
4369

3631
4370
<!ENTITY xml.changelog.parser-param '<row xmlns="http://docbook.org/ns/docbook">
3632
4371
<entry>8.0.0</entry>
3633
4372
<entry>
3634
4373
<parameter>parser</parameter> expects an <classname>XMLParser</classname>
3635
-
instance now; previously, a <type>resource</type> was expected.
4374
+
instance now; previously, a valid <literal>xml</literal> <type>resource</type> was expected.
3636
4375
</entry>
3637
4376
</row>'>
3638
4377

3639
4378