language-snippets.ent
cb6d65ebe2412bbaef6d1edd076911539f1aceda
cb6d65ebe2412bbaef6d1edd076911539f1aceda
...
...
@@ -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% probability after less than
43
+
80,000 randomly generated seeds according to the birthday problem. A 10% probability
44
+
of a duplicated seed happens after randomly generating roughly 30,000 seeds.
45
+
</para>
46
+
<para>
47
+
This makes Mt19937 unsuitable for applications where duplicated sequences must not happen with
48
+
more than a negligible probability. If reproducible seeding is required, both the
49
+
<classname>Random\Engine\Xoshiro256StarStar</classname> and <classname>Random\Engine\PcgOneseq128XslRr64</classname>
50
+
engines support much larger seeds that are unlikely to collide randomly. If reproducibility
51
+
is not required, the <classname>Random\Engine\Secure</classname> engine provides cryptographically
52
+
secure randomness.
53
+
</para>
54
+
</caution>'>
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><|>*?":</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
...
...
@@ -182,6 +233,9 @@ the names of its functions and any other documentation surrounding this
182
233
extension may change without notice in a future release of PHP.
183
234
This extension should be used at your own risk.</simpara></warning>'>
184
235
236
+
<!ENTITY deprecated.function 'Deprecated this function.'>
237
+
<!ENTITY removed.function 'Removed this function.'>
238
+
185
239
<!ENTITY warn.deprecated.feature-5-3-0 '<warning
186
240
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
187
241
<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature
...
...
@@ -221,6 +275,12 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
221
275
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0. Relying on this function
222
276
is highly discouraged.</simpara></warning>'>
223
277
278
+
<!ENTITY warn.deprecated.function-7-0-0.removed-8-0-0 '<warning
279
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
280
+
<emphasis>DEPRECATED</emphasis> as of PHP 7.0.0 and
281
+
<emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
282
+
is highly discouraged.</simpara></warning>'>
283
+
224
284
<!ENTITY warn.deprecated.function-7-1-0.removed-7-2-0 '<warning
225
285
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
226
286
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0 and
...
...
@@ -277,11 +337,45 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
277
337
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
278
338
is highly discouraged.</simpara></warning>'>
279
339
340
+
<!ENTITY warn.feature.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook">
341
+
<simpara>This feature was <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara>
342
+
</warning>'>
343
+
280
344
<!ENTITY warn.deprecated.function-8-0-0 '<warning
281
345
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
282
346
<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0. Relying on this function
283
347
is highly discouraged.</simpara></warning>'>
284
348
349
+
<!ENTITY warn.deprecated.function-8-1-0 '<warning
350
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
351
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
352
+
is highly discouraged.</simpara></warning>'>
353
+
354
+
<!ENTITY warn.deprecated.function-8-2-0 '<warning
355
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
356
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.2.0. Relying on this function
357
+
is highly discouraged.</simpara></warning>'>
358
+
359
+
<!ENTITY warn.deprecated.feature-8-3-0 '<warning
360
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
361
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this feature
362
+
is highly discouraged.</simpara></warning>'>
363
+
364
+
<!ENTITY warn.deprecated.function-8-3-0 '<warning
365
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
366
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this function
367
+
is highly discouraged.</simpara></warning>'>
368
+
369
+
<!ENTITY warn.deprecated.feature-8-4-0 '<warning
370
+
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
371
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.4.0. Relying on this feature
372
+
is highly discouraged.</simpara></warning>'>
373
+
374
+
<!ENTITY warn.deprecated.function-8-4-0 '<warning
375
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
376
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.4.0. Relying on this function
377
+
is highly discouraged.</simpara></warning>'>
378
+
285
379
<!ENTITY removed.php.future 'This deprecated feature <emphasis xmlns="http://docbook.org/ns/docbook">will</emphasis>
286
380
certainly be <emphasis xmlns="http://docbook.org/ns/docbook">removed</emphasis> in the future.'>
287
381
...
...
@@ -489,6 +583,15 @@ currently not documented; only its argument list is available.
489
583
</para>
490
584
'>
491
585
586
+
<!ENTITY warn.deprecated.function-8-1-0.alternatives '<warning
587
+
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
588
+
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
589
+
is highly discouraged.</simpara></warning>
590
+
<para xmlns="http://docbook.org/ns/docbook">
591
+
Alternatives to this function include:
592
+
</para>
593
+
'>
594
+
492
595
<!-- Misc -->
493
596
494
597
<!ENTITY version.exists.asof 'This exists as of PHP '>
...
...
@@ -525,6 +628,20 @@ currently not documented; only its argument list is available.
525
628
526
629
<!ENTITY example.outputs.80 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.0:</para>'>
527
630
631
+
<!ENTITY example.outputs.81 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.1:</para>'>
632
+
633
+
<!ENTITY example.outputs.82 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.2:</para>'>
634
+
635
+
<!ENTITY example.outputs.82.similar '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.2 is similar to:</para>'>
636
+
637
+
<!ENTITY example.outputs.83 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.3:</para>'>
638
+
639
+
<!ENTITY example.outputs.83.similar '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.3 is similar to:</para>'>
640
+
641
+
<!ENTITY example.outputs.84 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.4:</para>'>
642
+
643
+
<!ENTITY example.outputs.84.similar '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.4 is similar to:</para>'>
644
+
528
645
<!ENTITY example.outputs.32bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 32 bit machines:</para>'>
529
646
530
647
<!ENTITY example.outputs.64bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 64 bit machines:</para>'>
...
...
@@ -545,6 +662,22 @@ something similar to:</para>'>
545
662
<function>reset</function> the <type>array</type> pointer of the input array after
546
663
use.</simpara></note>'>
547
664
665
+
<!ENTITY array.changelog.by-ref '<row xmlns="http://docbook.org/ns/docbook">
666
+
<entry>8.0.0</entry>
667
+
<entry>
668
+
If <parameter>callback</parameter> expects a parameter to be passed
669
+
by reference, this function will now emit an <constant>E_WARNING</constant>.
670
+
</entry>
671
+
</row>'>
672
+
673
+
<!ENTITY array.changelog.require-only-one '<row xmlns="http://docbook.org/ns/docbook">
674
+
<entry>8.0.0</entry>
675
+
<entry>
676
+
This function can now be called with only one parameter.
677
+
Formerly, at least two parameters have been required.
678
+
</entry>
679
+
</row>'>
680
+
548
681
<!ENTITY seealso.array.sorting 'The <link xmlns="http://docbook.org/ns/docbook" linkend="array.sorting">comparison of array sorting functions</link>'>
549
682
550
683
<!ENTITY sort.flags.parameter '<varlistentry xmlns="http://docbook.org/ns/docbook">
...
...
@@ -594,6 +727,44 @@ use.</simpara></note>'>
594
727
</varlistentry>
595
728
'>
596
729
730
+
<!ENTITY sort.callback.description '<para xmlns="http://docbook.org/ns/docbook">
731
+
&return.callbacksort;
732
+
</para>
733
+
&callback.cmp;
734
+
<caution xmlns="http://docbook.org/ns/docbook">
735
+
<para>
736
+
Returning <emphasis>non-integer</emphasis> values from the comparison
737
+
function, such as <type>float</type>, will result in an internal cast to
738
+
<type>int</type> of the callback's return value. So values such as
739
+
<literal>0.99</literal> and <literal>0.1</literal> will both be cast to an
740
+
integer value of <literal>0</literal>, which will compare such values as equal.
741
+
</para>
742
+
</caution>'>
743
+
744
+
<!ENTITY sort.callback.description.presort '<caution xmlns="http://docbook.org/ns/docbook">
745
+
<para>
746
+
The sorting callback must handle any value from any array in any order,
747
+
regardless of the order they were originally provided.
748
+
This is because each individual array is first sorted before being compared against other arrays.
749
+
750
+
For example:
751
+
<programlisting role="php">
752
+
<![CDATA[
753
+
<?php
754
+
$arrayA = ["string", 1];
755
+
$arrayB = [["value" => 1]];
756
+
// $item1 and $item2 can be any of "string", 1 or ["value" => 1]
757
+
$compareFunc = static function ($item1, $item2) {
758
+
$value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);
759
+
$value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);
760
+
return $value1 <=> $value2;
761
+
};
762
+
?>
763
+
]]>
764
+
</programlisting>
765
+
</para>
766
+
</caution>'>
767
+
597
768
<!ENTITY ini.shorthandbytes '<simpara xmlns="http://docbook.org/ns/docbook">When an <type>int</type> is used, the
598
769
value is measured in bytes. Shorthand notation, as described
599
770
in <link linkend="faq.using.shorthandbytes">this FAQ</link>, may also be used.
...
...
@@ -628,11 +799,7 @@ files from the PHP folder into the Windows system directory also works
628
799
<!ENTITY style.oop 'Object-oriented style'>
629
800
<!ENTITY style.procedural 'Procedural style'>
630
801
631
-
<!ENTITY resource '<link xmlns="http://docbook.org/ns/docbook" linkend="language.types.resource">resource</link>'>
632
-
633
-
<!ENTITY foreach '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.foreach">foreach</link>'>
634
-
635
-
<!ENTITY yield '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.yield">yield</link>'>
802
+
<!ENTITY match '<link xmlns="http://docbook.org/ns/docbook" linkend="control-structures.match">match</link>'>
636
803
637
804
<!ENTITY parameter.context 'Refer to the <link xmlns="http://docbook.org/ns/docbook" linkend="context">context</link>
638
805
section of the manual for a description of <literal xmlns="http://docbook.org/ns/docbook">contexts</literal>.'>
...
...
@@ -642,6 +809,13 @@ searched for within the <link xmlns="http://docbook.org/ns/docbook" linkend="ini
642
809
643
810
<!-- Returns -->
644
811
812
+
<!ENTITY return.type.true '<row xmlns="http://docbook.org/ns/docbook">
813
+
<entry>8.2.0</entry>
814
+
<entry>
815
+
The return type is &true; now; previously, it was <type>bool</type>.
816
+
</entry>
817
+
</row>'>
818
+
645
819
<!ENTITY return.falseforfailure ' or &false; on failure'>
646
820
<!ENTITY return.falseforfailure.style.procedural '&style.procedural; returns &false; on failure.'>
647
821
...
...
@@ -663,6 +837,44 @@ information. Use <link linkend="language.operators.comparison">the ===
663
837
operator</link> for testing the return value of this
664
838
function.</simpara></warning>'>
665
839
840
+
<!-- Standard -->
841
+
<!ENTITY standard.changelog.calling-on-objects '<row xmlns="http://docbook.org/ns/docbook">
842
+
<entry>8.1.0</entry>
843
+
<entry>
844
+
Calling this function on &object;s is deprecated.
845
+
Either convert the &object; to an &array; using <function>get_mangled_object_vars</function> first, or use the methods
846
+
provided by a class that implements <interfacename>Iterator</interfacename>, such as <classname>ArrayIterator</classname>, instead.
847
+
</entry>
848
+
</row>
849
+
<row xmlns="http://docbook.org/ns/docbook">
850
+
<entry>7.4.0</entry>
851
+
<entry>
852
+
Instances of <link xmlns="http://docbook.org/ns/docbook" linkend="book.spl">SPL</link> classes are now treated like empty objects that have no properties instead of calling the <interfacename>Iterator</interfacename> method with the same name as this function.
853
+
</entry>
854
+
</row>
855
+
'>
856
+
857
+
<!ENTITY standard.changelog.binary-safe-string-comparison '<row xmlns="http://docbook.org/ns/docbook">
858
+
<entry>8.2.0</entry>
859
+
<entry>
860
+
This function is no longer guaranteed to return
861
+
<code>strlen($string1) - strlen($string2)</code> when string lengths
862
+
are not equal, but may now return <literal>-1</literal> or
863
+
<literal>1</literal> instead.
864
+
</entry>
865
+
</row>
866
+
'>
867
+
868
+
<!-- FileInfo -->
869
+
<!ENTITY fileinfo.parameters.finfo '<para xmlns="http://docbook.org/ns/docbook">An <classname>finfo</classname> instance, returned by <function>finfo_open</function>.</para>'>
870
+
<!ENTITY fileinfo.changelog.finfo-object '<row xmlns="http://docbook.org/ns/docbook">
871
+
<entry>8.1.0</entry>
872
+
<entry>
873
+
The <parameter>finfo</parameter> parameter expects an <classname>finfo</classname>
874
+
instance now; previously, a &resource; was expected.
875
+
</entry>
876
+
</row>'>
877
+
666
878
<!-- OpenSSL -->
667
879
<!ENTITY openssl.param.x509 '<varlistentry xmlns="http://docbook.org/ns/docbook">
668
880
<term><parameter>x509</parameter></term>
...
...
@@ -704,15 +916,22 @@ PHP is compiled with freetype support (<option role="configure">--with-freetype-
704
916
705
917
<!ENTITY note.gd.interpolation '<note xmlns="http://docbook.org/ns/docbook"><para>This function is affected by the interpolation method set by <function>imagesetinterpolation</function>.</para></note>'>
706
918
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,
919
+
<!ENTITY gd.image.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
920
+
<parameter>image</parameter></term><listitem><para>A <classname>GdImage</classname> object, returned by one of the image creation functions,
709
921
such as <function>imagecreatetruecolor</function>.</para></listitem></varlistentry>'>
710
922
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>'>
923
+
<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
924
+
<parameter>font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in
925
+
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or <classname>GdFont</classname> instance,
926
+
returned by <function>imageloadfont</function>.</para></listitem></varlistentry>'>
927
+
928
+
<!ENTITY gd.changelog.gdfont-instance '<row xmlns="http://docbook.org/ns/docbook">
929
+
<entry>8.1.0</entry>
930
+
<entry>
931
+
The <parameter>font</parameter> parameter now accepts both an <classname>GdFont</classname> instance
932
+
and an &integer;; previously only &integer; was accepted.
933
+
</entry>
934
+
</row>'>
716
935
717
936
<!ENTITY gd.ttf.fontfile "
718
937
<varlistentry xmlns='http://docbook.org/ns/docbook'>
...
...
@@ -850,14 +1069,24 @@ purposes.</simpara></warning>'>
850
1069
<entry>8.0.0</entry>
851
1070
<entry>
852
1071
<parameter>image</parameter> expects a <classname>GdImage</classname>
853
-
instance now; previously, a <type>resource</type> was expected.
1072
+
instance now; previously, a valid <literal>gd</literal> <type>resource</type> was expected.
854
1073
</entry>
855
1074
</row>'>
856
1075
1076
+
<!-- CSV -->
1077
+
<!ENTITY warning.csv.escape-parameter '<warning xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"><simpara>
1078
+
When <parameter>escape</parameter> is set to anything other than an empty string
1079
+
(<literal>""</literal>) it can result in CSV that is not compliant with
1080
+
<link xlink:href="&url.rfc;4180">RFC 4180</link> or unable to survive a roundtrip
1081
+
through the PHP CSV functions. The default for <parameter>escape</parameter> is
1082
+
<literal>"\\"</literal> so it is recommended to set it to the empty string explicitly.
1083
+
The default value will change in a future version of PHP, no earlier than PHP 9.0.
1084
+
</simpara></warning>'>
1085
+
857
1086
<!-- DBM notes -->
858
1087
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,
1088
+
<!ENTITY dbm.dbm-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1089
+
<parameter>dbm_identifier</parameter></term><listitem><para>The DBM link identifier,
861
1090
returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
862
1091
863
1092
<!-- JSON notes -->
...
...
@@ -909,6 +1138,16 @@ returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
909
1138
</entry>
910
1139
</row>'>
911
1140
1141
+
<!-- dba notes -->
1142
+
<!ENTITY dba.parameter.dba 'A <classname xmlns="http://docbook.org/ns/docbook">Dba\Connection</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">dba_open</function> or <function xmlns="http://docbook.org/ns/docbook">dba_popen</function>.'>
1143
+
<!ENTITY dba.changelog.dba-object '<row xmlns="http://docbook.org/ns/docbook">
1144
+
<entry>8.4.0</entry>
1145
+
<entry>
1146
+
The <parameter>dba</parameter> parameter expects a <classname>Dba\Connection</classname>
1147
+
instance now; previously, a valid <literal>dba</literal> &resource; was expected.
1148
+
</entry>
1149
+
</row>'>
1150
+
912
1151
<!-- dbase notes -->
913
1152
914
1153
<!ENTITY dbase.type-conversion '<para xmlns="http://docbook.org/ns/docbook">
...
...
@@ -979,8 +1218,20 @@ returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>
979
1218
980
1219
<!-- IMAP notes -->
981
1220
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
1221
+
<!ENTITY imap.changelog.imap-param '<row xmlns="http://docbook.org/ns/docbook">
1222
+
<entry>8.1.0</entry>
1223
+
<entry>
1224
+
The <parameter>imap</parameter> parameter expects an <classname>IMAP\Connection</classname>
1225
+
instance now; previously, a valid <literal>imap</literal> &resource; was expected.
1226
+
</entry>
1227
+
</row>'>
1228
+
1229
+
<!ENTITY imap.imap-parameter.imap '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1230
+
<parameter>imap</parameter></term><listitem><para>An <classname>IMAP\Connection</classname> instance.</para></listitem></varlistentry>'>
1231
+
1232
+
<!-- Deprecated -->
1233
+
<!ENTITY imap.imap-stream.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1234
+
<parameter>imap</parameter></term><listitem><para>An IMAP stream returned by
984
1235
<function>imap_open</function>.</para></listitem></varlistentry>'>
985
1236
986
1237
<!ENTITY imap.pattern '<para xmlns="http://docbook.org/ns/docbook">Specifies where in the mailbox hierarchy
...
...
@@ -1003,9 +1254,13 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1003
1254
1004
1255
<!-- intl notes -->
1005
1256
1257
+
<!ENTITY intl.parameter.intl-calendar '<para xmlns="http://docbook.org/ns/docbook">An <classname>IntlCalendar</classname> instance.</para>'>
1258
+
1259
+
<!ENTITY intl.error.intl-calendar '<para xmlns="http://docbook.org/ns/docbook">On failure &false; is also returned. To detect error conditions use <function>intl_get_error_code</function>, or set up Intl to throw <link linkend="ini.intl.use-exceptions">exceptions</link>.</para>'>
1260
+
1006
1261
<!ENTITY intl.codepoint.parameter '<para xmlns="http://docbook.org/ns/docbook">The <type>int</type> codepoint value (e.g. <literal>0x2603</literal> for <emphasis>U+2603 SNOWMAN</emphasis>), or the character encoded as a UTF-8 <type>string</type> (e.g. <literal>"\u{2603}"</literal>)</para>'>
1007
1262
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>'>
1263
+
<!ENTITY intl.codepoint.return '<para xmlns="http://docbook.org/ns/docbook">The return type is <type>int</type> unless the code point was passed as a UTF-8 <type>string</type>, in which case a <type>string</type> is returned. Returns &null; on failure.</para>'>
1009
1264
1010
1265
<!ENTITY intl.codepoint.example 'Testing different code points'>
1011
1266
...
...
@@ -1017,9 +1272,11 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1017
1272
1018
1273
<!-- LDAP notes -->
1019
1274
1020
-
<!ENTITY ldap.parameter.ldap 'An LDAP resource, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_connect</function>.'>
1275
+
<!ENTITY ldap.parameter.ldap 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\Connection</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_connect</function>.'>
1021
1276
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>.'>
1277
+
<!ENTITY ldap.parameter.result 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_list</function> or <function xmlns="http://docbook.org/ns/docbook">ldap_search</function>.'>
1278
+
1279
+
<!ENTITY ldap.parameter.entry 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\ResultEntry</classname> instance.'>
1023
1280
1024
1281
<!ENTITY ldap.warn.control-paged '<warning xmlns="http://docbook.org/ns/docbook">
1025
1282
<simpara>
...
...
@@ -1036,6 +1293,56 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
1036
1293
</entry>
1037
1294
</row>'>
1038
1295
1296
+
<!ENTITY ldap.changelog.ldap-object '<row xmlns="http://docbook.org/ns/docbook">
1297
+
<entry>8.1.0</entry>
1298
+
<entry>
1299
+
The <parameter>ldap</parameter> parameter expects an <classname>LDAP\Connection</classname>
1300
+
instance now; previously, a valid <literal>ldap link</literal> &resource; was expected.
1301
+
</entry>
1302
+
</row>'>
1303
+
1304
+
<!ENTITY ldap.changelog.entry-object '<row xmlns="http://docbook.org/ns/docbook">
1305
+
<entry>8.1.0</entry>
1306
+
<entry>
1307
+
The <parameter>entry</parameter> parameter expects an <classname>LDAP\ResultEntry</classname>
1308
+
instance now; previously, a valid <literal>ldap result entry</literal> &resource; was expected.
1309
+
</entry>
1310
+
</row>'>
1311
+
1312
+
<!ENTITY ldap.changelog.result-object '<row xmlns="http://docbook.org/ns/docbook">
1313
+
<entry>8.1.0</entry>
1314
+
<entry>
1315
+
The <parameter>result</parameter> parameter expects an <classname>LDAP\Result</classname>
1316
+
instance now; previously, a valid <literal>ldap result</literal> &resource; was expected.
1317
+
</entry>
1318
+
</row>'>
1319
+
1320
+
<!ENTITY ldap.changelog.return-result-object '<row xmlns="http://docbook.org/ns/docbook">
1321
+
<entry>8.1.0</entry>
1322
+
<entry>
1323
+
Returns an <classname>LDAP\Result</classname> instance now;
1324
+
previously, a &resource; was returned.
1325
+
</entry>
1326
+
</row>'>
1327
+
1328
+
<!ENTITY ldap.changelog.return-result-entry-object '<row xmlns="http://docbook.org/ns/docbook">
1329
+
<entry>8.1.0</entry>
1330
+
<entry>
1331
+
Returns an <classname>LDAP\ResultEntry</classname> instance now;
1332
+
previously, a &resource; was returned.
1333
+
</entry>
1334
+
</row>'>
1335
+
1336
+
<!ENTITY ldap.return-result 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance,&return.falseforfailure;.'>
1337
+
<!ENTITY ldap.return-result-array 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance, an array of <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instances,&return.falseforfailure;.'>
1338
+
1339
+
<!ENTITY ldap.return-result-array-info '<para xmlns="http://docbook.org/ns/docbook">It is also possible to perform parallel searches. In this case, the first argument should be an array of
1340
+
<classname>LDAP\Connection</classname> instances, rather than a single one.
1341
+
If the searches should not all use the same base DN and filter, an array of base DNs and/or an array of filters can be passed as arguments instead.
1342
+
These arrays must be of the same size as the <classname>LDAP\Connection</classname> instances array,
1343
+
since the first entries of the arrays are used for one search, the second entries are used for another, and so on.
1344
+
When doing parallel searches an array of <classname>LDAP\Result</classname> instances is returned, except in case of error, when the return value will be &false;.</para>'>
1345
+
1039
1346
<!-- mbstring notes -->
1040
1347
1041
1348
<!ENTITY note.mbstring.encoding.internal '<note xmlns="http://docbook.org/ns/docbook"><para>The internal encoding or the
...
...
@@ -1059,6 +1366,13 @@ encoding value will be used.</para>'>
1059
1366
</entry>
1060
1367
</row>'>
1061
1368
1369
+
<!ENTITY mbstring.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
1370
+
<entry>8.0.0</entry>
1371
+
<entry>
1372
+
<parameter>needle</parameter> now accepts an empty string.
1373
+
</entry>
1374
+
</row>'>
1375
+
1062
1376
<!-- mcrypt notes -->
1063
1377
1064
1378
<!ENTITY mcrypt.parameter.cipher '<para xmlns="http://docbook.org/ns/docbook">One of the <constant>MCRYPT_ciphername</constant> constants, or the name of the algorithm as string.</para>'>
...
...
@@ -1071,12 +1385,20 @@ encoding value will be used.</para>'>
1071
1385
1072
1386
<!-- MCVE notes -->
1073
1387
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
1388
+
<!ENTITY mcve.conn.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1389
+
<parameter>conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
1076
1390
<function>m_initengine</function>.</para></listitem></varlistentry>'>
1077
1391
1078
1392
<!-- memcached notes -->
1079
1393
1394
+
<!ENTITY memcached.note.delete-time '<note xmlns="http://docbook.org/ns/docbook"><simpara>
1395
+
As of memcached 1.3.0 (released 2009) this feature is no longer
1396
+
supported. Passing a non-zero <parameter>time</parameter> will cause
1397
+
the deletion to fail. <methodname>Memcached::getResultCode</methodname>
1398
+
will return <constant>MEMCACHED_INVALID_ARGUMENTS</constant>.
1399
+
</simpara></note>
1400
+
'>
1401
+
1080
1402
<!ENTITY memcached.parameter.expiration 'The expiration time, defaults to 0. See <link
1081
1403
linkend="memcached.expiration" xmlns="http://docbook.org/ns/docbook">Expiration Times</link> for more info.'>
1082
1404
...
...
@@ -1090,6 +1412,19 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
1090
1412
1091
1413
<!ENTITY memcached.result.getresultcode 'Use <methodname xmlns="http://docbook.org/ns/docbook">Memcached::getResultCode</methodname> if necessary.'>
1092
1414
1415
+
<!ENTITY memcached.result.delete-multi '<para xmlns="http://docbook.org/ns/docbook">
1416
+
Returns an array indexed by <parameter>keys</parameter>. Each element
1417
+
is &true; if the corresponding key was deleted, or one of the
1418
+
<constant>Memcached::RES_<replaceable>*</replaceable></constant> constants if the corresponding deletion
1419
+
failed.
1420
+
</para>
1421
+
<para xmlns="http://docbook.org/ns/docbook">
1422
+
The <methodname>Memcached::getResultCode</methodname> will return
1423
+
the result code for the last executed delete operation, that is, the delete
1424
+
operation for the last element of <parameter>keys</parameter>.
1425
+
</para>
1426
+
'>
1427
+
1093
1428
<!-- password notes -->
1094
1429
1095
1430
<!ENTITY password.parameter.algo 'A <link xmlns="http://docbook.org/ns/docbook" linkend="password.constants">password algorithm constant</link> denoting the algorithm to use when hashing the password.'>
...
...
@@ -1100,6 +1435,36 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
1100
1435
1101
1436
<!ENTITY password.parameter.password 'The user's password.'>
1102
1437
1438
+
<!-- pspell notes -->
1439
+
1440
+
<!ENTITY pspell.changelog.pspell-dictionary '<row xmlns="http://docbook.org/ns/docbook">
1441
+
<entry>8.1.0</entry>
1442
+
<entry>
1443
+
The <parameter>dictionary</parameter> parameter expects an <classname>PSpell\Dictionary</classname>
1444
+
instance now; previously, a &resource; was expected.
1445
+
</entry>
1446
+
</row>'>
1447
+
1448
+
<!ENTITY pspell.changelog.pspell-config '<row xmlns="http://docbook.org/ns/docbook">
1449
+
<entry>8.1.0</entry>
1450
+
<entry>
1451
+
The <parameter>config</parameter> parameter expects an <classname>PSpell\Config</classname>
1452
+
instance now; previously, a &resource; was expected.
1453
+
</entry>
1454
+
</row>'>
1455
+
1456
+
<!ENTITY pspell.parameter.pspell-dictionary '<para xmlns="http://docbook.org/ns/docbook">An <classname>PSpell\Dictionary</classname> instance.</para>'>
1457
+
1458
+
<!ENTITY pspell.parameter.pspell-config '<para xmlns="http://docbook.org/ns/docbook">An <classname>PSpell\Config</classname> instance.</para>'>
1459
+
1460
+
<!-- RNP -->
1461
+
1462
+
<!ENTITY rnp.parameter.ffi-description 'The FFI object returned by <function xmlns="http://docbook.org/ns/docbook">rnp_ffi_create</function>.'>
1463
+
1464
+
<!ENTITY rnp.parameter.key-format 'The key format of the data (GPG, KBX, G10).'>
1465
+
1466
+
<!ENTITY rnp.parameter.loadsave-flags 'See <constant xmlns="http://docbook.org/ns/docbook">RNP_LOAD_SAVE_<replaceable>*</replaceable></constant> flags description.'>
1467
+
1103
1468
<!-- socket entities -->
1104
1469
1105
1470
<!ENTITY sockets.changelog.socket-param '<row xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1136,6 +1501,49 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by
1136
1501
1137
1502
<!ENTITY gearman.parameter.jobhandle 'The job handle assigned by the Gearman server'>
1138
1503
1504
+
<!ENTITY gearman.parameter.callback '<varlistentry xmlns="http://docbook.org/ns/docbook">
1505
+
<term><parameter>callback</parameter></term>
1506
+
<listitem>
1507
+
<para>
1508
+
A function or method to call.
1509
+
It should return a valid <link linkend="gearman.constants">Gearman return value</link>.
1510
+
</para>
1511
+
<para>
1512
+
If no return statement is present, it defaults to <constant>GEARMAN_SUCCESS</constant>.
1513
+
</para>
1514
+
<methodsynopsis>
1515
+
<type>int</type><methodname><replaceable>callback</replaceable></methodname>
1516
+
<methodparam><type>GearmanTask</type><parameter>task</parameter></methodparam>
1517
+
<methodparam><type>mixed</type><parameter>context</parameter></methodparam>
1518
+
</methodsynopsis>
1519
+
<variablelist>
1520
+
<varlistentry>
1521
+
<term><parameter>task</parameter></term>
1522
+
<listitem>
1523
+
<para>
1524
+
The task this callback is called for.
1525
+
</para>
1526
+
</listitem>
1527
+
</varlistentry>
1528
+
<varlistentry>
1529
+
<term><parameter>context</parameter></term>
1530
+
<listitem>
1531
+
<para>
1532
+
Whatever has been passed to <methodname>GearmanClient::addTask</methodname> (or equivalent method) as <parameter>context</parameter>.
1533
+
</para>
1534
+
</listitem>
1535
+
</varlistentry>
1536
+
</variablelist>
1537
+
</listitem>
1538
+
</varlistentry>'>
1539
+
1540
+
<!ENTITY gearman.note.callback '<note xmlns="http://docbook.org/ns/docbook">
1541
+
<para>
1542
+
The callback will only be triggered for tasks that are added (e.g. by calling <methodname>GearmanClient::addTask</methodname>)
1543
+
after calling this method.
1544
+
</para>
1545
+
</note>'>
1546
+
1139
1547
<!-- Date and time entities -->
1140
1548
<!ENTITY date.timezone.intro.title '<title xmlns="http://docbook.org/ns/docbook">List of Supported Timezones</title>'>
1141
1549
...
...
@@ -1201,11 +1609,14 @@ returned by <function>date_create</function></para></listitem></varlistentry>'>
1201
1609
returned by <function>date_create</function>.
1202
1610
The function modifies this object.</para></listitem></varlistentry>'>
1203
1611
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
1612
+
<!ENTITY date.datetimezone.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
1613
+
<parameter>object</parameter></term><listitem><para>Procedural style only: A <classname>DateTimeZone</classname> object
1206
1614
returned by <function>timezone_open</function></para></listitem></varlistentry>'>
1207
1615
1208
-
<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining&return.falseforfailure;.'>
1616
+
<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the modified <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining&return.falseforfailure;.'>
1617
+
<!ENTITY date.datetime.return.modifiedobject 'Returns the modified <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining.'>
1618
+
<!ENTITY date.datetimeimmutable.return.modifiedobjectorfalseforfailure 'Returns a new <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object with the modified data &return.falseforfailure;.'>
1619
+
<!ENTITY date.datetimeimmutable.return.modifiedobject 'Returns a new <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object with the modified data.'>
1209
1620
1210
1621
<!ENTITY date.timezone.dbversion 'This list is based upon the timezone database version'>
1211
1622
...
...
@@ -1225,21 +1636,68 @@ returned by <function>timezone_open</function></para></listitem></varlistentry>'
1225
1636
<!ENTITY date.formats 'Valid formats are explained in <link xmlns="http://docbook.org/ns/docbook" linkend="datetime.formats">Date and Time Formats</link>.'>
1226
1637
<!ENTITY date.formats.parameter 'A date/time string. &date.formats;'>
1227
1638
1228
-
<!-- DomXml Notes -->
1229
-
<!ENTITY node.inserted 'This node will not show up in the document unless it
1230
-
is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">domnode_append_child</function>.'>
1231
-
1232
-
1233
1639
<!-- Dom Notes -->
1234
1640
<!ENTITY dom.node.inserted 'This node will not show up in the document unless
1235
1641
it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNode::appendChild</function>.'>
1236
1642
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
1643
<!ENTITY dom.malformederror '<para xmlns="http://docbook.org/ns/docbook">While malformed HTML should load successfully, this function may generate <constant>E_WARNING</constant> errors when it encounters bad markup. <link linkend="function.libxml-use-internal-errors">libxml's error handling functions</link> may be used to handle these errors.</para>'>
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>'>
1644
+
<!ENTITY dom.note.utf8 '<note xmlns="http://docbook.org/ns/docbook"><para>The DOM extension uses UTF-8 encoding. Use <function>mb_convert_encoding</function>, <methodname>UConverter::transcode</methodname>, or <function>iconv</function> to handle other encodings.</para></note>'>
1645
+
<!ENTITY dom.note.modern.utf8 '<note xmlns="http://docbook.org/ns/docbook">
1646
+
<simpara>
1647
+
The DOM extension uses UTF-8 encoding when working with methods or properties.
1648
+
The parser methods auto-detect the encoding or allow the caller to specify an encoding.
1649
+
</simpara>
1650
+
</note>'>
1242
1651
<!ENTITY dom.note.json '<note xmlns="http://docbook.org/ns/docbook"><para>When using <function>json_encode</function> on a <classname>DOMDocument</classname> object the result will be that of encoding an empty object.</para></note>'>
1652
+
<!ENTITY dom.domdocument.html5 '<warning xmlns="http://docbook.org/ns/docbook">
1653
+
<simpara>
1654
+
Use <classname>Dom\HTMLDocument</classname> to parse and process modern HTML
1655
+
instead of <classname>DOMDocument</classname>.
1656
+
</simpara>
1657
+
<simpara>
1658
+
This function parses the input using an HTML 4 parser. The parsing rules
1659
+
of HTML 5, which is what modern web browsers use, are different. Depending
1660
+
on the input this might result in a different DOM structure. Therefore
1661
+
this function cannot be safely used for sanitizing HTML.
1662
+
</simpara>
1663
+
<simpara>
1664
+
The behavior when parsing HTML can depend on the version of
1665
+
<literal>libxml</literal> that is being used, particularly with regards to
1666
+
edge conditions and error handling.
1667
+
For parsing that conforms to the HTML5 specification,
1668
+
use <methodname>Dom\HTMLDocument::createFromString</methodname> or
1669
+
<methodname>Dom\HTMLDocument::createFromFile</methodname>, added in PHP 8.4.
1670
+
</simpara>
1671
+
<simpara>
1672
+
As an example, some HTML elements will implicitly close a parent element
1673
+
when encountered. The rules for automatically closing parent elements
1674
+
differ between HTML 4 and HTML 5 and thus the resulting DOM structure that
1675
+
<classname>DOMDocument</classname> sees might be different from the DOM
1676
+
structure a web browser sees, possibly allowing an attacker to break the
1677
+
resulting HTML.
1678
+
</simpara>
1679
+
</warning>'>
1680
+
<!ENTITY dom.tokenlist.errors '<itemizedlist xmlns="http://docbook.org/ns/docbook">
1681
+
<listitem>
1682
+
<simpara>
1683
+
Throws a <exceptionname>ValueError</exceptionname> if
1684
+
a token contains any null bytes.
1685
+
</simpara>
1686
+
</listitem>
1687
+
<listitem>
1688
+
<simpara>
1689
+
Throws a <exceptionname>Dom\DOMException</exceptionname> with code
1690
+
<constant>Dom\SYNTAX_ERR</constant> if a token is the empty string.
1691
+
</simpara>
1692
+
</listitem>
1693
+
<listitem>
1694
+
<simpara>
1695
+
Throws a <exceptionname>Dom\DOMException</exceptionname> with code
1696
+
<constant>Dom\INVALID_CHARACTER_ERR</constant> if a token contains any
1697
+
ASCII whitespace.
1698
+
</simpara>
1699
+
</listitem>
1700
+
</itemizedlist>'>
1243
1701
1244
1702
1245
1703
...
...
@@ -1277,38 +1735,160 @@ As of PHP 8.0.0 calling this method statically throws an <classname>Error</class
1277
1735
</books>
1278
1736
]]></programlisting>'>
1279
1737
1280
-
1281
-
<!-- FileSystem entities -->
1282
-
<!ENTITY fs.emits.warning.on.failure '<para xmlns="http://docbook.org/ns/docbook">
1283
-
Upon failure, an <constant>E_WARNING</constant> is emitted.
1738
+
<!-- Dom entities -->
1739
+
<!ENTITY dom.parameter.options '<para xmlns="http://docbook.org/ns/docbook">
1740
+
<link linkend="language.operators.bitwise">Bitwise <literal>OR</literal></link>
1741
+
of the <link linkend="libxml.constants">libxml option constants</link>.
1284
1742
</para>'>
1285
1743
1286
-
<!ENTITY fs.validfp.all '<para xmlns="http://docbook.org/ns/docbook">The file pointer must be valid, and must point to
1287
-
a file successfully opened by <function>fopen</function> or
1288
-
<function>fsockopen</function> (and not yet closed by
1289
-
<function>fclose</function>).</para>'>
1744
+
<!ENTITY dom.parameter.compliant.options '&dom.parameter.options;
1745
+
<simpara xmlns="http://docbook.org/ns/docbook">
1746
+
It is also possible to pass <constant>Dom\HTML_NO_DEFAULT_NS</constant>
1747
+
to disable the use of the HTML namespace and the template element.
1748
+
This should only be used if the implications are properly understood.
1749
+
</simpara>'>
1290
1750
1291
-
<!ENTITY fs.file.pointer '<para xmlns="http://docbook.org/ns/docbook">A file system pointer <type>resource</type>
1292
-
that is typically created using <function>fopen</function>.</para>'>
1751
+
<!ENTITY dom.parameter.compliant.encoding '<simpara xmlns="http://docbook.org/ns/docbook">
1752
+
The encoding that the document was created in.
1753
+
If not provided, it will attempt to determine the encoding that is most likely used.
1754
+
</simpara>'>
1293
1755
1294
-
<!ENTITY fs.file.32bit '<note xmlns="http://docbook.org/ns/docbook"><simpara>
1295
-
Because PHP's integer type is signed and many platforms use 32bit integers,
1296
-
some filesystem functions may return unexpected results for files which
1297
-
are larger than 2GB.
1298
-
</simpara></note>'>
1756
+
<!ENTITY dom.parser.compliant.note.whitespace '<refsect1 role="notes" xmlns="http://docbook.org/ns/docbook">
1757
+
&reftitle.notes;
1758
+
<note>
1759
+
<simpara>
1760
+
Whitespace in the <literal>html</literal> and <literal>head</literal> tags
1761
+
is not considered significant and may lose formatting.
1762
+
</simpara>
1763
+
</note>
1764
+
</refsect1>'>
1299
1765
1300
-
<!ENTITY ini.scanner.typed '<para xmlns="http://docbook.org/ns/docbook">
1301
-
As of PHP 5.6.1 can also be specified as <constant>INI_SCANNER_TYPED</constant>.
1302
-
In this mode boolean, null and integer types are preserved when possible.
1303
-
String values <literal>"true"</literal>, <literal>"on"</literal> and <literal>"yes"</literal>
1304
-
are converted to &true;. <literal>"false"</literal>, <literal>"off"</literal>, <literal>"no"</literal>
1305
-
and <literal>"none"</literal> are considered &false;. <literal>"null"</literal> is converted to &null;
1306
-
in typed mode. Also, all numeric strings are converted to integer type if it is possible.
1307
-
</para>'>
1766
+
<!ENTITY dom.parameters.register_node_ns '<varlistentry xmlns="http://docbook.org/ns/docbook">
1767
+
<term><parameter>registerNodeNS</parameter></term>
1768
+
<listitem>
1769
+
<para>
1770
+
Whether to automatically register the in-scope namespace prefixes of the context node to the <classname>DOMXPath</classname> object.
1771
+
This can be used to avoid needing to call <methodname>DOMXPath::registerNamespace</methodname> manually for each in-scope namespaces.
1772
+
When a namespace prefix conflict exists, only the nearest descendant namespace prefix is registered.
1773
+
</para>
1774
+
</listitem>
1775
+
</varlistentry>'>
1308
1776
1309
-
<!-- GNUPG -->
1310
-
<!ENTITY gnupg.identifier '<para xmlns="http://docbook.org/ns/docbook">The gnupg identifier, from a call to
1311
-
<function>gnupg_init</function> or <classname>gnupg</classname>.</para>'>
1777
+
<!ENTITY dom.parameters.serialize.options '<simpara xmlns="http://docbook.org/ns/docbook">
1778
+
Additional Options.
1779
+
The <constant>LIBXML_NOEMPTYTAG</constant>
1780
+
and <constant>LIBXML_NOXMLDECL</constant> options are supported.
1781
+
Prior to PHP 8.3.0, only the <constant>LIBXML_NOEMPTYTAG</constant>
1782
+
option is supported.
1783
+
</simpara>'>
1784
+
1785
+
<!ENTITY dom.errors.hierarchy.parent '<varlistentry xmlns="http://docbook.org/ns/docbook">
1786
+
<term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
1787
+
<listitem>
1788
+
<para>
1789
+
Raised if the parent is of a type that does not allow children of the
1790
+
type of one of the passed <parameter>nodes</parameter>, or if the node to
1791
+
put in is one of this node's ancestors or this node itself.
1792
+
</para>
1793
+
</listitem>
1794
+
</varlistentry>'>
1795
+
1796
+
<!ENTITY dom.errors.hierarchy.self '<varlistentry xmlns="http://docbook.org/ns/docbook">
1797
+
<term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
1798
+
<listitem>
1799
+
<para>
1800
+
Raised if this node is of a type that does not allow children of the
1801
+
type of one of the passed <parameter>nodes</parameter>, or if the node to
1802
+
put in is one of this node's ancestors or this node itself.
1803
+
</para>
1804
+
</listitem>
1805
+
</varlistentry>'>
1806
+
1807
+
<!ENTITY dom.errors.wrong_document '<varlistentry xmlns="http://docbook.org/ns/docbook">
1808
+
<term><constant>DOM_WRONG_DOCUMENT_ERR</constant></term>
1809
+
<listitem>
1810
+
<para>
1811
+
Raised if one of the passed <parameter>nodes</parameter> was created from a different
1812
+
document than the one that created this node.
1813
+
</para>
1814
+
</listitem>
1815
+
</varlistentry>'>
1816
+
1817
+
<!ENTITY dom.errors.compliant.wrong_document '<listitem xmlns="http://docbook.org/ns/docbook">
1818
+
<simpara>
1819
+
Throws a <exceptionname>Dom\DOMException</exceptionname> with code
1820
+
<constant>Dom\WRONG_DOCUMENT_ERR</constant> if <parameter>node</parameter>
1821
+
is from another document.
1822
+
</simpara>
1823
+
</listitem>'>
1824
+
1825
+
<!ENTITY dom.errors.compliant.common '<listitem xmlns="http://docbook.org/ns/docbook">
1826
+
<simpara>
1827
+
Throws a <exceptionname>ValueError</exceptionname> if
1828
+
<parameter>options</parameter> contains an invalid option.
1829
+
</simpara>
1830
+
</listitem>
1831
+
<listitem>
1832
+
<simpara>
1833
+
Throws a <exceptionname>ValueError</exceptionname> if
1834
+
<parameter>overrideEncoding</parameter> is an unknown encoding.
1835
+
</simpara>
1836
+
</listitem>'>
1837
+
1838
+
<!ENTITY dom.changelog.previous_hierarchy_exception 'Previously this threw a
1839
+
<classname xmlns="http://docbook.org/ns/docbook">DOMException</classname> with code
1840
+
<constant xmlns="http://docbook.org/ns/docbook">DOM_HIERARCHY_REQUEST_ERR</constant>.'>
1841
+
1842
+
<!ENTITY dom.c14n.xpath_array '<listitem xmlns="http://docbook.org/ns/docbook">
1843
+
<para>
1844
+
An array of XPaths to filter the nodes by.
1845
+
Each entry in this array is an associative array with:
1846
+
<itemizedlist>
1847
+
<listitem>
1848
+
<simpara>
1849
+
A required <literal>query</literal> key containing the XPath expression as a string.
1850
+
</simpara>
1851
+
</listitem>
1852
+
<listitem>
1853
+
<simpara>
1854
+
An optional <literal>namespaces</literal> key containing an array that maps namespace prefixes (keys) to namespace URIs (values).
1855
+
</simpara>
1856
+
</listitem>
1857
+
</itemizedlist>
1858
+
</para>
1859
+
</listitem>'>
1860
+
1861
+
<!-- FileSystem entities -->
1862
+
<!ENTITY fs.emits.warning.on.failure '<para xmlns="http://docbook.org/ns/docbook">
1863
+
Upon failure, an <constant>E_WARNING</constant> is emitted.
1864
+
</para>'>
1865
+
1866
+
<!ENTITY fs.validfp.all '<para xmlns="http://docbook.org/ns/docbook">The file pointer must be valid, and must point to
1867
+
a file successfully opened by <function>fopen</function> or
1868
+
<function>fsockopen</function> (and not yet closed by
1869
+
<function>fclose</function>).</para>'>
1870
+
1871
+
<!ENTITY fs.file.pointer '<para xmlns="http://docbook.org/ns/docbook">A file system pointer <type>resource</type>
1872
+
that is typically created using <function>fopen</function>.</para>'>
1873
+
1874
+
<!ENTITY fs.file.32bit '<note xmlns="http://docbook.org/ns/docbook"><simpara>
1875
+
Because PHP's integer type is signed and many platforms use 32bit integers,
1876
+
some filesystem functions may return unexpected results for files which
1877
+
are larger than 2GB.
1878
+
</simpara></note>'>
1879
+
1880
+
<!ENTITY ini.scanner.typed '<para xmlns="http://docbook.org/ns/docbook">
1881
+
As of PHP 5.6.1 can also be specified as <constant>INI_SCANNER_TYPED</constant>.
1882
+
In this mode boolean, null and integer types are preserved when possible.
1883
+
String values <literal>"true"</literal>, <literal>"on"</literal> and <literal>"yes"</literal>
1884
+
are converted to &true;. <literal>"false"</literal>, <literal>"off"</literal>, <literal>"no"</literal>
1885
+
and <literal>"none"</literal> are considered &false;. <literal>"null"</literal> is converted to &null;
1886
+
in typed mode. Also, all numeric strings are converted to integer type if it is possible.
1887
+
</para>'>
1888
+
1889
+
<!-- GNUPG -->
1890
+
<!ENTITY gnupg.identifier '<para xmlns="http://docbook.org/ns/docbook">The gnupg identifier, from a call to
1891
+
<function>gnupg_init</function> or <classname>gnupg</classname>.</para>'>
1312
1892
1313
1893
<!ENTITY gnupg.fingerprint '<para xmlns="http://docbook.org/ns/docbook">The fingerprint key.</para>'>
1314
1894
...
...
@@ -1316,9 +1896,15 @@ that is typically created using <function>fopen</function>.</para>'>
1316
1896
<!ENTITY haru.error '<para xmlns="http://docbook.org/ns/docbook">Throws a <classname>HaruException</classname> on error.</para>'>
1317
1897
1318
1898
<!-- ODBC -->
1319
-
<!ENTITY odbc.connection.id '<para xmlns="http://docbook.org/ns/docbook">The ODBC connection identifier,
1899
+
<!ENTITY odbc.connection.id '<para xmlns="http://docbook.org/ns/docbook">The ODBC connection object,
1320
1900
see <function>odbc_connect</function> for details.</para>'>
1321
1901
1902
+
<!ENTITY odbc.result.object 'The ODBC result object'>
1903
+
1904
+
<!ENTITY odbc.result.object-return 'Returns an ODBC result object'>
1905
+
1906
+
<!ENTITY odbc.result.object-return-falseforfailure '&odbc.result.object-return;&return.falseforfailure;.'>
1907
+
1322
1908
<!ENTITY odbc.parameter.catalog 'The catalog ('qualifier' in ODBC 2 parlance).'>
1323
1909
1324
1910
<!ENTITY odbc.parameter.schema 'The schema ('owner' in ODBC 2 parlance).'>
...
...
@@ -1329,6 +1915,66 @@ and <literal xmlns="http://docbook.org/ns/docbook">_</literal> to match a single
1329
1915
1330
1916
<!ENTITY odbc.result.driver-specific 'Drivers can report additional columns.'>
1331
1917
1918
+
<!ENTITY odbc.changelog.connection-param '<row xmlns="http://docbook.org/ns/docbook">
1919
+
<entry>8.4.0</entry>
1920
+
<entry>
1921
+
<parameter>odbc</parameter> expects an <classname>Odbc\Connection</classname>
1922
+
instance now; previously, a <type>resource</type> was expected.
1923
+
</entry>
1924
+
</row>'>
1925
+
1926
+
<!ENTITY odbc.changelog.connection-return '&odbc.changelog.connection-param;
1927
+
<row xmlns="http://docbook.org/ns/docbook">
1928
+
<entry>8.4.0</entry>
1929
+
<entry>
1930
+
This function returns a <classname>Odbc\Connection</classname> instance now;
1931
+
previously, a <type>resource</type> was returned.
1932
+
</entry>
1933
+
</row>'>
1934
+
1935
+
<!ENTITY odbc.changelog.credential-params '<row xmlns="http://docbook.org/ns/docbook">
1936
+
<entry>8.4.0</entry>
1937
+
<entry>
1938
+
<parameter>user</parameter> and <parameter>password</parameter> are now nullable,
1939
+
they are now also optional and default to &null;.
1940
+
</entry>
1941
+
</row>
1942
+
<row xmlns="http://docbook.org/ns/docbook">
1943
+
<entry>8.4.0</entry>
1944
+
<entry>
1945
+
Previously, using an empty string for <parameter>password</parameter> would not include
1946
+
<literal>pwd</literal> in the generated connection string for <parameter>dsn</parameter>.
1947
+
It is now generated to include a <literal>pwd</literal> which has an empty string as its value.
1948
+
To restore the previous behaviour <parameter>password</parameter> can now be set to &null;.
1949
+
</entry>
1950
+
</row>
1951
+
<row xmlns="http://docbook.org/ns/docbook">
1952
+
<entry>8.4.0</entry>
1953
+
<entry>
1954
+
Previously, if <parameter>dsn</parameter> contained <literal>uid</literal> or <literal>pwd</literal>
1955
+
both <parameter>user</parameter> and <parameter>password</parameter> parameters were ignored.
1956
+
Now <parameter>user</parameter> is only ignored if <parameter>dsn</parameter> contains
1957
+
<literal>uid</literal>, and <parameter>password</parameter> is only ignored if
1958
+
<parameter>dsn</parameter> contains <literal>pwd</literal>.
1959
+
</entry>
1960
+
</row>'>
1961
+
1962
+
<!ENTITY odbc.changelog.result-param '<row xmlns="http://docbook.org/ns/docbook">
1963
+
<entry>8.4.0</entry>
1964
+
<entry>
1965
+
<parameter>statement</parameter> expects an <classname>Odbc\Result</classname>
1966
+
instance now; previously, a <type>resource</type> was expected.
1967
+
</entry>
1968
+
</row>'>
1969
+
1970
+
<!ENTITY odbc.changelog.result-return '<row xmlns="http://docbook.org/ns/docbook">
1971
+
<entry>8.4.0</entry>
1972
+
<entry>
1973
+
This function returns an <classname>Odbc\Result</classname>
1974
+
instance now; previously, a <type>resource</type> was returned.
1975
+
</entry>
1976
+
</row>'>
1977
+
1332
1978
<!-- OAUTH -->
1333
1979
<!ENTITY oauth.callback.error 'Emits an <constant xmlns="http://docbook.org/ns/docbook">E_ERROR</constant> level
1334
1980
error if the callback function cannot be called, or was not specified.'>
...
...
@@ -1343,7 +1989,7 @@ string</link>, or a Connect Name from
1343
1989
the <filename>tnsnames.ora</filename> file, or the name of a local
1344
1990
Oracle instance.
1345
1991
</para>
1346
-
<para xmlns='http://docbook.org/ns/docbook'>If not specified, PHP uses
1992
+
<para xmlns='http://docbook.org/ns/docbook'>If not specified or &null;, PHP uses
1347
1993
environment variables such as <constant>TWO_TASK</constant> (on Linux)
1348
1994
or <constant>LOCAL</constant> (on Windows)
1349
1995
and <constant>ORACLE_SID</constant> to determine the
...
...
@@ -1461,61 +2107,16 @@ call to <function>pcntl_waitpid</function>.</para>'>
1461
2107
is printed or viewed but it will show up if the document is converted to
1462
2108
pdf by either Acrobat Distiller™ or Ghostview.</para>'>
1463
2109
1464
-
<!-- Notes for safe-mode limited functions: -->
1465
-
1466
-
<!-- Not used in EN anymore -->
1467
-
<!ENTITY note.sm.disabled '<note xmlns="http://docbook.org/ns/docbook"><simpara>&sm.disabled;</simpara></note>'>
1468
-
1469
-
<!-- Not used in EN anymore -->
1470
-
<!ENTITY note.sm.uidcheck '<note xmlns="http://docbook.org/ns/docbook"><simpara>When <link
1471
-
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether
1472
-
the files or directories being operated upon have the same UID (owner) as the
1473
-
script that is being executed.</simpara></note>'>
1474
-
1475
-
<!-- Not used in EN anymore -->
1476
-
<!ENTITY note.sm.uidcheck.dir '<note xmlns="http://docbook.org/ns/docbook"><simpara>When <link
1477
-
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether
1478
-
the directory in which the script is operating has the same UID (owner) as the
1479
-
script that is being executed.</simpara></note>'>
1480
-
1481
2110
<!ENTITY note.open-basedir.func '<note xmlns="http://docbook.org/ns/docbook"><para>This function is affected by <link
1482
2111
linkend="ini.open-basedir">open_basedir</link>.</para></note>'>
1483
2112
1484
2113
1485
2114
<!ENTITY note.language-construct '<note xmlns="http://docbook.org/ns/docbook"><simpara>Because this is a
1486
2115
language construct and not a function, it cannot be called using
1487
-
<link linkend="functions.variable-functions">variable functions</link>.</simpara>
2116
+
<link linkend="functions.variable-functions">variable functions</link>,
2117
+
or <link linkend="functions.named-arguments">named arguments</link>.</simpara>
1488
2118
</note>'>
1489
2119
1490
-
<!-- Common pieces in features/safe-mode.xml
1491
-
Jade doesn't allow in-line entities, so I put them here... Though they
1492
-
should have been inline in safe-mode.xml -->
1493
-
1494
-
<!-- Not used in EN anymore -->
1495
-
<!ENTITY sm.uidcheck 'Checks whether the files or directories being operated
1496
-
upon have the same UID (owner) as the script that is being executed.'>
1497
-
1498
-
<!-- Not used in EN anymore -->
1499
-
<!ENTITY warn.sm.exec '<warning xmlns="http://docbook.org/ns/docbook"><simpara>With <link linkend="features.safe-mode">safe mode</link> enabled,
1500
-
the command string is escaped with <function>escapeshellcmd</function>. Thus,
1501
-
<literal>echo y | echo x</literal> becomes <literal>echo y \| echo x</literal>.</simpara></warning>'>
1502
-
1503
-
<!-- Not used in EN anymore -->
1504
-
<!ENTITY note.exec-path '<note xmlns="http://docbook.org/ns/docbook"><simpara>When
1505
-
<link linkend="features.safe-mode">safe mode</link> is enabled, you can only
1506
-
execute files within the <link linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
1507
-
For practical reasons, it is currently not allowed to have <literal>..</literal>
1508
-
components in the path to the executable.</simpara></note>'>
1509
-
1510
-
<!-- Not used in EN anymore -->
1511
-
<!ENTITY sm.uidcheck.dir 'Checks whether the directory in which
1512
-
the script is operating has the same UID (owner) as the script that is being
1513
-
executed.'>
1514
-
1515
-
<!-- Not used in EN anymore -->
1516
-
<!ENTITY sm.disabled 'This function is disabled when PHP is running in <link xmlns="http://docbook.org/ns/docbook"
1517
-
linkend="features.safe-mode">safe mode</link>.'>
1518
-
1519
2120
<!-- Common pieces in partintro-sections -->
1520
2121
<!ENTITY no.config '<para xmlns="http://docbook.org/ns/docbook">This extension has no configuration directives defined in &php.ini;.</para>'>
1521
2122
<!ENTITY no.resource '<para xmlns="http://docbook.org/ns/docbook">This extension has no resource types defined.</para>'>
...
...
@@ -1536,7 +2137,7 @@ The behaviour of these functions is affected by settings in &php.ini;.
1536
2137
</simpara>'>
1537
2138
1538
2139
<!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"/>.'>
2140
+
INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>
1540
2141
1541
2142
<!-- Used in reference/$extname/constants.xml -->
1542
2143
<!ENTITY extension.constants '<simpara xmlns="http://docbook.org/ns/docbook">
...
...
@@ -1557,9 +2158,6 @@ will only be available when the extension has either
1557
2158
been compiled into PHP or dynamically loaded at runtime.
1558
2159
</simpara>'>
1559
2160
1560
-
<!ENTITY note.extension.php5 '<note xmlns="http://docbook.org/ns/docbook"><simpara>
1561
-
This extension requires PHP 5.</simpara></note>'>
1562
-
1563
2161
<!-- PDO entities -->
1564
2162
<!ENTITY pdo.driver-constants '<simpara xmlns="http://docbook.org/ns/docbook">The constants below are defined by
1565
2163
this driver, and will only be available when the extension has been either
...
...
@@ -1572,12 +2170,21 @@ driver, if your code can run against multiple drivers.</simpara>'>
1572
2170
1573
2171
<!ENTITY pdo.errors.exception-not-errmode '<note xmlns="http://docbook.org/ns/docbook"><simpara>An exception is raised even when the <constant>PDO::ATTR_ERRMODE</constant> attribute is not <constant>PDO::ERRMODE_EXCEPTION</constant>.</simpara></note>'>
1574
2172
2173
+
<!-- PDO errors -->
2174
+
2175
+
<!ENTITY pdo.errors '<para xmlns="http://docbook.org/ns/docbook">
2176
+
Emits an error with level <constant>E_WARNING</constant> if the attribute <constant>PDO::ATTR_ERRMODE</constant> is set
2177
+
to <constant>PDO::ERRMODE_WARNING</constant>.
2178
+
</para>
2179
+
<para xmlns="http://docbook.org/ns/docbook">
2180
+
Throws a <classname>PDOException</classname> if the attribute <constant>PDO::ATTR_ERRMODE</constant>
2181
+
is set to <constant>PDO::ERRMODE_EXCEPTION</constant>.
2182
+
</para>'>
2183
+
1575
2184
<!-- 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.'>
2185
+
<!ENTITY pecl.moved 'This &link.pecl; extension is not bundled with PHP.'>
1578
2186
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.'>
2187
+
<!ENTITY pecl.bundled 'This &link.pecl; extension is bundled with PHP.'>
1581
2188
1582
2189
<!ENTITY pecl.info 'Information for installing this PECL extension may be
1583
2190
found in the manual chapter titled <link xmlns="http://docbook.org/ns/docbook" linkend="install.pecl">Installation
...
...
@@ -1603,9 +2210,81 @@ for this <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension
1603
2210
1604
2211
<!ENTITY pecl.windows.download.unbundled '&pecl.windows.download;'>
1605
2212
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 '>
2213
+
<!ENTITY pecl.moved-ver 'This extension has been moved to the &link.pecl;
2214
+
repository and is no longer bundled with PHP as of PHP '>
2215
+
2216
+
<!ENTITY pecl.moving.to.pie '<note xmlns="http://docbook.org/ns/docbook">
2217
+
<simpara>
2218
+
PHP Installer for Extensions (<acronym>PIE</acronym>) is a new tool that will deprecate PECL.
2219
+
We recommend using PIE to install extensions.
2220
+
Find out more at <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/php/pie">https://github.com/php/pie</link>
2221
+
</simpara>
2222
+
</note>'>
2223
+
2224
+
<!ENTITY warn.pecl.unmaintained '<warning xmlns="http://docbook.org/ns/docbook">
2225
+
<simpara>This extension is <emphasis>unmaintained</emphasis>.</simpara>
2226
+
</warning>'>
2227
+
2228
+
<!-- PGSQL entities -->
2229
+
2230
+
<!ENTITY pgsql.parameter.connection '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.</para>'>
2231
+
2232
+
<!ENTITY pgsql.parameter.connection-with-unspecified-default '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.
2233
+
When <parameter>connection</parameter> is unspecified, the default connection is used.
2234
+
The default connection is the last connection made by <function>pg_connect</function>
2235
+
or <function>pg_pconnect</function>.
2236
+
<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>
2237
+
2238
+
<!ENTITY pgsql.parameter.connection-with-nullable-default '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Connection</classname> instance.
2239
+
When <parameter>connection</parameter> is &null;, the default connection is used.
2240
+
The default connection is the last connection made by <function>pg_connect</function>
2241
+
or <function>pg_pconnect</function>.
2242
+
<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>
2243
+
2244
+
<!ENTITY pgsql.parameter.result '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Result</classname> instance, returned by <function>pg_query</function>,
2245
+
<function>pg_query_params</function> or <function>pg_execute</function>(among others).</para>'>
2246
+
2247
+
<!ENTITY pgsql.parameter.lob '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Lob</classname> instance, returned by <function>pg_lo_open</function>.</para>'>
2248
+
2249
+
<!ENTITY pgsql.parameter.mode '<para xmlns="http://docbook.org/ns/docbook">
2250
+
An optional parameter that controls how the returned <type>array</type> is indexed.
2251
+
<parameter>mode</parameter> is a constant and can take the following values:
2252
+
<constant>PGSQL_ASSOC</constant>, <constant>PGSQL_NUM</constant> and <constant>PGSQL_BOTH</constant>.
2253
+
Using <constant>PGSQL_NUM</constant>, the function will return an array with numerical indices,
2254
+
using <constant>PGSQL_ASSOC</constant> it will return only associative indices
2255
+
while <constant>PGSQL_BOTH</constant> will return both numerical and associative indices.</para>'>
2256
+
2257
+
<!ENTITY pgsql.changelog.connection-object '<row xmlns="http://docbook.org/ns/docbook">
2258
+
<entry>8.1.0</entry>
2259
+
<entry>
2260
+
The <parameter>connection</parameter> parameter expects an <classname>PgSql\Connection</classname>
2261
+
instance now; previously, a &resource; was expected.
2262
+
</entry>
2263
+
</row>'>
2264
+
2265
+
<!ENTITY pgsql.changelog.result-object '<row xmlns="http://docbook.org/ns/docbook">
2266
+
<entry>8.1.0</entry>
2267
+
<entry>
2268
+
The <parameter>result</parameter> parameter expects an <classname>PgSql\Result</classname>
2269
+
instance now; previously, a &resource; was expected.
2270
+
</entry>
2271
+
</row>'>
2272
+
2273
+
<!ENTITY pgsql.changelog.lob-object '<row xmlns="http://docbook.org/ns/docbook">
2274
+
<entry>8.1.0</entry>
2275
+
<entry>
2276
+
The <parameter>lob</parameter> parameter expects an <classname>PgSql\Lob</classname>
2277
+
instance now; previously, a &resource; was expected.
2278
+
</entry>
2279
+
</row>'>
2280
+
2281
+
<!ENTITY pgsql.changelog.return-result-object '<row xmlns="http://docbook.org/ns/docbook">
2282
+
<entry>8.1.0</entry>
2283
+
<entry>
2284
+
Returns an <classname>PgSql\Result</classname> instance now;
2285
+
previously, a &resource; was returned.
2286
+
</entry>
2287
+
</row>'>
1609
2288
1610
2289
<!-- Common pieces for reference part END -->
1611
2290
...
...
@@ -1619,22 +2298,6 @@ extensions in order to use these functions.</simpara>'>
1619
2298
1620
2299
<!ENTITY sqlsafemode '<link xmlns="http://docbook.org/ns/docbook" linkend="ini.sql.safe-mode">SQL safe mode</link>'>
1621
2300
1622
-
<!-- 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
1625
-
together the <literal>XXX_TRACE</literal> constants.</para><para>It is not recommended
1626
-
to use <constant>MEMORY_TRACE</constant>. It is very slow and does not appear to be accurate.
1627
-
<constant>ASSIGNMENT_TRACE</constant> is not implemented yet.</para><para>To turn on all
1628
-
functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the value 99</para>
1629
-
</listitem></varlistentry>'>
1630
-
1631
-
<!-- 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
1634
-
of digits after the decimal place in the result. If omitted, it will default to the scale set
1635
-
globally with the <function>bcscale</function> function, or fallback to <literal>0</literal> if
1636
-
this has not been set.</para></listitem></varlistentry>'>
1637
-
1638
2301
<!-- CTYPE Notes -->
1639
2302
<!ENTITY note.ctype.parameter.integer '<note xmlns="http://docbook.org/ns/docbook"><para>
1640
2303
If an <type>int</type> between -128 and 255 inclusive is provided, it is interpreted as
...
...
@@ -1642,21 +2305,44 @@ the ASCII value of a single character (negative values have 256 added in order t
1642
2305
characters in the Extended ASCII range). Any other integer is interpreted as a string
1643
2306
containing the decimal digits of the integer.</para></note>'>
1644
2307
2308
+
<!ENTITY note.ctype.parameter.non-string '<warning xmlns="http://docbook.org/ns/docbook"><para>
2309
+
As of PHP 8.1.0, passing a non-string argument is deprecated.
2310
+
In the future, the argument will be interpreted as a string instead of an ASCII codepoint.
2311
+
Depending on the intended behavior, the argument should either be cast to &string;
2312
+
or an explicit call to <function>chr</function> should be made.</para></warning>'>
2313
+
2314
+
<!ENTITY ctype.result.empty-string 'When called with an empty string the result will always be &false;.'>
2315
+
2316
+
<!-- FTP Notes -->
2317
+
<!ENTITY ftp.changelog.ftp-param '<row xmlns="http://docbook.org/ns/docbook">
2318
+
<entry>8.1.0</entry>
2319
+
<entry>
2320
+
The <parameter>ftp</parameter> parameter expects an <classname>FTP\Connection</classname>
2321
+
instance now; previously, a &resource; was expected.
2322
+
</entry>
2323
+
</row>'>
2324
+
<!ENTITY ftp.parameter.ftp '<para xmlns="http://docbook.org/ns/docbook">An <classname>FTP\Connection</classname> instance.</para>'>
2325
+
1645
2326
<!-- GMP Notes -->
1646
2327
<!ENTITY gmp.return 'A <classname xmlns="http://docbook.org/ns/docbook">GMP</classname> object.'>
1647
-
<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">A <classname>GMP</classname> object, an &integer; or a numeric &string;.</para>'>
2328
+
<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">
2329
+
A <classname>GMP</classname> object, an &integer;,
2330
+
or a &string; that can be interpreted as a number following the same logic
2331
+
as if the string was used in <function>gmp_init</function> with automatic
2332
+
base detection (i.e. when <parameter>base</parameter> is equal to 0).
2333
+
</para>'>
1648
2334
1649
2335
<!-- 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>
2336
+
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2337
+
<parameter>result</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_result</classname>
1652
2338
object returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>,
1653
2339
<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
2340
+
<!ENTITY mysqli.link.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2341
+
<parameter>mysql</parameter></term><listitem><para>Procedural style only: A <classname>mysqli</classname> object
1656
2342
returned by <function>mysqli_connect</function> or <function>mysqli_init</function>
1657
2343
</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
2344
+
<!ENTITY mysqli.stmt.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2345
+
<parameter>statement</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_stmt</classname> object
1660
2346
returned by <function>mysqli_stmt_init</function>.</para></listitem></varlistentry>'>
1661
2347
<!ENTITY mysqli.available.mysqlnd 'Available only with <link xmlns="http://docbook.org/ns/docbook"
1662
2348
linkend="book.mysqlnd">mysqlnd</link>.'>
...
...
@@ -1665,6 +2351,9 @@ linkend="book.mysqlnd">mysqlnd</link>.'>
1665
2351
hand-shake/authentication, which mysqlnd will use.</para><para>Libmysqlclient uses the default charset set in the
1666
2352
<filename>my.cnf</filename> or by an explicit call to <function>mysqli_options</function> prior to
1667
2353
calling <function>mysqli_real_connect</function>, but after <function>mysqli_init</function>.</para></note>'>
2354
+
<!ENTITY mysqli.integer.overflow.as.string.note '<note xmlns="http://docbook.org/ns/docbook">
2355
+
<para>If the number of rows is greater than <constant>PHP_INT_MAX</constant>,
2356
+
the number will be returned as a &string;.</para></note>'>
1668
2357
<!ENTITY mysqli.sqlinjection.warning '<warning xmlns="http://docbook.org/ns/docbook">
1669
2358
<title>Security warning: SQL injection</title><para>If the query contains any variable
1670
2359
input then <link linkend="mysqli.quickstart.prepared-statements">parameterized
...
...
@@ -1672,12 +2361,26 @@ prepared statements</link> should be used instead. Alternatively, the
1672
2361
data must be properly formatted and all strings must be escaped using
1673
2362
the <function>mysqli_real_escape_string</function>
1674
2363
function.</para></warning>'>
2364
+
<!ENTITY mysqli.conditionalexception '<para xmlns="http://docbook.org/ns/docbook">
2365
+
If mysqli error reporting is enabled (<constant>MYSQLI_REPORT_ERROR</constant>) and the requested operation fails,
2366
+
a warning is generated. If, in addition, the mode is set to <constant>MYSQLI_REPORT_STRICT</constant>,
2367
+
a <classname>mysqli_sql_exception</classname> is thrown instead.</para>'>
2368
+
2369
+
<!-- Notes for PCRE -->
2370
+
<!ENTITY pcre.pattern.warning '<para xmlns="http://docbook.org/ns/docbook">
2371
+
If the regex pattern passed does not compile to a valid regex, an <constant>E_WARNING</constant> is emitted.
2372
+
</para>'>
1675
2373
1676
2374
<!-- Notes for SAPI/Apache -->
1677
2375
<!ENTITY apache.req.module '<simpara xmlns="http://docbook.org/ns/docbook">This function is supported when PHP
1678
2376
is installed as an Apache module webserver.
1679
2377
</simpara>'>
1680
2378
2379
+
<!-- Notes for SAPI/FPM -->
2380
+
<!ENTITY fpm.intro '<para xmlns="http://docbook.org/ns/docbook">FPM (FastCGI Process Manager) is
2381
+
a primary PHP FastCGI implementation containing some features (mostly) useful for heavy-loaded sites.
2382
+
</para>'>
2383
+
1681
2384
<!-- SimpleXML Notes -->
1682
2385
<!ENTITY simplexml.iteration '<note xmlns="http://docbook.org/ns/docbook"><simpara>SimpleXML has made a rule of adding
1683
2386
iterative properties to most methods. They cannot be viewed using <function>var_dump</function>
...
...
@@ -1720,29 +2423,10 @@ are <emphasis>case-sensitive</emphasis>.</simpara></note>'>
1720
2423
<!ENTITY database.fetch-null '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function sets NULL fields to
1721
2424
the PHP &null; value.</simpara></note>'>
1722
2425
1723
-
<!-- MSQL Notes -->
1724
-
<!-- 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.
1727
-
If not specified, the last link opened by <function>msql_connect</function>
1728
-
is assumed. If no such link is found, the function will try to establish a
1729
-
link as if <function>msql_connect</function> was called, and use it.
1730
-
</para></listitem></varlistentry>'>
1731
-
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
1734
-
is being evaluated. This result comes from a call to
1735
-
<function>msql_query</function>.</para></listitem></varlistentry>'>
1736
-
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
1739
-
<parameter>field_offset</parameter> starts at <literal>1</literal>.</para></listitem></varlistentry>'>
1740
-
1741
-
1742
2426
<!-- MySQL Notes -->
1743
2427
<!-- 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
2428
+
<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2429
+
<parameter>link_identifier</parameter></term><listitem><para>The MySQL connection. If the
1746
2430
link identifier is not specified, the last link opened by
1747
2431
<function>mysql_connect</function> is assumed. If no such link is found, it
1748
2432
will try to create one as if <function>mysql_connect</function> had been called
...
...
@@ -1751,20 +2435,20 @@ with no arguments. If no connection is found or established, an
1751
2435
</varlistentry>'>
1752
2436
1753
2437
<!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
2438
+
xmlns="http://docbook.org/ns/docbook"><term>
2439
+
<parameter>link_identifier</parameter></term><listitem><para>The MySQL connection. If the
1756
2440
link identifier is not specified, the last link opened by
1757
2441
<function>mysql_connect</function> is assumed. If no connection is found or
1758
2442
established, an <constant>E_WARNING</constant> level error is
1759
2443
generated.</para></listitem></varlistentry>'>
1760
2444
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
2445
+
<!ENTITY mysql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2446
+
<parameter>result</parameter></term><listitem><para>The result <type>resource</type> that
1763
2447
is being evaluated. This result comes from a call to
1764
2448
<function>mysql_query</function>.</para></listitem></varlistentry>'>
1765
2449
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
2450
+
<!ENTITY mysql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2451
+
<parameter>field_offset</parameter></term><listitem><para>The numerical field offset. The
1768
2452
<parameter>field_offset</parameter> starts at <literal>0</literal>. If
1769
2453
<parameter>field_offset</parameter> does not exist, an error of level
1770
2454
<constant>E_WARNING</constant> is also issued.</para></listitem></varlistentry>'>
...
...
@@ -1806,40 +2490,6 @@ This will immediately return resources to PHP and MySQL, which can
1806
2490
improve performance. For related information, see
1807
2491
<link linkend="language.types.resource.self-destruct">freeing resources</link></para>'>
1808
2492
1809
-
<!-- Sybase Notes -->
1810
-
<!ENTITY sybase.ct.only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when
1811
-
using the CT library interface to Sybase, and not with the DB library.
1812
-
</simpara></note>'>
1813
-
1814
-
<!ENTITY sybase.db.only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when
1815
-
using the DB library interface to Sybase, and not with the CT library.</simpara></note>'>
1816
-
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
1819
-
link identifier is not specified, the last link opened by
1820
-
<function>sybase_connect</function> is assumed. If no such link is found, it
1821
-
will try to create one as if <function>sybase_connect</function> was called
1822
-
with no arguments. If no connection is found or established, an
1823
-
<constant>E_WARNING</constant> level error is generated.</para></listitem>
1824
-
</varlistentry>'>
1825
-
1826
-
<!-- CPDF Notes -->
1827
-
<!ENTITY cpdf.ul '<para xmlns="http://docbook.org/ns/docbook">The optional parameter <parameter>mode</parameter>
1828
-
determines the unit length. If it is <literal>0</literal> or omitted, the
1829
-
default unit as specified for the page is used. In other cases, the coordinates
1830
-
are measured in postscript points, disregarding the current unit.</para>'>
1831
-
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>
1834
-
determines the unit length. If it is <literal>0</literal> or omitted, the
1835
-
default unit as specified for the page is used. In other cases, the coordinates
1836
-
are measured in postscript points, disregarding the current unit.</para>
1837
-
</listitem></varlistentry>'>
1838
-
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
1841
-
<function>cpdf_open</function>.</para></listitem></varlistentry>'>
1842
-
1843
2493
<!-- Xattr entities -->
1844
2494
<!ENTITY xattr.namespace '<para xmlns="http://docbook.org/ns/docbook">Extended attributes have two different namespaces: user
1845
2495
and root. The user namespace is available to all users, while the root namespace
...
...
@@ -1852,9 +2502,6 @@ namespace by default, but this can be changed with the
1852
2502
(e.g. <literal>fe80::1</literal>), you must enclose the IP in square
1853
2503
brackets—for example, <literal>tcp://[fe80::1]:80</literal>.</simpara></note>'>
1854
2504
1855
-
<!ENTITY ipv6.php5 '<note xmlns="http://docbook.org/ns/docbook"><simpara>IPv6 Support was added in PHP 5.0.0.
1856
-
</simpara></note>'>
1857
-
1858
2505
<!-- Notes for tidy -->
1859
2506
<!ENTITY tidy.object 'The <classname xmlns="http://docbook.org/ns/docbook">Tidy</classname> object.'>
1860
2507
...
...
@@ -1879,6 +2526,15 @@ threaded MPM in production with Apache 2. Use the prefork MPM, which is
1879
2526
the default MPM with Apache 2.0 and 2.2.
1880
2527
For information on why, read the related FAQ entry on using
1881
2528
<link linkend="faq.installation.apache2">Apache2 with a threaded MPM</link></para></warning>'>
2529
+
<!ENTITY warn.install.third-party-support '<warning xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
2530
+
<para>
2531
+
Builds from third-parties are considered unofficial and not directly
2532
+
supported by the PHP project. Any bugs encountered should be reported to the
2533
+
provider of those unofficial builds unless they can be reproduced using the
2534
+
builds from <link xlink:href="&url.php.downloads;">the official download
2535
+
area</link>.
2536
+
</para>
2537
+
</warning>'>
1882
2538
1883
2539
<!ENTITY note.apache.slashes '<note xmlns="http://docbook.org/ns/docbook"><simpara>Remember that when adding
1884
2540
path values in the Apache configuration files on Windows, all backslashes
...
...
@@ -1889,10 +2545,9 @@ slash may also be necessary for directories.</simpara></note>'>
1889
2545
<!-- Snippets and titles for the contributors section -->
1890
2546
<!ENTITY Credit.Authors.and.Contributors 'Authors and Contributors'>
1891
2547
1892
-
<!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
2548
+
<!ENTITY Credit.Introduction '<para xmlns="http://docbook.org/ns/docbook"> There is a large number of contributors who
1894
2549
currently help in our work or have provided a great amount of help to the project
1895
-
in the past. There are a lot of unnamed people who help out with user
2550
+
in the past. There are also a lot of unnamed people who help out with user
1896
2551
notes on manual pages, which continually get included in the references, the
1897
2552
work of whom we are also very thankful for. All of the lists provided below are in
1898
2553
alphabetical order.
...
...
@@ -1916,23 +2571,11 @@ into managing user notes:'>
1916
2571
1917
2572
<!ENTITY listendand ' and'>
1918
2573
1919
-
<!-- classkit and runkit entities -->
1920
-
<!ENTITY note.classkit.selfmanipulation '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function cannot
1921
-
be used to manipulate the currently running (or chained) method.</simpara>
1922
-
</note>'>
1923
-
2574
+
<!-- runkit entities -->
1924
2575
<!ENTITY note.runkit.selfmanipulation '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function cannot
1925
2576
be used to manipulate the currently running (or chained) method.</simpara>
1926
2577
</note>'>
1927
2578
1928
-
<!ENTITY note.runkit.sandbox '<note xmlns="http://docbook.org/ns/docbook"><simpara>Sandbox support (required for
1929
-
<function>runkit_lint</function>, <function>runkit_lint_file</function>,
1930
-
and the <classname>Runkit_Sandbox</classname> class) is only available as of
1931
-
PHP 5.1.0 or specially patched versions of PHP 5.0, and requires that thread
1932
-
safety be enabled.
1933
-
See the <filename>README</filename> file included in the runkit package for
1934
-
more information.</simpara></note>'>
1935
-
1936
2579
<!ENTITY note.runkit.internal-override '<note xmlns="http://docbook.org/ns/docbook"><simpara>By default, only
1937
2580
userspace functions may be removed, renamed, or modified. In order to
1938
2581
override internal functions, you must enable the
...
...
@@ -1950,8 +2593,8 @@ using public key authentication, use the
1950
2593
<!ENTITY returns.session.storage.retval 'The return value (usually &true; on success, &false; on failure). Note this value is returned internally to PHP for processing.'>
1951
2594
1952
2595
<!-- 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.
2596
+
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
2597
+
<parameter>writer</parameter></term><listitem><para>Only for procedural calls.
1955
2598
The <classname>XMLWriter</classname> instance that is being modified. This object is returned from a call to <function>xmlwriter_open_uri</function> or <function>xmlwriter_open_memory</function>.</para></listitem></varlistentry>'>
1956
2599
1957
2600
<!ENTITY xmlwriter.changelog.writer-param '<row xmlns="http://docbook.org/ns/docbook">
...
...
@@ -2077,13 +2720,6 @@ The <classname>XMLWriter</classname> instance that is being modified. This objec
2077
2720
</para>
2078
2721
</note>
2079
2722
'>
2080
-
<!ENTITY com.use-oo-instead '<note xmlns="http://docbook.org/ns/docbook">
2081
-
<simpara>
2082
-
This function does not exist in PHP 5; instead, you should use the regular
2083
-
and more natural OO syntax to access properties or call methods.
2084
-
</simpara>
2085
-
</note>
2086
-
'>
2087
2723
2088
2724
<!-- phar -->
2089
2725
<!ENTITY phar.write '<note xmlns="http://docbook.org/ns/docbook"><para>This
...
...
@@ -2091,17 +2727,6 @@ method requires the &php.ini; setting <literal>phar.readonly</literal> to be
2091
2727
set to <literal>0</literal> in order to work for <classname>Phar</classname>
2092
2728
objects. Otherwise, a <classname>PharException</classname> will be thrown.</para></note>'>
2093
2729
2094
-
<!ENTITY phar.removed.pharcompress '<note xmlns="http://docbook.org/ns/docbook"><para>This
2095
-
method has been removed from the phar extension as of version 2.0.0. Alternative
2096
-
implementations are available using <function>Phar::compress</function>,
2097
-
<function>Phar::decompress</function>, <function>Phar::compressFiles</function> and
2098
-
<function>Phar::decompressFiles</function>.</para></note>'>
2099
-
2100
-
<!ENTITY phar.removed.pharfileinfocompress '<note xmlns="http://docbook.org/ns/docbook"><para>This
2101
-
method has been removed from the phar extension as of version 2.0.0. Alternative
2102
-
implementations are available using <function>PharFileInfo::isCompressed</function>,
2103
-
<function>PharFileInfo::decompress</function>, and <function>PharFileInfo::compress</function>.</para></note>'>
2104
-
2105
2730
<!ENTITY phar.note.performance '<note xmlns="http://docbook.org/ns/docbook">
2106
2731
<simpara>
2107
2732
<function>Phar::addFile</function>, <function>Phar::addFromString</function> and <function>Phar::offsetSet</function>
...
...
@@ -2144,6 +2769,9 @@ implementations are available using <function>PharFileInfo::isCompressed</functi
2144
2769
<varname linkend="streamwrapper.props.context">streamWrapper::$context</varname>
2145
2770
property is updated if a valid context is passed to the caller function.</para></note>'>
2146
2771
2772
+
<!ENTITY stream.bucket.param '<parameter>bucket</parameter> expects a <classname>StreamBucket</classname> instance now; previously, an <classname>stdClass</classname> was expected.'>
2773
+
<!ENTITY stream.bucket.return 'This function returns a <classname>StreamBucket</classname> instance now; previously, an <classname>stdClass</classname> was returned.'>
2774
+
2147
2775
<!-- Gmagick -->
2148
2776
<!ENTITY gmagick.return.success 'Returns &true; on success.'>
2149
2777
<!ENTITY gmagick.gmagickexception.throw 'Throws an
...
...
@@ -2162,24 +2790,33 @@ to be references, then they must be references in the passed argument list.'>
2162
2790
2163
2791
<!ENTITY reflection.export.param.name 'The reflection to export.'>
2164
2792
2165
-
<!-- SPL -->
2166
-
<!ENTITY spl.datastructures.intro.title '<title xmlns="http://docbook.org/ns/docbook">Datastructures</title>'>
2167
-
2168
-
<!ENTITY spl.exceptions.intro.title '<title xmlns="http://docbook.org/ns/docbook">Exceptions</title>'>
2169
-
<!ENTITY spl.exceptions.intro '<para xmlns="http://docbook.org/ns/docbook">SPL provides a set of standard Exceptions.</para><para xmlns="http://docbook.org/ns/docbook">See also the <xref linkend="reserved.exceptions" /></para>'>
2170
-
2171
-
<!ENTITY spl.files.intro.title '<title xmlns="http://docbook.org/ns/docbook">File Handling</title>'>
2172
-
<!ENTITY spl.files.intro '<partintro xmlns="http://docbook.org/ns/docbook"><para>SPL provides a number of classes to work with files.</para></partintro>'>
2173
-
2174
-
<!ENTITY spl.interfaces.intro.title '<title xmlns="http://docbook.org/ns/docbook">Interfaces</title>'>
2175
-
<!ENTITY spl.interfaces.intro '<para xmlns="http://docbook.org/ns/docbook">SPL provides a set of interfaces.</para><para xmlns="http://docbook.org/ns/docbook">See also the <xref linkend="reserved.interfaces" /></para>'>
2176
-
<!ENTITY spl.interfaces.list '<title xmlns="http://docbook.org/ns/docbook">Interface list</title>'>
2177
-
2178
-
<!ENTITY spl.iterators.intro.title '<title xmlns="http://docbook.org/ns/docbook">Iterators</title>'>
2179
-
<!ENTITY spl.iterators.intro '<para xmlns="http://docbook.org/ns/docbook">SPL provides a set of iterators to traverse over objects.</para>'>
2793
+
<!ENTITY reflection.getattributes.param.name '<varlistentry xmlns="http://docbook.org/ns/docbook">
2794
+
<term><parameter>name</parameter></term>
2795
+
<listitem>
2796
+
<para>
2797
+
Filter the results to include only <classname>ReflectionAttribute</classname>
2798
+
instances for attributes matching this class name.
2799
+
</para>
2800
+
</listitem>
2801
+
</varlistentry>'>
2180
2802
2181
-
<!ENTITY spl.misc.intro.title '<title xmlns="http://docbook.org/ns/docbook">Miscellaneous Classes and Interfaces</title>'>
2182
-
<!ENTITY spl.misc.intro '<partintro xmlns="http://docbook.org/ns/docbook"><para>Classes and interfaces which do not fit into the other SPL categories.</para></partintro>'>
2803
+
<!ENTITY reflection.getattributes.param.flags '<varlistentry xmlns="http://docbook.org/ns/docbook">
2804
+
<term><parameter>flags</parameter></term>
2805
+
<listitem>
2806
+
<para>
2807
+
Flags for determining how to filter the results, if <parameter>name</parameter>
2808
+
is provided.
2809
+
</para>
2810
+
<para>
2811
+
Default is <literal>0</literal> which will only return results for attributes that
2812
+
are of the class <parameter>name</parameter>.
2813
+
</para>
2814
+
<para>
2815
+
The only other option available, is to use <constant>ReflectionAttribute::IS_INSTANCEOF</constant>,
2816
+
which will instead use <literal>instanceof</literal> for filtering.
2817
+
</para>
2818
+
</listitem>
2819
+
</varlistentry>'>
2183
2820
2184
2821
<!-- ZIP -->
2185
2822
<!ENTITY zip.filename.separator '<note xmlns="http://docbook.org/ns/docbook"><simpara>For maximum portability, it is recommended to always use forward slashes (<literal>/</literal>) as directory separator in ZIP filenames.</simpara></note>'>
...
...
@@ -2286,7 +2923,7 @@ system call.</para></listitem>
2286
2923
</varlistentry>
2287
2924
<varlistentry xmlns="http://docbook.org/ns/docbook">
2288
2925
<term><parameter>req</parameter></term>
2289
-
<listitem><para>is optional request resource which can be used with functions like <function>eio_get_last_error</function></para></listitem>
2926
+
<listitem><para>is optional request resource which can be used with functions like <function>eio_get_last_error</function>.</para></listitem>
2290
2927
</varlistentry>
2291
2928
</variablelist>
2292
2929
</para>
...
...
@@ -2331,7 +2968,7 @@ paths</simpara></warning>
2331
2968
<!ENTITY trader.arg.fast.ma.type 'Type of Moving Average for fast MA. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
2332
2969
<!ENTITY trader.arg.slow.ma.type 'Type of Moving Average for slow MA. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
2333
2970
<!ENTITY trader.arg.fastd.ma.type 'Type of Moving Average for Fast-D. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
2334
-
<!ENTITY trader.arg.slowk.ma.type 'Type of Moving Average for Slow-K. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
2971
+
<!ENTITY trader.arg.fastk.ma.type 'Type of Moving Average for Fast-K. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
2335
2972
<!ENTITY trader.arg.slowd.ma.type 'Type of Moving Average for Slow-D. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
2336
2973
<!ENTITY trader.arg.slowk.ma.type 'Type of Moving Average for Slow-K. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
2337
2974
<!ENTITY trader.arg.signal.ma.type 'Type of Moving Average for signal line. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
...
...
@@ -2340,70 +2977,78 @@ paths</simpara></warning>
2340
2977
<!ENTITY trader.arg.fast.limit 'Upper limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.'>
2341
2978
<!ENTITY trader.arg.slow.limit 'Lower limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.'>
2342
2979
2343
-
<!-- Mongo -->
2344
-
<!ENTITY mongo.setreadpreference.parameters '<variablelist xmlns="http://docbook.org/ns/docbook"><varlistentry><term><parameter>read_preference</parameter></term><listitem><para>The read preference mode: <constant>MongoClient::RP_PRIMARY</constant>, <constant>MongoClient::RP_PRIMARY_PREFERRED</constant>, <constant>MongoClient::RP_SECONDARY</constant>, <constant>MongoClient::RP_SECONDARY_PREFERRED</constant>, or <constant>MongoClient::RP_NEAREST</constant>.</para></listitem></varlistentry><varlistentry><term><parameter>tags</parameter></term><listitem><para>An array of zero or more tag sets, where each tag set is itself an array of criteria used to match tags on replica set members.</para></listitem></varlistentry></variablelist>'>
2345
-
<!ENTITY mongo.setreadpreference.returnvalues '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>
2346
-
<!ENTITY mongo.setreadpreference.errors '<para xmlns="http://docbook.org/ns/docbook">Emits <constant>E_WARNING</constant> if either parameter is invalid, or if one or more tag sets are provided with the <constant>MongoClient::RP_PRIMARY</constant> read preference mode.</para>'>
2347
-
<!ENTITY mongo.getreadpreference.returnvalues '<para xmlns="http://docbook.org/ns/docbook">This function returns an array describing the read preference. The array contains the values <literal>type</literal> for the string read preference mode (corresponding to the <classname>MongoClient</classname> constants), and <literal>tagsets</literal> containing a list of all tag set criteria. If no tag sets were specified, <literal>tagsets</literal> will not be present in the array.</para>'>
2348
-
<!ENTITY mongo.setwriteconcern.parameters '<variablelist xmlns="http://docbook.org/ns/docbook"><varlistentry><term><parameter>w</parameter></term><listitem><para>The write concern. This may be an integer denoting the number of servers required to acknowledge the write, or a string mode (e.g. "majority").</para></listitem></varlistentry><varlistentry><term><parameter>wtimeout</parameter></term><listitem><para>The maximum number of milliseconds to wait for the server to satisfy the write concern.</para></listitem></varlistentry></variablelist>'>
2349
-
<!ENTITY mongo.setwriteconcern.returnvalues '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>
2350
-
<!ENTITY mongo.setwriteconcern.errors '<para xmlns="http://docbook.org/ns/docbook">Emits <constant>E_WARNING</constant> if the <literal>w</literal> parameter is not an integer or string value.</para>'>
2351
-
<!ENTITY mongo.getwriteconcern.returnvalues '<para xmlns="http://docbook.org/ns/docbook">This function returns an array describing the write concern. The array contains the values <literal>w</literal> for an integer acknowledgement level or string mode, and <literal>wtimeout</literal> denoting the maximum number of milliseconds to wait for the server to satisfy the write concern.</para>'>
2352
-
<!ENTITY mongo.command.parameters.maxtimems '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"maxTimeMS"</literal></para><para>Specifies a cumulative time limit in milliseconds for processing the operation on the server (does not include idle time). If the operation is not completed by the server within the timeout period, a <classname>MongoExecutionTimeoutException</classname> will be thrown.</para></listitem>'>
2353
-
<!ENTITY mongo.index.parameters.background '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"background"</literal></para><para>Builds the index in the background so that building an index does <emphasis>not</emphasis> block other database activities. Specify &true; to build in the background. The default value is &false;.</para><warning xmlns="http://docbook.org/ns/docbook"><para>Prior to MongoDB 2.6.0, index builds on secondaries were executed as foreground operations, irrespective of this option. See <link xlink:href="&url.mongodb.dochub.indexes.rs;" xmlns:xlink="http://www.w3.org/1999/xlink">Building Indexes with Replica Sets</link> for more information.</para></warning></listitem>'>
2354
-
<!ENTITY mongo.index.parameters.dropdups '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"dropDups"</literal></para><para>Specify &true; to force creation of a unique index where the collection may contain duplicate values for a key. MongoDB will index the first occurrence of a key and delete all subsequent documents from the collection that contain a duplicate value for that key. The default value is &false;.</para><warning xmlns="http://docbook.org/ns/docbook"><para><literal>"dropDups"</literal> may delete data from your database. Use with extreme caution.</para></warning><note xmlns="http://docbook.org/ns/docbook"><para>This option is not supported on MongoDB 2.8+. Index creation will fail if the collection contains duplicate values.</para></note></listitem>'>
2355
-
<!ENTITY mongo.index.parameters.expireafterseconds '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"expireAfterSeconds"</literal></para><para>The value of this option should specify the number of seconds after which a document should be considered expired and automatically removed from the collection. This option is only compatible with single-field indexes where the field will contain <classname>MongoDate</classname> values.</para><note xmlns="http://docbook.org/ns/docbook"><para>This feature is available in MongoDB 2.2+. See <link xlink:href="&url.mongodb.docs.expire_data;" xmlns:xlink="http://www.w3.org/1999/xlink">Expire Data from Collections by Setting TTL</link> for more information.</para></note></listitem>'>
2356
-
<!ENTITY mongo.index.parameters.name '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"name"</literal></para><para>A optional name that uniquely identifies the index.</para><note xmlns="http://docbook.org/ns/docbook"><para>By default, the driver will generate an index name based on the index's field(s) and ordering or type. For example, a compound index <literal>array("x" => 1, "y" => -1)</literal> would be named <literal>"x_1_y_-1"</literal> and a geospatial index <literal>array("loc" => "2dsphere")</literal> would be named <literal>"loc_2dsphere"</literal>. For indexes with many fields, it is possible that the generated name might exceed MongoDB's <link xlink:href="&url.mongodb.docs.limits;#Index-Name-Length" xmlns:xlink="http://www.w3.org/1999/xlink">limit for index names</link>. The <literal>"name"</literal> option may be used in that case to supply a shorter name.</para></note></listitem>'>
2357
-
<!ENTITY mongo.index.parameters.sparse '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"sparse"</literal></para><para>Specify &true; to create a sparse index, which only indexes documents containing a specified field. The default value is &false;.</para></listitem>'>
2358
-
<!ENTITY mongo.index.parameters.unique '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"unique"</literal></para><para>Specify &true; to create a unique index. The default value is &false;. This option applies only to ascending/descending indexes.</para><note xmlns="http://docbook.org/ns/docbook"><para>When MongoDB indexes a field, if a document does not have a value for the field, a &null; value is indexed. If multiple documents do not contain a field, a unique index will reject all but the first of those documents. The <literal>"sparse"</literal> option may be used to overcome this, since it will prevent documents without the field from being indexed.</para></note></listitem>'>
2359
-
<!ENTITY mongo.listcollections.note '<note xmlns="http://docbook.org/ns/docbook"><simpara>This method will use the <link xlink:href="&url.mongodb.docs.command;listCollections" xmlns:xlink="http://www.w3.org/1999/xlink">listCollections</link> database command when communicating with MongoDB 2.8+. For previous database versions, the method will query the special <literal>system.namespaces</literal> collection.</simpara></note>'>
2360
-
<!ENTITY mongo.listcollections.parameters.filter '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"filter"</literal></para><para>Optional query criteria. If provided, this criteria will be used to filter the collections included in the result.</para><para>Relevant fields that may be queried include <literal>"name"</literal> (collection name as a string, without the database name prefix) and <literal>"options" (object containing options used to create the collection).</literal>.</para><note><simpara>MongoDB 2.6 and earlier versions require the <literal>"name"</literal> criteria, if specified, to be a string value (i.e. equality match). This is because the driver must prefix the value with the database name in order to query the <literal>system.namespaces</literal> collection. Later versions of MongoDB do not have this limitation, as the driver will use the listCollections command.</simpara></note></listitem>'>
2361
-
<!ENTITY mongo.listcollections.parameters.includesystemcollections '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"includeSystemCollections"</literal></para><para>Boolean, defaults to &false;. Determines whether system collections should be included in the result.</para></listitem>'>
2362
-
<!ENTITY mongo.writes.parameters.writeconcern '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"w"</literal></para><para>See <link linkend="mongo.writeconcerns">Write Concerns</link>. The default value for <classname>MongoClient</classname> is <literal>1</literal>.</para></listitem>'>
2363
-
<!ENTITY mongo.writes.parameters.writeconcerntimeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"wtimeout"</literal></para><para>Deprecated alias for <literal>"wTimeoutMS"</literal>.</para></listitem>'>
2364
-
<!ENTITY mongo.writes.parameters.writeconcerntimeoutms '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"wTimeoutMS"</literal></para><para>This option specifies the time limit, in milliseconds, for <link linkend="mongo.writeconcerns">write concern</link> acknowledgement. It is only applicable when <literal>"w"</literal> is greater than <literal>1</literal>, as the timeout pertains to replication. If the write concern is not satisfied within the time limit, a <classname>MongoCursorException</classname> will be thrown. A value of <literal>0</literal> may be specified to block indefinitely. The default value for <classname>MongoClient</classname> is <literal>10000</literal> (ten seconds).</para></listitem>'>
2365
-
<!ENTITY mongo.writes.parameters.fsync '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"fsync"</literal></para><para>Boolean, defaults to &false;. If journaling is enabled, it works exactly like <literal>"j"</literal>. If journaling is not enabled, the write operation blocks until it is synced to database files on disk. If &true;, an acknowledged insert is implied and this option will override setting <literal>"w"</literal> to <literal>0</literal>.</para><note><simpara>If journaling is enabled, users are strongly encouraged to use the <literal>"j"</literal> option instead of <literal>"fsync"</literal>. Do not use <literal>"fsync"</literal> and <literal>"j"</literal> simultaneously, as that will result in an error.</simpara></note></listitem>'>
2366
-
<!ENTITY mongo.writes.parameters.sockettimeoutms '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"socketTimeoutMS"</literal></para><para>This option specifies the time limit, in milliseconds, for socket communication. If the server does not respond within the timeout period, a <classname>MongoCursorTimeoutException</classname> will be thrown and there will be no way to determine if the server actually handled the write or not. A value of <literal>-1</literal> may be specified to block indefinitely. The default value for <classname>MongoClient</classname> is <literal>30000</literal> (30 seconds).</para></listitem>'>
2367
-
<!ENTITY mongo.writes.parameters.journal '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"j"</literal></para><para>Boolean, defaults to &false;. Forces the write operation to block until it is synced to the journal on disk. If &true;, an acknowledged write is implied and this option will override setting <literal>"w"</literal> to <literal>0</literal>.</para><note><simpara>If this option is used and journaling is disabled, MongoDB 2.6+ will raise an error and the write will fail; older server versions will simply ignore the option.</simpara></note></listitem>'>
2368
-
<!ENTITY mongo.writes.parameters.safe '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"safe"</literal></para><para>Deprecated. Please use the <link linkend="mongo.writeconcerns">write concern</link> <literal>"w"</literal> option.</para></listitem>'>
2369
-
<!ENTITY mongo.writes.parameters.timeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"timeout"</literal></para><para>Deprecated alias for <literal>"socketTimeoutMS"</literal>.</para></listitem>'>
2370
-
<!ENTITY mongo.errors.exceptions.writeconcern '<para xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoCursorException</classname> if the <literal>"w"</literal> option is set and the write fails.</para><para xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoCursorTimeoutException</classname> if the <literal>"w"</literal> option is set to a value greater than one and the operation takes longer than <varname>MongoCursor::$timeout</varname> milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout. The operation in <varname>MongoCollection::$wtimeout</varname> is milliseconds.</para>'>
2371
-
<!ENTITY mongo.errors.deprecated '<para xmlns="http://docbook.org/ns/docbook">Issues <constant>E_DEPRECATED</constant> warning</para>'>
2372
-
<!ENTITY mongo.gridfs.store.metadata.note '<note xmlns="http://docbook.org/ns/docbook"><para>These fields may also overwrite those that would be created automatically by the driver, as described in the MongoDB core documentation for the <link xlink:href="&url.mongodb.docs.gridfs;#the-files-collection" xmlns:xlink="http://www.w3.org/1999/xlink">files collection</link>. Some practical use cases for this behavior would be to specify a custom <literal>chunkSize</literal> or <literal>_id</literal> for the file.</para></note>'>
2373
-
<!ENTITY mongo.gridfs.store.return '<para xmlns="http://docbook.org/ns/docbook">Returns the <literal>_id</literal> of the saved file document. This will be a generated <classname>MongoId</classname> unless an <literal>_id</literal> was explicitly specified in the <parameter>metadata</parameter> parameter.</para>'>
2374
-
<!ENTITY mongo.mongowritebatch.writeoptions.description '<listitem xmlns="http://docbook.org/ns/docbook"><para>An array of Write Options.<informaltable><thead><row><entry>key</entry><entry>value meaning</entry></row></thead><tbody><row><entry>w (int|string)</entry><entry><link linkend="mongo.writeconcerns">Write concern</link> value</entry></row><row><entry>wtimeout (int)</entry><entry><link linkend="mongo.writeconcerns">Maximum time to wait for replication</link></entry></row><row><entry>ordered</entry><entry>Determines if MongoDB must apply this batch in order. Ordered writes execute serially (i.e. one at a time) and execution will stop after the first error. Unordered writes may execute in parallel and execution will not stop after the first error. Defaults to &true;</entry></row><row><entry>j (bool)</entry><entry>Wait for journaling on the primary. This value is discouraged, use WriteConcern instead</entry></row><row><entry>fsync (bool)</entry><entry>Wait for fsync on the primary. This value is discouraged, use WriteConcern instead</entry></row></tbody></informaltable></para></listitem>'>
2375
-
<!ENTITY mongo.mongowritebatch.collection.description '<listitem xmlns="http://docbook.org/ns/docbook"><para>The <classname>MongoCollection</classname> to execute the batch on. Its <link linkend="mongo.writeconcerns">write concern</link> will be copied and used as the default write concern if none is given as <parameter>$write_options</parameter> or during <methodname>MongoWriteBatch::execute</methodname>.</para></listitem>'>
2376
-
<!ENTITY mongo.context.server ' <varlistentry xmlns="http://docbook.org/ns/docbook"> <term> <parameter>server</parameter> </term> <listitem> <para> An array containing the basic information about the server that was picked. <informaltable> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>hash</entry> <entry>server hash, example: <literal>localhost:27017;-;X;56052</literal></entry> </row> <row> <entry>type</entry> <entry>Node type (primary/secondary/mongos/arbiter): <literal>2</literal></entry> </row> <row> <entry>max_bson_size</entry> <entry>The maximum BSON Size over the wire this node accepts: <literal>16777216</literal></entry> </row> <row> <entry>max_message_size</entry> <entry>The maximum Message Size over the wire this node accepts: <literal>48000000</literal></entry> </row> <row> <entry>request_id</entry> <entry>The request identifier for this message: <literal>42</literal></entry> </row> </tbody> </tgroup> </informaltable> </para> </listitem> </varlistentry>'>
2377
-
<!ENTITY mongo.context.writeoptions '<varlistentry xmlns="http://docbook.org/ns/docbook"> <term> <parameter>writeOptions</parameter> </term> <listitem> <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>ordered</entry> <entry>boolean, if the operation (in case of batch operation) must be executed sequentually (ordered=true)</entry> </row> <row> <entry>writeConcern</entry> <entry>An array of writeConcern options (see below)</entry> </row> </tbody> </tgroup> </informaltable> <table> <title>writeConcern array values</title> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>fsync</entry> <entry>boolean, force flushing to disk before returning</entry> </row> <row> <entry>j</entry> <entry>boolean, force journal write before returning</entry> </row> <row> <entry>wtimeout</entry> <entry>integer, milliseconds, maximum time the primary is allowed to wait to verify replication</entry> </row> <row> <entry>w</entry> <entry>integer=server count, or string=replication-tag</entry> </row> </tbody> </tgroup> </table> </para> </listitem> </varlistentry>'>
2378
-
<!ENTITY mongo.context.protocoloptions ' <varlistentry xmlns="http://docbook.org/ns/docbook"> <term> <parameter>protocolOptions</parameter> </term> <listitem> <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>message_length</entry> <entry>The total size (in bytes) of the encoded message being sent over the wire</entry> </row> <row> <entry>request_id</entry> <entry>The request identifier for this message: <literal>42</literal></entry> </row> <row> <entry>namespace</entry> <entry>The MongoDB namespace used for the protocol message <literal>dbname.collectionname</literal></entry> </row> </tbody> </tgroup> </informaltable> </para> </listitem> </varlistentry>'>
2379
-
<!ENTITY mongo.alternative.class.note '<para
2380
-
xmlns="http://docbook.org/ns/docbook">This extension that defines this class
2381
-
is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.
2382
-
Alternatives to this class include:</para>'>
2383
-
<!ENTITY mongo.noalternative.class.note '<para
2384
-
xmlns="http://docbook.org/ns/docbook">This extension that defines this class
2385
-
is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.
2386
-
There is no equivalent for this class in the new extension.</para>'>
2387
-
<!ENTITY mongo.alternative.method.note '<para
2388
-
xmlns="http://docbook.org/ns/docbook">This extension that defines this method
2389
-
is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.
2390
-
Alternatives to this method include:</para>'>
2391
-
<!ENTITY mongo.noalternative.method.note '<para
2392
-
xmlns="http://docbook.org/ns/docbook">This extension that defines this method
2393
-
is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.
2394
-
There is no equivalent for this method in the new extension.</para>'>
2395
-
<!ENTITY mongo.alternative.phplib.note '<para
2396
-
xmlns="http://docbook.org/ns/docbook">This extension that defines this method
2397
-
is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.
2398
-
There is no equivalent for this method in the new extension, but there is an
2399
-
alternative in the <link linkend="mongodb.overview">PHP library</link>:</para>'>
2400
-
2401
-
<!ENTITY mongo.deprecated.note '<para
2402
-
xmlns="http://docbook.org/ns/docbook">This extension is deprecated. Instead,
2403
-
the <link linkend="set.mongodb">MongoDB</link> extension should be
2404
-
used.</para>'>
2405
-
2406
2980
<!-- mongodb -->
2981
+
<!ENTITY mongodb.changelog.class-removed '
2982
+
<row xmlns="http://docbook.org/ns/docbook">
2983
+
<entry>PECL mongodb 2.0.0</entry>
2984
+
<entry>
2985
+
This class was removed.
2986
+
</entry>
2987
+
</row>
2988
+
'>
2989
+
2990
+
<!ENTITY mongodb.changelog.function-removed '
2991
+
<row xmlns="http://docbook.org/ns/docbook">
2992
+
<entry>PECL mongodb 2.0.0</entry>
2993
+
<entry>
2994
+
This function was removed.
2995
+
</entry>
2996
+
</row>
2997
+
'>
2998
+
2999
+
<!ENTITY mongodb.changelog.method-removed '
3000
+
<row xmlns="http://docbook.org/ns/docbook">
3001
+
<entry>PECL mongodb 2.0.0</entry>
3002
+
<entry>
3003
+
This method was removed.
3004
+
</entry>
3005
+
</row>
3006
+
'>
3007
+
3008
+
<!ENTITY mongodb.changelog.serializable-interface-removed '
3009
+
<row xmlns="http://docbook.org/ns/docbook">
3010
+
<entry>PECL mongodb 2.0.0</entry>
3011
+
<entry>
3012
+
<para>
3013
+
This class no longer implements the
3014
+
<interfacename>Serializable</interfacename> interface.
3015
+
</para>
3016
+
</entry>
3017
+
</row>
3018
+
'>
3019
+
3020
+
<!ENTITY mongodb.changelog.tentative-return-types '
3021
+
<row xmlns="http://docbook.org/ns/docbook">
3022
+
<entry>PECL mongodb 1.15.0</entry>
3023
+
<entry>
3024
+
Return types for methods are declared as tentative on PHP 8.0 and newer,
3025
+
triggering deprecation notices in code that implements this interface
3026
+
without declaring the appropriate return types. The <code>#[ReturnTypeWillChange]</code>
3027
+
attribute can be added to silence the deprecation notice.
3028
+
</entry>
3029
+
</row>
3030
+
'>
3031
+
3032
+
<!ENTITY mongodb.changelog.tentative-return-types-enforced '
3033
+
<row xmlns="http://docbook.org/ns/docbook">
3034
+
<entry>PECL mongodb 2.0.0</entry>
3035
+
<entry>
3036
+
Return types previously declared as tentative are now enforced.
3037
+
</entry>
3038
+
</row>
3039
+
'>
3040
+
3041
+
<!ENTITY mongodb.changelog.throw-unacknowledged-write '
3042
+
<row xmlns="http://docbook.org/ns/docbook">
3043
+
<entry>PECL mongodb 2.0.0</entry>
3044
+
<entry>
3045
+
<para>
3046
+
This method now throws an exception when called for an unacknowledged write instead of returning &null;.
3047
+
</para>
3048
+
</entry>
3049
+
</row>
3050
+
'>
3051
+
2407
3052
<!ENTITY mongodb.option.collation '
2408
3053
<row xmlns="http://docbook.org/ns/docbook">
2409
3054
<entry>collation</entry>
...
...
@@ -2421,6 +3066,20 @@ used.</para>'>
2421
3066
</entry>
2422
3067
</row>
2423
3068
'>
3069
+
<!ENTITY mongodb.option.let '
3070
+
<row xmlns="http://docbook.org/ns/docbook">
3071
+
<entry>let</entry>
3072
+
<entry><type class="union"><type>array</type><type>object</type></type></entry>
3073
+
<entry>
3074
+
<para>
3075
+
Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an aggregate expression context (e.g. <literal>$$var</literal>).
3076
+
</para>
3077
+
<para>
3078
+
This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.
3079
+
</para>
3080
+
</entry>
3081
+
</row>
3082
+
'>
2424
3083
<!ENTITY mongodb.option.encryption.keyVaultClient '
2425
3084
<row xmlns="http://docbook.org/ns/docbook">
2426
3085
<entry>keyVaultClient</entry>
...
...
@@ -2432,16 +3091,22 @@ used.</para>'>
2432
3091
<row xmlns="http://docbook.org/ns/docbook">
2433
3092
<entry>keyVaultNamespace</entry>
2434
3093
<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>
3094
+
<entry>A fully qualified namespace (e.g. <literal>"databaseName.collectionName"</literal>) denoting the collection that contains all data keys used for encryption and decryption. This option is required.</entry>
2436
3095
</row>
2437
3096
'>
2438
3097
<!ENTITY mongodb.option.encryption.kmsProviders '
2439
-
<row xmlns="http://docbook.org/ns/docbook">
3098
+
<row xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
2440
3099
<entry>kmsProviders</entry>
2441
3100
<entry><type>array</type></entry>
2442
3101
<entry>
2443
3102
<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.
3103
+
A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Supported providers include <literal>"aws"</literal>, <literal>"azure"</literal>, <literal>"gcp"</literal>, <literal>"kmip"</literal>, and <literal>"local"</literal> and at least one must be specified.
3104
+
</para>
3105
+
<para>
3106
+
If an empty document is specified for <literal>"aws"</literal>,
3107
+
<literal>"azure"</literal>, or <literal>"gcp"</literal>, the driver
3108
+
will attempt to configure the provider using
3109
+
<link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#automatic-credentials">Automatic Credentials</link>.
2445
3110
</para>
2446
3111
<para>
2447
3112
The format for <literal>"aws"</literal> is as follows:
...
...
@@ -2450,7 +3115,8 @@ used.</para>'>
2450
3115
<![CDATA[
2451
3116
aws: {
2452
3117
accessKeyId: <string>,
2453
-
secretAccessKey: <string>
3118
+
secretAccessKey: <string>,
3119
+
sessionToken: <optional string>
2454
3120
}
2455
3121
]]>
2456
3122
</programlisting>
...
...
@@ -2464,7 +3130,6 @@ azure: {
2464
3130
clientId: <string>,
2465
3131
clientSecret: <string>,
2466
3132
identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
2467
-
2468
3133
}
2469
3134
]]>
2470
3135
</programlisting>
...
...
@@ -2473,11 +3138,20 @@ azure: {
2473
3138
</para>
2474
3139
<programlisting role="javascript">
2475
3140
<![CDATA[
2476
-
aws: {
3141
+
gcp: {
2477
3142
email: <string>,
2478
3143
privateKey: <base64 string>|<MongoDB\BSON\Binary>,
2479
3144
endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
2480
-
3145
+
}
3146
+
]]>
3147
+
</programlisting>
3148
+
<para>
3149
+
The format for <literal>"kmip"</literal> is as follows:
3150
+
</para>
3151
+
<programlisting role="javascript">
3152
+
<![CDATA[
3153
+
kmip: {
3154
+
endpoint: <string>
2481
3155
}
2482
3156
]]>
2483
3157
</programlisting>
...
...
@@ -2495,6 +3169,168 @@ local: {
2495
3169
</entry>
2496
3170
</row>
2497
3171
'>
3172
+
<!ENTITY mongodb.option.encryption.masterKey-options-by-provider '
3173
+
<para xmlns="http://docbook.org/ns/docbook">
3174
+
<table>
3175
+
<title><literal>"aws"</literal> provider options</title>
3176
+
<tgroup cols="3">
3177
+
<thead>
3178
+
<row>
3179
+
<entry>Option</entry>
3180
+
<entry>Type</entry>
3181
+
<entry>Description</entry>
3182
+
</row>
3183
+
</thead>
3184
+
<tbody>
3185
+
<row>
3186
+
<entry>region</entry>
3187
+
<entry>string</entry>
3188
+
<entry>Required.</entry>
3189
+
</row>
3190
+
<row>
3191
+
<entry>key</entry>
3192
+
<entry>string</entry>
3193
+
<entry>Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).</entry>
3194
+
</row>
3195
+
<row>
3196
+
<entry>endpoint</entry>
3197
+
<entry>string</entry>
3198
+
<entry>Optional. An alternate host identifier to send KMS requests to. May include port number.</entry>
3199
+
</row>
3200
+
</tbody>
3201
+
</tgroup>
3202
+
</table>
3203
+
</para>
3204
+
<para xmlns="http://docbook.org/ns/docbook">
3205
+
<table>
3206
+
<title><literal>"azure"</literal> provider options</title>
3207
+
<tgroup cols="3">
3208
+
<thead>
3209
+
<row>
3210
+
<entry>Option</entry>
3211
+
<entry>Type</entry>
3212
+
<entry>Description</entry>
3213
+
</row>
3214
+
</thead>
3215
+
<tbody>
3216
+
<row>
3217
+
<entry>keyVaultEndpoint</entry>
3218
+
<entry>string</entry>
3219
+
<entry>Required. Host with optional port (e.g. "example.vault.azure.net").</entry>
3220
+
</row>
3221
+
<row>
3222
+
<entry>keyName</entry>
3223
+
<entry>string</entry>
3224
+
<entry>Required.</entry>
3225
+
</row>
3226
+
<row>
3227
+
<entry>keyVersion</entry>
3228
+
<entry>string</entry>
3229
+
<entry>Optional. A specific version of the named key. Defaults to using the key's primary version.</entry>
3230
+
</row>
3231
+
</tbody>
3232
+
</tgroup>
3233
+
</table>
3234
+
</para>
3235
+
<para xmlns="http://docbook.org/ns/docbook">
3236
+
<table>
3237
+
<title><literal>"gcp"</literal> provider options</title>
3238
+
<tgroup cols="3">
3239
+
<thead>
3240
+
<row>
3241
+
<entry>Option</entry>
3242
+
<entry>Type</entry>
3243
+
<entry>Description</entry>
3244
+
</row>
3245
+
</thead>
3246
+
<tbody>
3247
+
<row>
3248
+
<entry>projectId</entry>
3249
+
<entry>string</entry>
3250
+
<entry>Required.</entry>
3251
+
</row>
3252
+
<row>
3253
+
<entry>location</entry>
3254
+
<entry>string</entry>
3255
+
<entry>Required.</entry>
3256
+
</row>
3257
+
<row>
3258
+
<entry>keyRing</entry>
3259
+
<entry>string</entry>
3260
+
<entry>Required.</entry>
3261
+
</row>
3262
+
<row>
3263
+
<entry>keyName</entry>
3264
+
<entry>string</entry>
3265
+
<entry>Required.</entry>
3266
+
</row>
3267
+
<row>
3268
+
<entry>keyVersion</entry>
3269
+
<entry>string</entry>
3270
+
<entry>Optional. A specific version of the named key. Defaults to using the key's primary version.</entry>
3271
+
</row>
3272
+
<row>
3273
+
<entry>endpoint</entry>
3274
+
<entry>string</entry>
3275
+
<entry>Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".</entry>
3276
+
</row>
3277
+
</tbody>
3278
+
</tgroup>
3279
+
</table>
3280
+
</para>
3281
+
<para xmlns="http://docbook.org/ns/docbook">
3282
+
<table>
3283
+
<title><literal>"kmip"</literal> provider options</title>
3284
+
<tgroup cols="3">
3285
+
<thead>
3286
+
<row>
3287
+
<entry>Option</entry>
3288
+
<entry>Type</entry>
3289
+
<entry>Description</entry>
3290
+
</row>
3291
+
</thead>
3292
+
<tbody>
3293
+
<row>
3294
+
<entry>keyId</entry>
3295
+
<entry>string</entry>
3296
+
<entry>Optional. Unique identifier to a 96-byte KMIP secret data managed object. If unspecified, the driver creates a random 96-byte KMIP secret data managed object.</entry>
3297
+
</row>
3298
+
<row>
3299
+
<entry>endpoint</entry>
3300
+
<entry>string</entry>
3301
+
<entry>Optional. Host with optional port.</entry>
3302
+
</row>
3303
+
<row>
3304
+
<entry>delegated</entry>
3305
+
<entry>bool</entry>
3306
+
<entry>Optional. If true, this key should be decrypted by the KMIP server.</entry>
3307
+
</row>
3308
+
</tbody>
3309
+
</tgroup>
3310
+
</table>
3311
+
</para>
3312
+
'>
3313
+
<!ENTITY mongodb.option.encryption.tlsOptions '
3314
+
<row xmlns="http://docbook.org/ns/docbook">
3315
+
<entry>tlsOptions</entry>
3316
+
<entry><type>array</type></entry>
3317
+
<entry>
3318
+
<para>
3319
+
A document containing the TLS configuration for one or more KMS providers. Supported providers include <literal>"aws"</literal>, <literal>"azure"</literal>, <literal>"gcp"</literal>, and <literal>"kmip"</literal>. All providers support the following options:
3320
+
</para>
3321
+
<programlisting role="javascript">
3322
+
<![CDATA[
3323
+
<provider>: {
3324
+
tlsCaFile: <optional string>,
3325
+
tlsCertificateKeyFile: <optional string>,
3326
+
tlsCertificateKeyFilePassword: <optional string>,
3327
+
tlsDisableOCSPEndpointCheck: <optional bool>
3328
+
}
3329
+
]]>
3330
+
</programlisting>
3331
+
</entry>
3332
+
</row>
3333
+
'>
2498
3334
<!ENTITY mongodb.option.maxCommitTimeMS '
2499
3335
<row xmlns="http://docbook.org/ns/docbook">
2500
3336
<entry>maxCommitTimeMS</entry>
...
...
@@ -2603,6 +3439,16 @@ local: {
2603
3439
</listitem>
2604
3440
</varlistentry>
2605
3441
'>
3442
+
<!ENTITY mongodb.parameter.bulkwritecommand '
3443
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3444
+
<term><parameter>bulk</parameter> (<classname>MongoDB\Driver\BulkWriteCommand</classname>)</term>
3445
+
<listitem>
3446
+
<para>
3447
+
The write(s) to execute.
3448
+
</para>
3449
+
</listitem>
3450
+
</varlistentry>
3451
+
'>
2606
3452
<!ENTITY mongodb.parameter.command '
2607
3453
<varlistentry xmlns="http://docbook.org/ns/docbook">
2608
3454
<term><parameter>command</parameter> (<classname>MongoDB\Driver\Command</classname>)</term>
...
...
@@ -2613,6 +3459,172 @@ local: {
2613
3459
</listitem>
2614
3460
</varlistentry>
2615
3461
'>
3462
+
<!ENTITY mongodb.parameter.encryptOpts '
3463
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
3464
+
<term><parameter>options</parameter></term>
3465
+
<listitem>
3466
+
<para>
3467
+
<table>
3468
+
<title>Encryption options</title>
3469
+
<tgroup cols="3">
3470
+
<thead>
3471
+
<row>
3472
+
<entry>Option</entry>
3473
+
<entry>Type</entry>
3474
+
<entry>Description</entry>
3475
+
</row>
3476
+
</thead>
3477
+
<tbody>
3478
+
<row>
3479
+
<entry>algorithm</entry>
3480
+
<entry><type>string</type></entry>
3481
+
<entry>
3482
+
<para>
3483
+
The encryption algorithm to be used. This option is required.
3484
+
Specify one of the following
3485
+
<link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
3486
+
</para>
3487
+
<simplelist>
3488
+
<member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC</constant></member>
3489
+
<member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM</constant></member>
3490
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant></member>
3491
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED</constant></member>
3492
+
<member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant></member>
3493
+
</simplelist>
3494
+
</entry>
3495
+
</row>
3496
+
<row>
3497
+
<entry>contentionFactor</entry>
3498
+
<entry><type>int</type></entry>
3499
+
<entry>
3500
+
<para>
3501
+
The contention factor for evaluating queries with indexed, encrypted
3502
+
payloads.
3503
+
</para>
3504
+
<para>
3505
+
This option only applies and may only be specified when
3506
+
<literal>algorithm</literal> is
3507
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
3508
+
or
3509
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant>.
3510
+
</para>
3511
+
</entry>
3512
+
</row>
3513
+
<row>
3514
+
<entry>keyAltName</entry>
3515
+
<entry><type>string</type></entry>
3516
+
<entry>
3517
+
<para>
3518
+
Identifies a key vault collection document by
3519
+
<literal>keyAltName</literal>. This option is mutually exclusive
3520
+
with <literal>keyId</literal> and exactly one is required.
3521
+
</para>
3522
+
</entry>
3523
+
</row>
3524
+
<row>
3525
+
<entry>keyId</entry>
3526
+
<entry><classname>MongoDB\BSON\Binary</classname></entry>
3527
+
<entry>
3528
+
<para>
3529
+
Identifies a data key by <literal>_id</literal>. The value is a UUID
3530
+
(binary subtype 4). This option is mutually exclusive with
3531
+
<literal>keyAltName</literal> and exactly one is required.
3532
+
</para>
3533
+
</entry>
3534
+
</row>
3535
+
<row>
3536
+
<entry>queryType</entry>
3537
+
<entry><type>string</type></entry>
3538
+
<entry>
3539
+
<para>
3540
+
The query type for evaluating queries with indexed, encrypted
3541
+
payloads. Specify one of the following
3542
+
<link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
3543
+
</para>
3544
+
<simplelist>
3545
+
<member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY</constant></member>
3546
+
<member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE</constant></member>
3547
+
</simplelist>
3548
+
<para>
3549
+
This option only applies and may only be specified when
3550
+
<literal>algorithm</literal> is
3551
+
<constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
3552
+
or <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant>.
3553
+
</para>
3554
+
</entry>
3555
+
</row>
3556
+
<row>
3557
+
<entry>rangeOpts</entry>
3558
+
<entry><type>array</type></entry>
3559
+
<entry>
3560
+
<para>
3561
+
Index options for a queryable encryption field supporting "range"
3562
+
queries. The options below must match the values set in the
3563
+
<literal>encryptedFields</literal> of the target collection. For
3564
+
double and decimal128 BSON field types, <literal>min</literal>,
3565
+
<literal>max</literal>, and <literal>precision</literal> must all be
3566
+
set, or all be unset.
3567
+
</para>
3568
+
<para>
3569
+
<table>
3570
+
<title>Range index options</title>
3571
+
<tgroup cols="3">
3572
+
<thead>
3573
+
<row>
3574
+
<entry>Option</entry>
3575
+
<entry>Type</entry>
3576
+
<entry>Description</entry>
3577
+
</row>
3578
+
</thead>
3579
+
<tbody>
3580
+
<row>
3581
+
<entry>min</entry>
3582
+
<entry><type>mixed</type></entry>
3583
+
<entry>
3584
+
Required if <literal>precision</literal> is set. The minimum
3585
+
BSON value of the range.
3586
+
</entry>
3587
+
</row>
3588
+
<row>
3589
+
<entry>max</entry>
3590
+
<entry><type>mixed</type></entry>
3591
+
<entry>
3592
+
Required if <literal>precision</literal> is set. The maximum
3593
+
BSON value of the range.
3594
+
</entry>
3595
+
</row>
3596
+
<row>
3597
+
<entry>sparsity</entry>
3598
+
<entry><type>int</type></entry>
3599
+
<entry>Optional. Positive 64-bit integer.</entry>
3600
+
</row>
3601
+
<row>
3602
+
<entry>precision</entry>
3603
+
<entry><type>int</type></entry>
3604
+
<entry>
3605
+
Optional. Positive 32-bit integer specifying precision to use
3606
+
for explicit encryption. May only be set for double or
3607
+
decimal128 BSON field types.
3608
+
</entry>
3609
+
</row>
3610
+
<row>
3611
+
<entry>trimFactor</entry>
3612
+
<entry><type>int</type></entry>
3613
+
<entry>Optional. Positive 32-bit integer.</entry>
3614
+
</row>
3615
+
</tbody>
3616
+
</tgroup>
3617
+
</table>
3618
+
</para>
3619
+
</entry>
3620
+
</row>
3621
+
</tbody>
3622
+
</tgroup>
3623
+
</table>
3624
+
</para>
3625
+
</listitem>
3626
+
</varlistentry>
3627
+
'>
2616
3628
<!ENTITY mongodb.parameter.query '
2617
3629
<varlistentry xmlns="http://docbook.org/ns/docbook">
2618
3630
<term><parameter>query</parameter> (<classname>MongoDB\Driver\Query</classname>)</term>
...
...
@@ -2643,7 +3655,7 @@ local: {
2643
3655
</para>
2644
3656
<note>
2645
3657
<simpara>
2646
-
When evaluating query criteria, MongoDB compares types and values according to its own <link xlink:href="&url.mongodb.docs;reference/bson-type-comparison-order/" xmlns:xlink="http://www.w3.org/1999/xlink">comparison rules for BSON types</link>, which differs from PHP's <link linkend="types.comparisons">comparison</link> and <link linkend="language.types.type-juggling">type juggling</link> rules. When matching a special BSON type the query criteria should use the respective <link linkend="book.bson">BSON class</link> (e.g. use <classname>MongoDB\BSON\ObjectId</classname> to match an <link xlink:href="&url.mongodb.docs.objectid;" xmlns:xlink="http://www.w3.org/1999/xlink">ObjectId</link>).
3658
+
When evaluating query criteria, MongoDB compares types and values according to its own <link xlink:href="&url.mongodb.docs;reference/bson-type-comparison-order/" xmlns:xlink="http://www.w3.org/1999/xlink">comparison rules for BSON types</link>, which differs from PHP's <link linkend="types.comparisons">comparison</link> and <link linkend="language.types.type-juggling">type juggling</link> rules. When matching a special BSON type the query criteria should use the respective <link linkend="mongodb.bson">BSON class</link> (e.g. use <classname>MongoDB\BSON\ObjectId</classname> to match an <link xlink:href="&url.mongodb.docs.objectid;" xmlns:xlink="http://www.w3.org/1999/xlink">ObjectId</link>).
2647
3659
</simpara>
2648
3660
</note>
2649
3661
</listitem>
...
...
@@ -2651,14 +3663,20 @@ local: {
2651
3663
'>
2652
3664
<!ENTITY mongodb.returns.cursor '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\Cursor</classname> on success.</para>'>
2653
3665
<!ENTITY mongodb.returns.writeresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\WriteResult</classname> on success.</para>'>
3666
+
<!ENTITY mongodb.returns.bulkwritecommandresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\BulkWriteCommandResult</classname> on success.</para>'>
2654
3667
<!ENTITY mongodb.throws.std '&mongodb.throws.argumentparsing;&mongodb.throws.connection;&mongodb.throws.authentication;'>
2655
3668
<!ENTITY mongodb.throws.session-readwriteconcern '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if the <literal>"session"</literal> option is used with an associated transaction in combination with a <literal>"readConcern"</literal> or <literal>"writeConcern"</literal> option.</member>'>
2656
3669
<!ENTITY mongodb.throws.session-unacknowledged '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if the <literal>"session"</literal> option is used in combination with an unacknowledged write concern.</member>'>
3670
+
<!ENTITY mongodb.throws.bulkwritecommandexception '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname> on any write failure (e.g. command failure, write or write concern error)</member>'>
2657
3671
<!ENTITY mongodb.throws.bulkwriteexception '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\BulkWriteException</classname> on any write failure (e.g. write error, failure to apply a write concern)</member>'>
2658
3672
<!ENTITY mongodb.throws.argumentparsing '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> on argument parsing errors.</member>'>
2659
3673
<!ENTITY mongodb.throws.authentication '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\AuthenticationException</classname> if authentication is needed and fails.</member>'>
2660
3674
<!ENTITY mongodb.throws.connection '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\ConnectionException</classname> if connection to the server fails (for reasons other than authentication).</member>'>
2661
3675
<!ENTITY mongodb.throws.bson.unexpected '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname> if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected <link xlink:href="&url.mongodb.libbson;" xmlns:xlink="http://www.w3.org/1999/xlink">libbson</link> error.</member>'>
3676
+
<!ENTITY mongodb.throws.unacknowledged '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\LogicException</classname> if the write was not acknowledged.</member>'>
3677
+
3678
+
<!-- Not used in EN anymore -->
3679
+
<!ENTITY mongodb.note.queryable-encryption-preview ''>
2662
3680
2663
3681
<!ENTITY mongodb.note.decimal128 '
2664
3682
<note xmlns="http://docbook.org/ns/docbook">
...
...
@@ -2686,7 +3704,7 @@ local: {
2686
3704
<!ENTITY mongodb.note.forking '
2687
3705
<note xmlns="http://docbook.org/ns/docbook">
2688
3706
<simpara>
2689
-
On Unix platforms, the MongoDB driver is sensitive to scripts that use the
3707
+
On Unix platforms, the extension is sensitive to scripts that use the
2690
3708
fork() system call without also calling exec(). Users are advised not to
2691
3709
re-use <classname>MongoDB\Driver\Manager</classname> instances in a forked
2692
3710
child process.
...
...
@@ -2728,6 +3746,18 @@ local: {
2728
3746
</note>
2729
3747
'>
2730
3748
3749
+
<!ENTITY mongodb.warning.duplicate-keys '
3750
+
<warning xmlns="http://docbook.org/ns/docbook">
3751
+
<simpara>
3752
+
BSON documents can technically contain duplicate keys because documents are
3753
+
stored as a list of key-value pairs; however, applications should refrain
3754
+
from generating documents with duplicate keys as server and driver behavior
3755
+
may be undefined. Since PHP objects and arrays cannot have duplicate keys,
3756
+
data could also be lost when decoding a BSON document with duplicate keys.
3757
+
</simpara>
3758
+
</warning>
3759
+
'>
3760
+
2731
3761
<!-- Radius -->
2732
3762
<!ENTITY radius.request.required '<note xmlns="http://docbook.org/ns/docbook"><para>A request must be created via <function>radius_create_request</function> before this function can be called.</para></note>'>
2733
3763
<!ENTITY radius.parameter.attribute-type '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>type</parameter></term><listitem><para>The attribute type.</para></listitem></varlistentry>'>
...
...
@@ -2738,7 +3768,7 @@ local: {
2738
3768
2739
3769
<!-- posix snippets -->
2740
3770
<!ENTITY posix.parameter.fd '<varlistentry xmlns="http://docbook.org/ns/docbook">
2741
-
<term><parameter>fd</parameter></term>
3771
+
<term><parameter>file_descriptor</parameter></term>
2742
3772
<listitem>
2743
3773
<para>
2744
3774
The file descriptor, which is expected to be either a file
...
...
@@ -2746,9 +3776,6 @@ local: {
2746
3776
will be assumed to be a file descriptor that can be passed directly to
2747
3777
the underlying system call.
2748
3778
</para>
2749
-
<para>
2750
-
In almost all cases, you will want to provide a file <type>resource</type>.
2751
-
</para>
2752
3779
</listitem>
2753
3780
</varlistentry>'>
2754
3781
...
...
@@ -2763,6 +3790,204 @@ local: {
2763
3790
'>
2764
3791
2765
3792
<!-- strings snippets -->
3793
+
<!ENTITY strings.stripped.characters '
3794
+
<itemizedlist xmlns="http://docbook.org/ns/docbook">
3795
+
<listitem>
3796
+
<simpara>
3797
+
<literal>" "</literal>: <acronym>ASCII</acronym> <acronym>SP</acronym> character
3798
+
<literal>0x20</literal>, an ordinary space.
3799
+
</simpara>
3800
+
</listitem>
3801
+
<listitem>
3802
+
<simpara>
3803
+
<literal>"\t"</literal>: <acronym>ASCII</acronym> <acronym>HT</acronym> character
3804
+
<literal>0x09</literal>, a tab.
3805
+
</simpara>
3806
+
</listitem>
3807
+
<listitem>
3808
+
<simpara>
3809
+
<literal>"\n"</literal>: <acronym>ASCII</acronym> <acronym>LF</acronym> character
3810
+
<literal>0x0A</literal>, a new line (line feed).
3811
+
</simpara>
3812
+
</listitem>
3813
+
<listitem>
3814
+
<simpara>
3815
+
<literal>"\r"</literal>: <acronym>ASCII</acronym> <acronym>CR</acronym> character
3816
+
<literal>0x0D</literal>, a carriage return.
3817
+
</simpara>
3818
+
</listitem>
3819
+
<listitem>
3820
+
<simpara>
3821
+
<literal>"\0"</literal>: <acronym>ASCII</acronym> <acronym>NUL</acronym> character
3822
+
<literal>0x00</literal>, the NUL-byte.
3823
+
</simpara>
3824
+
</listitem>
3825
+
<listitem>
3826
+
<simpara>
3827
+
<literal>"\v"</literal>: <acronym>ASCII</acronym> <acronym>VT</acronym>
3828
+
character <literal>0x0B</literal>, a vertical tab.
3829
+
</simpara>
3830
+
</listitem>
3831
+
</itemizedlist>
3832
+
'>
3833
+
3834
+
<!ENTITY strings.stripped.unicode '
3835
+
<itemizedlist xmlns="http://docbook.org/ns/docbook">
3836
+
<listitem>
3837
+
<simpara>
3838
+
<literal>" "</literal> (<acronym>Unicode</acronym> U+0020), an ordinary space.
3839
+
</simpara>
3840
+
</listitem>
3841
+
<listitem>
3842
+
<simpara>
3843
+
<literal>"\t"</literal> (<acronym>Unicode</acronym> U+0009), a tab.
3844
+
</simpara>
3845
+
</listitem>
3846
+
<listitem>
3847
+
<simpara>
3848
+
<literal>"\n"</literal> (<acronym>Unicode</acronym> U+000A), a new line (line feed).
3849
+
</simpara>
3850
+
</listitem>
3851
+
<listitem>
3852
+
<simpara>
3853
+
<literal>"\r"</literal> (<acronym>Unicode</acronym> U+000D), a carriage return.
3854
+
</simpara>
3855
+
</listitem>
3856
+
<listitem>
3857
+
<simpara>
3858
+
<literal>"\0"</literal> (<acronym>Unicode</acronym> U+0000), the NUL-byte.
3859
+
</simpara>
3860
+
</listitem>
3861
+
<listitem>
3862
+
<simpara>
3863
+
<literal>"\v"</literal> (<acronym>Unicode</acronym> U+000B), a vertical tab.
3864
+
</simpara>
3865
+
</listitem>
3866
+
<listitem>
3867
+
<simpara>
3868
+
<literal>"\f"</literal> (<acronym>Unicode</acronym> U+000C), a form feed.
3869
+
</simpara>
3870
+
</listitem>
3871
+
<listitem>
3872
+
<simpara>
3873
+
<literal>"\u00A0"</literal> (<acronym>Unicode</acronym> U+00A0), a NO-BREAK SPACE.
3874
+
</simpara>
3875
+
</listitem>
3876
+
<listitem>
3877
+
<simpara>
3878
+
<literal>"\u1680"</literal> (<acronym>Unicode</acronym> U+1680), a OGHAM SPACE MARK.
3879
+
</simpara>
3880
+
</listitem>
3881
+
<listitem>
3882
+
<simpara>
3883
+
<literal>"\u2000"</literal> (<acronym>Unicode</acronym> U+2000), a EN QUAD.
3884
+
</simpara>
3885
+
</listitem>
3886
+
<listitem>
3887
+
<simpara>
3888
+
<literal>"\u2001"</literal> (<acronym>Unicode</acronym> U+2001), a EM QUAD.
3889
+
</simpara>
3890
+
</listitem>
3891
+
<listitem>
3892
+
<simpara>
3893
+
<literal>"\u2002"</literal> (<acronym>Unicode</acronym> U+2002), a EN SPACE.
3894
+
</simpara>
3895
+
</listitem>
3896
+
<listitem>
3897
+
<simpara>
3898
+
<literal>"\u2003"</literal> (<acronym>Unicode</acronym> U+2003), a EM SPACE.
3899
+
</simpara>
3900
+
</listitem>
3901
+
<listitem>
3902
+
<simpara>
3903
+
<literal>"\u2004"</literal> (<acronym>Unicode</acronym> U+2004), a THREE-PER-EM SPACE.
3904
+
</simpara>
3905
+
</listitem>
3906
+
<listitem>
3907
+
<simpara>
3908
+
<literal>"\u2005"</literal> (<acronym>Unicode</acronym> U+2005), a FOUR-PER-EM SPACE.
3909
+
</simpara>
3910
+
</listitem>
3911
+
<listitem>
3912
+
<simpara>
3913
+
<literal>"\u2006"</literal> (<acronym>Unicode</acronym> U+2006), a SIX-PER-EM SPACE.
3914
+
</simpara>
3915
+
</listitem>
3916
+
<listitem>
3917
+
<simpara>
3918
+
<literal>"\u2007"</literal> (<acronym>Unicode</acronym> U+2007), a FIGURE SPACE.
3919
+
</simpara>
3920
+
</listitem>
3921
+
<listitem>
3922
+
<simpara>
3923
+
<literal>"\u2008"</literal> (<acronym>Unicode</acronym> U+2008), a PUNCTUATION SPACE.
3924
+
</simpara>
3925
+
</listitem>
3926
+
<listitem>
3927
+
<simpara>
3928
+
<literal>"\u2009"</literal> (<acronym>Unicode</acronym> U+2009), a THIN SPACE.
3929
+
</simpara>
3930
+
</listitem>
3931
+
<listitem>
3932
+
<simpara>
3933
+
<literal>"\u200A"</literal> (<acronym>Unicode</acronym> U+200A), a HAIR SPACE.
3934
+
</simpara>
3935
+
</listitem>
3936
+
<listitem>
3937
+
<simpara>
3938
+
<literal>"\u2028"</literal> (<acronym>Unicode</acronym> U+2028), a LINE SEPARATOR.
3939
+
</simpara>
3940
+
</listitem>
3941
+
<listitem>
3942
+
<simpara>
3943
+
<literal>"\u2029"</literal> (<acronym>Unicode</acronym> U+2029), a PARAGRAPH SEPARATOR.
3944
+
</simpara>
3945
+
</listitem>
3946
+
<listitem>
3947
+
<simpara>
3948
+
<literal>"\u202F"</literal> (<acronym>Unicode</acronym> U+202F), a NARROW NO-BREAK SPACE.
3949
+
</simpara>
3950
+
</listitem>
3951
+
<listitem>
3952
+
<simpara>
3953
+
<literal>"\u205F"</literal> (<acronym>Unicode</acronym> U+205F), a MEDIUM MATHEMATICAL SPACE.
3954
+
</simpara>
3955
+
</listitem>
3956
+
<listitem>
3957
+
<simpara>
3958
+
<literal>"\u3000"</literal> (<acronym>Unicode</acronym> U+3000), a IDEOGRAPHIC SPACE.
3959
+
</simpara>
3960
+
</listitem>
3961
+
<listitem>
3962
+
<simpara>
3963
+
<literal>"\u0085"</literal> (<acronym>Unicode</acronym> U+0085), a NEXT LINE (NEL).
3964
+
</simpara>
3965
+
</listitem>
3966
+
<listitem>
3967
+
<simpara>
3968
+
<literal>"\u180E"</literal> (<acronym>Unicode</acronym> U+180E), a MONGOLIAN VOWEL SEPARATOR.
3969
+
</simpara>
3970
+
</listitem>
3971
+
</itemizedlist>
3972
+
'>
3973
+
3974
+
<!ENTITY strings.parameter.characters.optional '
3975
+
<simpara xmlns="http://docbook.org/ns/docbook">
3976
+
Optionally, the stripped characters can also be specified using
3977
+
the <parameter>characters</parameter> parameter.
3978
+
Simply list all characters that need to be stripped.
3979
+
With <literal>..</literal> it is possible to specify an incrementing range of characters.
3980
+
</simpara>
3981
+
'>
3982
+
3983
+
<!ENTITY strings.parameter.unicode.optional '
3984
+
<simpara xmlns="http://docbook.org/ns/docbook">
3985
+
Optionally, the stripped characters can also be specified using
3986
+
the <parameter>characters</parameter> parameter.
3987
+
Simply list all characters that need to be stripped.
3988
+
</simpara>
3989
+
'>
3990
+
2766
3991
<!ENTITY strings.parameter.encoding '
2767
3992
<para xmlns="http://docbook.org/ns/docbook">
2768
3993
An optional argument defining the encoding used when converting characters.
...
...
@@ -2807,71 +4032,77 @@ local: {
2807
4032
</para>
2808
4033
</formalpara>
2809
4034
2810
-
<para>
2811
-
<table>
2812
-
<title>Flags</title>
2813
-
<tgroup cols="2">
2814
-
<thead>
2815
-
<row>
2816
-
<entry>Flag</entry>
2817
-
<entry>&Description;</entry>
2818
-
</row>
2819
-
</thead>
2820
-
<tbody>
2821
-
<row>
2822
-
<entry><literal>-</literal></entry>
2823
-
<entry>
2824
-
Left-justify within the given field width;
2825
-
Right justification is the default
2826
-
</entry>
2827
-
</row>
2828
-
<row>
2829
-
<entry><literal>+</literal></entry>
2830
-
<entry>
2831
-
Prefix positive numbers with a plus sign
2832
-
<literal>+</literal>; Default only negative
2833
-
are prefixed with a negative sign.
2834
-
</entry>
2835
-
</row>
2836
-
<row>
2837
-
<entry><literal> </literal>(space)</entry>
2838
-
<entry>
2839
-
Pads the result with spaces.
2840
-
This is the default.
2841
-
</entry>
2842
-
</row>
2843
-
<row>
2844
-
<entry><literal>0</literal></entry>
2845
-
<entry>
2846
-
Only left-pads numbers with zeros.
2847
-
With <literal>s</literal> specifiers this can
2848
-
also right-pad with zeros.
2849
-
</entry>
2850
-
</row>
2851
-
<row>
2852
-
<entry><literal>'</literal>(char)</entry>
2853
-
<entry>
2854
-
Pads the result with the character (char).
2855
-
</entry>
2856
-
</row>
2857
-
</tbody>
2858
-
</tgroup>
2859
-
</table>
2860
-
</para>
4035
+
<formalpara>
4036
+
<title>Flags</title>
4037
+
<para>
4038
+
<informaltable>
4039
+
<tgroup cols="2">
4040
+
<thead>
4041
+
<row>
4042
+
<entry>Flag</entry>
4043
+
<entry>&Description;</entry>
4044
+
</row>
4045
+
</thead>
4046
+
<tbody>
4047
+
<row>
4048
+
<entry><literal>-</literal></entry>
4049
+
<entry>
4050
+
Left-justify within the given field width;
4051
+
Right justification is the default
4052
+
</entry>
4053
+
</row>
4054
+
<row>
4055
+
<entry><literal>+</literal></entry>
4056
+
<entry>
4057
+
Prefix positive numbers with a plus sign
4058
+
<literal>+</literal>; Default only negative
4059
+
are prefixed with a negative sign.
4060
+
</entry>
4061
+
</row>
4062
+
<row>
4063
+
<entry><literal> </literal>(space)</entry>
4064
+
<entry>
4065
+
Pads the result with spaces.
4066
+
This is the default.
4067
+
</entry>
4068
+
</row>
4069
+
<row>
4070
+
<entry><literal>0</literal></entry>
4071
+
<entry>
4072
+
Only left-pads numbers with zeros.
4073
+
With <literal>s</literal> specifiers this can
4074
+
also right-pad with zeros.
4075
+
</entry>
4076
+
</row>
4077
+
<row>
4078
+
<entry><literal>'</literal>(char)</entry>
4079
+
<entry>
4080
+
Pads the result with the character (char).
4081
+
</entry>
4082
+
</row>
4083
+
</tbody>
4084
+
</tgroup>
4085
+
</informaltable>
4086
+
</para>
4087
+
</formalpara>
2861
4088
2862
4089
<formalpara>
2863
4090
<title>Width</title>
2864
4091
<para>
2865
-
An integer that says how many characters (minimum)
2866
-
this conversion should result in.
4092
+
Either an integer that says how many characters (minimum)
4093
+
this conversion should result in, or <literal>*</literal>.
4094
+
If <literal>*</literal> is used, then the width is supplied
4095
+
as an additional integer value preceding the one formatted
4096
+
by the specifier.
2867
4097
</para>
2868
4098
</formalpara>
2869
4099
2870
4100
<formalpara>
2871
4101
<title>Precision</title>
2872
4102
<para>
2873
-
A period <literal>.</literal> followed by an integer
2874
-
who's meaning depends on the specifier:
4103
+
A period <literal>.</literal> optionally followed by
4104
+
either an integer or <literal>*</literal>,
4105
+
whose meaning depends on the specifier:
2875
4106
<itemizedlist>
2876
4107
<listitem>
2877
4108
<simpara>
...
...
@@ -2899,19 +4130,14 @@ local: {
2899
4130
<note>
2900
4131
<simpara>
2901
4132
If the period is specified without an explicit value for precision,
2902
-
0 is assumed.
4133
+
0 is assumed. If <literal>*</literal> is used, the precision is
4134
+
supplied as an additional integer value preceding the one formatted
4135
+
by the specifier.
2903
4136
</simpara>
2904
4137
</note>
2905
4138
</para>
2906
4139
</formalpara>
2907
4140
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
4141
<para>
2916
4142
<table>
2917
4143
<title>Specifiers</title>
...
...
@@ -3056,13 +4282,13 @@ local: {
3056
4282
3057
4283
<warning>
3058
4284
<para>
3059
-
The <literal>c</literal> type specifier ignores padding and width
4285
+
The <literal>c</literal> type specifier ignores padding and width.
3060
4286
</para>
3061
4287
</warning>
3062
4288
3063
4289
<warning>
3064
4290
<para>
3065
-
Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results
4291
+
Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results.
3066
4292
</para>
3067
4293
</warning>
3068
4294
...
...
@@ -3115,6 +4341,44 @@ local: {
3115
4341
</varlistentry>
3116
4342
'>
3117
4343
4344
+
<!ENTITY strings.scanf.parameter.format '
4345
+
<varlistentry xmlns="http://docbook.org/ns/docbook">
4346
+
<term><parameter>format</parameter></term>
4347
+
<listitem>
4348
+
<para>
4349
+
The interpreted format for <parameter>string</parameter>, which is
4350
+
described in the documentation for <function>sprintf</function> with
4351
+
following differences:
4352
+
<simplelist>
4353
+
<member>
4354
+
Function is not locale-aware.
4355
+
</member>
4356
+
<member>
4357
+
<literal>F</literal>, <literal>g</literal>, <literal>G</literal> and
4358
+
<literal>b</literal> are not supported.
4359
+
</member>
4360
+
<member>
4361
+
<literal>D</literal> stands for decimal number.
4362
+
</member>
4363
+
<member>
4364
+
<literal>i</literal> stands for integer with base detection.
4365
+
</member>
4366
+
<member>
4367
+
<literal>n</literal> stands for number of characters processed so far.
4368
+
</member>
4369
+
<member>
4370
+
<literal>s</literal> stops reading at any whitespace character.
4371
+
</member>
4372
+
<member>
4373
+
<literal>*</literal> instead of <literal>argnum$</literal> suppresses
4374
+
the assignment of this conversion specification.
4375
+
</member>
4376
+
</simplelist>
4377
+
</para>
4378
+
</listitem>
4379
+
</varlistentry>
4380
+
'>
4381
+
3118
4382
<!ENTITY strings.parameter.needle.non-string '
3119
4383
<para xmlns="http://docbook.org/ns/docbook">
3120
4384
Prior to PHP 8.0.0, if <parameter>needle</parameter> is not a string, it is converted
...
...
@@ -3126,6 +4390,13 @@ local: {
3126
4390
</para>
3127
4391
'>
3128
4392
4393
+
<!ENTITY strings.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
4394
+
<entry>8.0.0</entry>
4395
+
<entry>
4396
+
<parameter>needle</parameter> now accepts an empty string.
4397
+
</entry>
4398
+
</row>'>
4399
+
3129
4400
<!ENTITY strings.changelog.encoding '
3130
4401
<row xmlns="http://docbook.org/ns/docbook">
3131
4402
<entry>5.6.0</entry>
...
...
@@ -3138,19 +4409,193 @@ local: {
3138
4409
</row>
3139
4410
'>
3140
4411
4412
+
<!ENTITY strings.changelog.ascii-case-conversion '
4413
+
<row xmlns="http://docbook.org/ns/docbook">
4414
+
<entry>8.2.0</entry>
4415
+
<entry>
4416
+
Case conversion no longer depends on the locale set with
4417
+
<function>setlocale</function>. Only ASCII characters will be converted.
4418
+
</entry>
4419
+
</row>
4420
+
'>
4421
+
4422
+
<!ENTITY strings.changelog.ascii-case-folding '
4423
+
<row xmlns="http://docbook.org/ns/docbook">
4424
+
<entry>8.2.0</entry>
4425
+
<entry>
4426
+
Case folding no longer depends on the locale set with
4427
+
<function>setlocale</function>. Only ASCII case folding will be done.
4428
+
Non-ASCII bytes will be compared by their byte value.
4429
+
</entry>
4430
+
</row>
4431
+
'>
4432
+
4433
+
<!ENTITY strings.changelog.sprintf '
4434
+
<informaltable xmlns="http://docbook.org/ns/docbook">
4435
+
<tgroup cols="2">
4436
+
<thead>
4437
+
<row>
4438
+
<entry>&Version;</entry>
4439
+
<entry>&Description;</entry>
4440
+
</row>
4441
+
</thead>
4442
+
<tbody>
4443
+
<row>
4444
+
<entry>8.0.0</entry>
4445
+
<entry>
4446
+
This function no longer returns &false; on failure.
4447
+
</entry>
4448
+
</row>
4449
+
<row>
4450
+
<entry>8.0.0</entry>
4451
+
<entry>
4452
+
Throw a <classname>ValueError</classname> if the number of arguments is zero;
4453
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4454
+
</entry>
4455
+
</row>
4456
+
<row>
4457
+
<entry>8.0.0</entry>
4458
+
<entry>
4459
+
Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4460
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4461
+
</entry>
4462
+
</row>
4463
+
<row>
4464
+
<entry>8.0.0</entry>
4465
+
<entry>
4466
+
Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4467
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4468
+
</entry>
4469
+
</row>
4470
+
<row>
4471
+
<entry>8.0.0</entry>
4472
+
<entry>
4473
+
Throw a <classname>ArgumentCountError</classname> when less arguments are given than required;
4474
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4475
+
</entry>
4476
+
</row>
4477
+
</tbody>
4478
+
</tgroup>
4479
+
</informaltable>
4480
+
'>
4481
+
4482
+
<!ENTITY strings.changelog.vsprintf '
4483
+
<informaltable xmlns="http://docbook.org/ns/docbook">
4484
+
<tgroup cols="2">
4485
+
<thead>
4486
+
<row>
4487
+
<entry>&Version;</entry>
4488
+
<entry>&Description;</entry>
4489
+
</row>
4490
+
</thead>
4491
+
<tbody>
4492
+
<row>
4493
+
<entry>8.0.0</entry>
4494
+
<entry>
4495
+
This function no longer returns &false; on failure.
4496
+
</entry>
4497
+
</row>
4498
+
<row>
4499
+
<entry>8.0.0</entry>
4500
+
<entry>
4501
+
Throw a <classname>ValueError</classname> if the number of arguments is zero;
4502
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4503
+
</entry>
4504
+
</row>
4505
+
<row>
4506
+
<entry>8.0.0</entry>
4507
+
<entry>
4508
+
Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4509
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4510
+
</entry>
4511
+
</row>
4512
+
<row>
4513
+
<entry>8.0.0</entry>
4514
+
<entry>
4515
+
Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
4516
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4517
+
</entry>
4518
+
</row>
4519
+
<row>
4520
+
<entry>8.0.0</entry>
4521
+
<entry>
4522
+
Throw a <classname>ValueError</classname> when less arguments are given than required;
4523
+
previously this function emitted a <constant>E_WARNING</constant> instead.
4524
+
</entry>
4525
+
</row>
4526
+
</tbody>
4527
+
</tgroup>
4528
+
</informaltable>
4529
+
'>
4530
+
4531
+
<!ENTITY strings.errors.sprintf '
4532
+
<para xmlns="http://docbook.org/ns/docbook">
4533
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
4534
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4535
+
</para>
4536
+
<para xmlns="http://docbook.org/ns/docbook">
4537
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4538
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4539
+
</para>
4540
+
<para xmlns="http://docbook.org/ns/docbook">
4541
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4542
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4543
+
</para>
4544
+
<para xmlns="http://docbook.org/ns/docbook">
4545
+
As of PHP 8.0.0, a <classname>ArgumentCountError</classname> is thrown when less arguments are given than required.
4546
+
Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
4547
+
</para>
4548
+
'>
4549
+
4550
+
<!ENTITY strings.errors.vsprintf '
4551
+
<para xmlns="http://docbook.org/ns/docbook">
4552
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
4553
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4554
+
</para>
4555
+
<para xmlns="http://docbook.org/ns/docbook">
4556
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4557
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4558
+
</para>
4559
+
<para xmlns="http://docbook.org/ns/docbook">
4560
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.
4561
+
Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
4562
+
</para>
4563
+
<para xmlns="http://docbook.org/ns/docbook">
4564
+
As of PHP 8.0.0, a <classname>ValueError</classname> is thrown when less arguments are given than required.
4565
+
Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
4566
+
</para>
4567
+
'>
4568
+
4569
+
<!ENTITY strings.comparison.return '
4570
+
<simpara xmlns="http://docbook.org/ns/docbook">
4571
+
Returns a value less than 0 if <parameter>string1</parameter>
4572
+
is less than <parameter>string2</parameter>; a value greater
4573
+
than 0 if <parameter>string1</parameter> is greater than
4574
+
<parameter>string2</parameter>, and <literal>0</literal> if they
4575
+
are equal.
4576
+
No particular meaning can be reliably inferred from the value aside
4577
+
from its sign.
4578
+
</simpara>
4579
+
'>
4580
+
3141
4581
<!-- filter snippets -->
4582
+
<!-- TODO: Remove -->
3142
4583
<!ENTITY filter.param.filter '
3143
4584
<varlistentry xmlns="http://docbook.org/ns/docbook">
3144
4585
<term><parameter>filter</parameter></term>
3145
4586
<listitem>
3146
4587
<para>
3147
-
The ID of the filter to apply. The <xref linkend="filter.filters" />
3148
-
manual page lists the available filters.
4588
+
The filter to apply.
4589
+
Can be a validation filter by using one of the
4590
+
<constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>
4591
+
constants, a sanitization filter by using one of the
4592
+
<constant>FILTER_SANITIZE_<replaceable>*</replaceable></constant>
4593
+
or <constant>FILTER_UNSAFE_RAW</constant>, or a custom filter by using
4594
+
<constant>FILTER_CALLBACK</constant>.
3149
4595
</para>
3150
4596
<para>
3151
-
If omitted, <constant>FILTER_DEFAULT</constant> will be used, which is
3152
-
equivalent to
3153
-
<link linkend="filter.filters.sanitize"><constant>FILTER_UNSAFE_RAW</constant></link>.
4597
+
The default is <constant>FILTER_DEFAULT</constant>,
4598
+
which is an alias of <constant>FILTER_UNSAFE_RAW</constant>.
3154
4599
This will result in no filtering taking place by default.
3155
4600
</para>
3156
4601
</listitem>
...
...
@@ -3160,34 +4605,65 @@ local: {
3160
4605
<!-- csprng snippets -->
3161
4606
<!ENTITY csprng.sources '
3162
4607
<para xmlns="http://docbook.org/ns/docbook">
3163
-
The sources of randomness used for this function are as follows:
4608
+
The sources of randomness in the order of priority are as follows:
3164
4609
</para>
3165
4610
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3166
4611
<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>
4612
+
<para>
4613
+
Linux: <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4614
+
</para>
3174
4615
</listitem>
3175
4616
<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>
4617
+
<para>
4618
+
FreeBSD >= 12 (PHP >= 7.3): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4619
+
</para>
4620
+
</listitem>
4621
+
<listitem>
4622
+
<para>
4623
+
Windows (PHP >= 7.2): <link xlink:href="&url.csprng.cng-api;">CNG-API</link>
4624
+
</para>
4625
+
<para>
4626
+
Windows: <link xlink:href="&url.csprng.crypt-gen-random;">CryptGenRandom</link>
4627
+
</para>
4628
+
</listitem>
4629
+
<listitem>
4630
+
<para>
4631
+
macOS (PHP >= 8.2; >= 8.1.9; >= 8.0.22 if CCRandomGenerateBytes is available at compile time): CCRandomGenerateBytes()
4632
+
</para>
4633
+
<para>
4634
+
macOS (PHP >= 8.1; >= 8.0.2): arc4random_buf(), <filename>/dev/urandom</filename>
4635
+
</para>
4636
+
</listitem>
4637
+
<listitem>
4638
+
<para>
4639
+
NetBSD >= 7 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
4640
+
</para>
4641
+
</listitem>
4642
+
<listitem>
4643
+
<para>
4644
+
OpenBSD >= 5.5 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
4645
+
</para>
4646
+
</listitem>
4647
+
<listitem>
4648
+
<para>
4649
+
DragonflyBSD (PHP >= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4650
+
</para>
4651
+
</listitem>
4652
+
<listitem>
4653
+
<para>
4654
+
Solaris (PHP >= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
4655
+
</para>
3181
4656
</listitem>
3182
4657
<listitem>
3183
4658
<simpara>
3184
-
On other platforms, <filename>/dev/urandom</filename> will be used.
4659
+
Any combination of operating system and PHP version not previously mentioned: <filename>/dev/urandom</filename>
3185
4660
</simpara>
3186
4661
</listitem>
3187
4662
<listitem>
3188
4663
<simpara>
3189
-
If none of the aforementioned sources are available, then an
3190
-
<classname>Exception</classname> will be thrown.
4664
+
If none of the sources are available or they all fail to generate
4665
+
randomness, then a <classname>Random\RandomException</classname>
4666
+
will be thrown.
3191
4667
</simpara>
3192
4668
</listitem>
3193
4669
</itemizedlist>
...
...
@@ -3196,13 +4672,7 @@ local: {
3196
4672
<listitem xmlns="http://docbook.org/ns/docbook">
3197
4673
<simpara>
3198
4674
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.
4675
+
a <classname>Random\RandomException</classname> will be thrown.
3206
4676
</simpara>
3207
4677
</listitem>
3208
4678
'>
...
...
@@ -3216,6 +4686,15 @@ local: {
3216
4686
</note>
3217
4687
'>
3218
4688
4689
+
<!-- Random snippets -->
4690
+
<!ENTITY random.engineErrors '
4691
+
<listitem xmlns="http://docbook.org/ns/docbook">
4692
+
<simpara>
4693
+
Any <classname>Throwable</classname>s thrown by the <methodname>Random\Engine::generate</methodname> method
4694
+
of the underlying <link linkend="random-randomizer.props.engine"><literal>Random\Randomizer::$engine</literal></link>.
4695
+
</simpara>
4696
+
</listitem>
4697
+
'>
3219
4698
3220
4699
<!-- UOPZ snippets -->
3221
4700
...
...
@@ -3224,12 +4703,80 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
3224
4703
<emphasis>REMOVED</emphasis> in PECL uopz 5.0.0.</simpara></warning>'>
3225
4704
3226
4705
<!-- XML snippets -->
4706
+
<!ENTITY xml.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
4707
+
<term><parameter>parser</parameter></term>
4708
+
<listitem>
4709
+
<para>
4710
+
The XML parser.
4711
+
</para>
4712
+
</listitem>
4713
+
</varlistentry>'>
4714
+
4715
+
<!ENTITY xml.handler.description '<para xmlns="http://docbook.org/ns/docbook">
4716
+
If &null; is passed, the handler is reset to its default state.
4717
+
<warning>
4718
+
<simpara>
4719
+
An empty string will also reset the handler,
4720
+
however this is deprecated as of PHP 8.4.0.
4721
+
</simpara>
4722
+
</warning>
4723
+
</para>
4724
+
<para xmlns="http://docbook.org/ns/docbook">
4725
+
If <parameter>handler</parameter> is a <type>callable</type>,
4726
+
the callable is set as the handler.
4727
+
</para>
4728
+
<para xmlns="http://docbook.org/ns/docbook">
4729
+
If <parameter>handler</parameter> is a <type>string</type>,
4730
+
it can be the name of a method of an object set with
4731
+
<function>xml_set_object</function>.
4732
+
<warning>
4733
+
<simpara>
4734
+
This is deprecated as of PHP 8.4.0.
4735
+
</simpara>
4736
+
</warning>
4737
+
</para>
4738
+
<warning xmlns="http://docbook.org/ns/docbook">
4739
+
<simpara>
4740
+
As of PHP 8.4.0, the callable is checked to be valid while setting the handler,
4741
+
not when it is called.
4742
+
This means that <function>xml_set_object</function> must be called prior to
4743
+
setting a method string as the callback.
4744
+
However, as this behaviour is also deprecated as of PHP 8.4.0,
4745
+
using a proper <type>callable</type> for the method is recommended instead.
4746
+
</simpara>
4747
+
</warning>
4748
+
'>
4749
+
4750
+
<!ENTITY xml.handler.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
4751
+
<term><parameter>parser</parameter></term>
4752
+
<listitem>
4753
+
<simpara>
4754
+
The XML parser calling the handler.
4755
+
</simpara>
4756
+
</listitem>
4757
+
</varlistentry>'>
4758
+
4759
+
<!ENTITY xml.changelog.handler-param '<row xmlns="http://docbook.org/ns/docbook">
4760
+
<entry>8.4.0</entry>
4761
+
<entry>
4762
+
Passing a non-<type>callable</type> <type>string</type> to
4763
+
<parameter>handler</parameter> is now deprecated,
4764
+
use a proper callable for methods, or &null; to reset the handler.
4765
+
</entry>
4766
+
</row>
4767
+
<row xmlns="http://docbook.org/ns/docbook">
4768
+
<entry>8.4.0</entry>
4769
+
<entry>
4770
+
The validity of <parameter>handler</parameter> as a <type>callable</type>
4771
+
is now checked when setting the handler instead of checking when calling it.
4772
+
</entry>
4773
+
</row>'>
3227
4774
3228
4775
<!ENTITY xml.changelog.parser-param '<row xmlns="http://docbook.org/ns/docbook">
3229
4776
<entry>8.0.0</entry>
3230
4777
<entry>
3231
4778
<parameter>parser</parameter> expects an <classname>XMLParser</classname>
3232
-
instance now; previously, a <type>resource</type> was expected.
4779
+
instance now; previously, a valid <literal>xml</literal> <type>resource</type> was expected.
3233
4780
</entry>
3234
4781
</row>'>
3235
4782
3236
4783