language-snippets.ent

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<!ENTITY installation.enabled.disable 'This extension is enabled by default. It may be disabled by using the following option at compile time: '>

<!ENTITY changelog.class-constants-typed '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.4.0</entry>
 <entry>
  The class constants are now typed.
 </entry>
</row>'>

<!-- Cautions -->
<!ENTITY caution.cryptographically-insecure '<caution xmlns="http://docbook.org/ns/docbook">
 <simpara>
  This function does not generate cryptographically secure values, and <emphasis>must not</emphasis>
  be used for cryptographic purposes, or purposes that require returned values to be unguessable.
 </simpara>
 <simpara>
  If cryptographically secure randomness is required, the <classname>Random\Randomizer</classname> may be
  used with the <classname>Random\Engine\Secure</classname> engine. For simple use cases, the <function>random_int</function>
  and <function>random_bytes</function> functions provide a convenient and secure <acronym>API</acronym> that is backed by
  the operating system’s <acronym>CSPRNG</acronym>.
 </simpara>
</caution>'>

<!ENTITY caution.mt19937-global-state '<caution xmlns="http://docbook.org/ns/docbook">
 <simpara>
    This function uses the global Mt19937 (“Mersenne Twister”) instance as the source of randomness and thus shares its state with all other functions using the global Mt19937.
    Using any of these functions advances the sequence for <emphasis>all</emphasis> the other functions, regardless of scope.
  </simpara>
  <simpara>
    Generating repeatable sequences by seeding <function>mt_srand</function> or <function>srand</function> with a known value will also yield repeatable output from this function.
  </simpara>
  <simpara>
    Prefer using <classname>Random\Randomizer</classname> methods in all newly written code.
 </simpara>
</caution>'>

<!ENTITY caution.mt19937-tiny-seed '<caution xmlns="http://docbook.org/ns/docbook">
 <simpara>
  Because the Mt19937 (“Mersenne Twister”) engine accepts only a single 32 bit integer as the
  seed, the number of possible random sequences is limited to just 2<superscript>32</superscript>
  (i.e. 4,294,967,296), despite Mt19937’s huge period of 2<superscript>19937</superscript>-1.
 </simpara>
 <simpara>
  When relying on either implicit or explicit random seeding, duplications will appear
  much earlier. Duplicated seeds are expected with 50&#37; probability after less than
  80,000 randomly generated seeds according to the birthday problem. A 10&#37; probability
  of a duplicated seed happens after randomly generating roughly 30,000 seeds.
 </simpara>
 <simpara>
  This makes Mt19937 unsuitable for applications where duplicated sequences must not happen with
  more than a negligible probability. If reproducible seeding is required, both the
  <classname>Random\Engine\Xoshiro256StarStar</classname> and <classname>Random\Engine\PcgOneseq128XslRr64</classname>
  engines support much larger seeds that are unlikely to collide randomly. If reproducibility
  is not required, the <classname>Random\Engine\Secure</classname> engine provides cryptographically
  secure randomness.
 </simpara>
</caution>'>

<!-- Notes -->

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

<!ENTITY note.clearstatcache '<note xmlns="http://docbook.org/ns/docbook"><simpara>The results of this
function are cached. See <function>clearstatcache</function> for
more details.</simpara></note>'>

<!ENTITY note.context-support '<simpara xmlns="http://docbook.org/ns/docbook">A <link linkend="stream.contexts">context stream</link>
<type>resource</type>.</simpara>'>

<!ENTITY note.exec-bg '<note xmlns="http://docbook.org/ns/docbook"><simpara>If a program is started with this function,
in order for it to continue running in the background, the output of the
program must be redirected to a file or another output stream. Failing to do so
will cause PHP to hang until the execution of the program ends.</simpara></note>'>

<!ENTITY note.exec-bypass-shell '<note xmlns="http://docbook.org/ns/docbook"><simpara>On Windows <function>exec</function>
will first start cmd.exe to launch the command. If you want to start an external program without starting cmd.exe
use <function>proc_open</function> with the <parameter>bypass_shell</parameter> option set.</simpara></note>'>

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

<!ENTITY note.func-callback-exceptions '<note xmlns="http://docbook.org/ns/docbook"><simpara>Callbacks registered
with functions such as <function>call_user_func</function> and <function>call_user_func_array</function> will not be
called if there is an uncaught exception thrown in a previous callback.</simpara></note>'>

<!ENTITY note.funcbyref '<note xmlns="http://docbook.org/ns/docbook"><simpara>If the arguments are passed by reference,
any changes to the arguments will be reflected in the values returned by this function. As of PHP 7
the current values will also be returned if the arguments are passed by value.</simpara></note>'>

<!ENTITY note.func-named-params '<note xmlns="http://docbook.org/ns/docbook"><simpara>As of PHP 8.0.0, the func_*() family of
functions is intended to be mostly transparent with regard to named arguments,
by treating the arguments as if they were all passed positionally,
and missing arguments are replaced with their defaults.
This function ignores the collection of unknown named variadic arguments.
Unknown named arguments which are collected can only be accessed through the variadic parameter.</simpara></note>'>

<!ENTITY note.line-endings '<note xmlns="http://docbook.org/ns/docbook"><simpara>Prior to PHP 8.1.0, the
<link linkend="ini.auto-detect-line-endings">auto_detect_line_endings</link>
run-time configuration option could be enabled to help PHP properly recognize
line endings when reading files created on Macintosh systems. This option has
been deprecated as of PHP 8.1.0. If necessary, handle <literal>"\r"</literal>
line breaks manually instead.</simpara></note>'>

<!ENTITY note.no-remote '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function will not work on
<link linkend="features.remote-files">remote files</link> as the file to
be examined must be accessible via the server&apos;s filesystem.</simpara></note>'>

<!ENTITY note.not-bin-safe '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function
is not (yet) binary safe!</simpara></warning>'>

<!ENTITY note.no-key-association '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function
assigns new keys to the elements in <parameter>array</parameter>.
It will remove any existing keys that may have been assigned, rather
than just reordering the keys.</simpara></note>'>

<!ENTITY note.no-windows '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is not
implemented on Windows platforms.</simpara></note>'>

<!ENTITY note.no-windows.extension '<note xmlns="http://docbook.org/ns/docbook"><simpara>This extension is not
available on Windows platforms.</simpara></note>'>

<!ENTITY note.no-zts '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is not
available in PHP interpreters built with ZTS (Zend Thread Safety) enabled. To check whether your copy of PHP was built with ZTS enabled, use <command>php -i</command> or test the built-in constant <constant>PHP_ZTS</constant>.</simpara></note>'>

<!ENTITY note.randomseed '<note xmlns="http://docbook.org/ns/docbook"><simpara>There is no need
to seed the random number generator with <function>srand</function> or
<function>mt_srand</function> as this is done automatically.
</simpara></note>'>

<!ENTITY note.is-superglobal "<note xmlns='http://docbook.org/ns/docbook'><simpara>This is a 'superglobal', or
automatic global, variable. This simply means that it is available in
all scopes throughout a script. There is no need to do
<command>global $variable;</command> to access it within functions or methods.
</simpara></note>">

<!ENTITY note.uses-ob '<note xmlns="http://docbook.org/ns/docbook"><simpara>When the <parameter>return</parameter> parameter
is used, this function uses internal output buffering so it cannot be used inside an
<function>ob_start</function> callback function.</simpara></note>'>

<!ENTITY note.uses-ob-php70 '<note xmlns="http://docbook.org/ns/docbook"><simpara>When the <parameter>return</parameter> parameter
is used, this function uses internal output buffering prior to PHP 7.1.0, so it cannot be used inside an
<function>ob_start</function> callback function.</simpara></note>'>

<!ENTITY note.filesystem-time-res '<note xmlns="http://docbook.org/ns/docbook"><simpara>Note that time resolution may differ
from one file system to another.</simpara></note>'>

<!ENTITY note.uses-autoload '<note xmlns="http://docbook.org/ns/docbook">
<simpara>Using this function will use any registered
<link linkend="language.oop5.autoload">autoloaders</link> if the class is not already known.</simpara></note>'>

<!ENTITY note.network.header.sapi '<note xmlns="http://docbook.org/ns/docbook">
   <simpara>
    Headers will only be accessible and output when a SAPI that supports them
    is in use.
   </simpara>
  </note>
'>

<!ENTITY note.sigchild '<note xmlns="http://docbook.org/ns/docbook">
 <simpara>
  If PHP has been compiled with --enable-sigchild, the return value of this function is undefined.
 </simpara>
</note>
'>

<!ENTITY note.sort-unstable '<note xmlns="http://docbook.org/ns/docbook">
 <simpara>
  If two members compare as equal, they retain their original order.
  Prior to PHP 8.0.0, their relative order in the sorted array was undefined.
 </simpara>
</note>
'>

<!ENTITY note.reset-index "<note xmlns='http://docbook.org/ns/docbook'>
 <simpara>
    Resets array's internal pointer to the first element.
 </simpara>
</note>
">

<!ENTITY note.resource-migration-8.0-dead-function '<note xmlns="http://docbook.org/ns/docbook">
 <simpara>
  This function has no effect. Prior to PHP 8.0.0, this function was used to close the resource.
 </simpara>
</note>
'>

<!-- Tips -->

<!ENTITY tip.fopen-wrapper '<tip xmlns="http://docbook.org/ns/docbook"><simpara>A URL can be used as a
filename with this function if the <link linkend="ini.allow-url-fopen"
>fopen wrappers</link> have been enabled.
See <function>fopen</function> for more details on how to specify the
filename. See the <xref linkend="wrappers"/> for links to information
about what abilities the various wrappers have, notes on their usage,
and information on any predefined variables they may
provide.</simpara></tip>'>

<!ENTITY tip.fopen-wrapper.stat '<tip xmlns="http://docbook.org/ns/docbook"><simpara>As of PHP 5.0.0, this function
can also be used with <emphasis>some</emphasis> URL wrappers.  Refer to
<xref linkend="wrappers"/> to determine which wrappers support
<function>stat</function> family of functionality.</simpara></tip>'>

<!ENTITY tip.ob-capture '<tip xmlns="http://docbook.org/ns/docbook"><simpara>As with anything that outputs
its result directly to the browser, the <link
linkend="book.outcontrol">output-control functions</link> can be used to capture
the output of this function, and save it in a
<type>string</type> (for example).</simpara></tip>'>

<!ENTITY tip.userlandnaming '<tip xmlns="http://docbook.org/ns/docbook"><simpara>See also the
<xref linkend="userlandnaming" />.</simpara></tip>'>

<!-- Warnings -->

<!ENTITY warn.escapeshell '<warning xmlns="http://docbook.org/ns/docbook"><simpara>When allowing user-supplied data to be
passed to this function, use
<function>escapeshellarg</function> or <function>escapeshellcmd</function>
to ensure that users cannot trick the system into executing arbitrary
commands.</simpara></warning>'>

<!ENTITY warn.experimental '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This extension is
<emphasis>EXPERIMENTAL</emphasis>. The behaviour of this extension including
the names of its functions and any other documentation surrounding this
extension may change without notice in a future release of PHP.
This extension should be used at your own risk.</simpara></warning>'>

<!ENTITY deprecated.function 'Deprecated this function.'>
<!ENTITY removed.function 'Removed this function.'>

<!ENTITY warn.deprecated.feature-5-6-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
<emphasis>DEPRECATED</emphasis> as of PHP 5.6.0. Relying on this feature
is highly discouraged.</simpara></warning>'>

<!ENTITY warn.deprecated.feature-7-1-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0. Relying on this feature
is highly discouraged.</simpara></warning>'>

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

<!ENTITY warn.deprecated.function-7-1-0.removed-7-2-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0 and
<emphasis>REMOVED</emphasis> as of PHP 7.2.0. Relying on this function
is highly discouraged.</simpara></warning>'>

<!ENTITY warn.deprecated.feature-7-2-0.removed-8-0-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this feature
is highly discouraged.</simpara></warning>'>

<!ENTITY warn.deprecated.function-7-2-0.removed-8-0-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
is highly discouraged.</simpara></warning>'>

<!ENTITY warn.deprecated.feature-7-3-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0. Relying on this feature
is highly discouraged.</simpara></warning>'>

<!ENTITY warn.deprecated.function-7-3-0.removed-8-0-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
is highly discouraged.</simpara></warning>'>

<!ENTITY warn.deprecated.function-7-4-0.removed-8-0-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function
is highly discouraged.</simpara></warning>'>

<!ENTITY warn.feature.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook">
<simpara>This feature was <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara>
</warning>'>

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

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

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

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

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

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

<!ENTITY warn.deprecated.function-8-4-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
<emphasis>DEPRECATED</emphasis> as of PHP 8.4.0. Relying on this function
is highly discouraged.</simpara></warning>'>

<!ENTITY warn.deprecated.feature-8-5-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
<emphasis>DEPRECATED</emphasis> as of PHP 8.5.0. Relying on this feature
is highly discouraged.</simpara></warning>'>

<!ENTITY warn.deprecated.function-8-5-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
<emphasis>DEPRECATED</emphasis> as of PHP 8.5.0. Relying on this function
is highly discouraged.</simpara></warning>'>

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

<!ENTITY warn.deprecated.alias-5-4-0 '<warning xmlns="http://docbook.org/ns/docbook">
<simpara>This alias has been <emphasis>DEPRECATED</emphasis> as of PHP 5.4.0.  Relying
on this alias is highly discouraged.</simpara></warning>'>

<!ENTITY warn.removed.function-7-0-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
<emphasis>REMOVED</emphasis> in PHP 7.0.0.</simpara></warning>'>

<!ENTITY warn.removed.function-7-4-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This function was
<emphasis>REMOVED</emphasis> in PHP 7.4.0.</simpara></warning>'>

<!ENTITY warn.deprecated.alias-7-2-0.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was
<emphasis>DEPRECATED</emphasis> in PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>

<!ENTITY warn.deprecated.alias-7-4-0.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was
<emphasis>DEPRECATED</emphasis> in PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>

<!ENTITY warn.deprecated.alias-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias is
<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0.</simpara></warning>'>

<!ENTITY warn.removed.alias-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias is
<emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>

<!ENTITY warn.removed.feature-8-5-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
<emphasis>REMOVED</emphasis> as of PHP 8.5.0.</simpara></warning>'>

<!ENTITY warn.experimental.func '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function is
<emphasis>EXPERIMENTAL</emphasis>. The behaviour of this function, its name, and
surrounding documentation may change without notice in a future release of PHP.
This function should be used at your own risk.
</simpara></warning>'>

<!ENTITY warn.imaprecodeyaz '<warning xmlns="http://docbook.org/ns/docbook"><simpara>The <link
linkend="book.imap">IMAP</link>, <link linkend="book.recode">recode</link> and
<link linkend="book.yaz">YAZ</link>
extensions cannot be used in conjunction, because they
share the same internal symbols. Note: Yaz 2.0 and above does not suffer from this problem.</simpara></warning>'>

<!ENTITY warn.install.cgi '<warning xmlns="http://docbook.org/ns/docbook"><simpara>A server deployed in CGI mode is open
to several possible vulnerabilities. Please read our
<link linkend="security.cgi-bin">CGI security section</link> to learn how to
defend yourself from such attacks.</simpara></warning>'>

<!ENTITY warn.passwordhashing '
<warning xmlns="http://docbook.org/ns/docbook">
 <simpara>
  It is not recommended to use this function to secure passwords,
  due to the fast nature of this hashing algorithm. See the
  <link linkend="faq.passwords.fasthash">Password Hashing FAQ</link>
  for details and best practices.
 </simpara>
</warning>
'>

<!ENTITY warn.ssl-non-standard '<warning xmlns="http://docbook.org/ns/docbook"><simpara>When using SSL, Microsoft IIS
will violate the protocol by closing the connection without sending a
<literal>close_notify</literal> indicator. PHP will report this as "SSL: Fatal
Protocol Error" when you reach the end of the data. To work around this, the
value of <link linkend="ini.error-reporting">error_reporting</link> should be
lowered to a level that does not include warnings.
PHP can detect buggy IIS server software when you open
the stream using the <literal>https://</literal> wrapper and will suppress the
warning. When using <function>fsockopen</function> to create an
<literal>ssl://</literal> socket, the developer is responsible for detecting
and suppressing this warning.</simpara></warning>'>

<!ENTITY warn.undocumented.func '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function is
currently not documented; only its argument list is available.
</simpara></warning>'>

<!-- Deprecation and removal warnings designed for use with a list of
     alternatives. See en/reference/regex/functions/ereg.xml and
     en/reference/regex/reference.xml for examples of these in action. -->

<!ENTITY warn.deprecated.feature.7-1-0.removed.7-2-0.alternatives '
<simpara xmlns="http://docbook.org/ns/docbook">
 This feature was <emphasis>DEPRECATED</emphasis> in PHP 7.1.0, and
 <emphasis>REMOVED</emphasis> in PHP 7.2.0.
</simpara>
<simpara xmlns="http://docbook.org/ns/docbook">
 Alternatives to this feature include:
</simpara>
'>

<!ENTITY warn.deprecated.function.7-1-0.removed.7-2-0.alternatives '
<simpara xmlns="http://docbook.org/ns/docbook">
 This function was <emphasis>DEPRECATED</emphasis> in PHP 7.1.0, and
 <emphasis>REMOVED</emphasis> in PHP 7.2.0.
</simpara>
<simpara xmlns="http://docbook.org/ns/docbook">
 Alternatives to this function include:
</simpara>
'>

<!ENTITY warn.deprecated.function-8-1-0.alternatives '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
<emphasis>DEPRECATED</emphasis> as of PHP 8.1.0. Relying on this function
is highly discouraged.</simpara></warning>
<simpara xmlns="http://docbook.org/ns/docbook">
 Alternatives to this function include:
</simpara>
'>

<!-- Misc -->

<!ENTITY version.exists.asof 'This exists as of PHP '>

<!ENTITY no.function.parameters '<simpara xmlns="http://docbook.org/ns/docbook">This function has no parameters.</simpara>'>

<!ENTITY example.outputs '<simpara xmlns="http://docbook.org/ns/docbook">The above example will output:</simpara>'>

<!ENTITY example.outputs.5 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5:</simpara>'>

<!ENTITY example.outputs.55 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.5:</simpara>'>

<!ENTITY example.outputs.56 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.6:</simpara>'>

<!ENTITY example.outputs.7 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7:</simpara>'>

<!ENTITY example.outputs.70 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.0:</simpara>'>

<!ENTITY example.outputs.71 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.1:</simpara>'>

<!ENTITY example.outputs.73 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.3:</simpara>'>

<!ENTITY example.outputs.8 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8:</simpara>'>

<!ENTITY example.outputs.8.similar '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8 is similar to:</simpara>'>

<!ENTITY example.outputs.80 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.0:</simpara>'>

<!ENTITY example.outputs.81 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.1:</simpara>'>

<!ENTITY example.outputs.82 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.2:</simpara>'>

<!ENTITY example.outputs.82.similar '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.2 is similar to:</simpara>'>

<!ENTITY example.outputs.83 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.3:</simpara>'>

<!ENTITY example.outputs.83.similar '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.3 is similar to:</simpara>'>

<!ENTITY example.outputs.84 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.4:</simpara>'>

<!ENTITY example.outputs.84.similar '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.4 is similar to:</simpara>'>

<!ENTITY example.outputs.85.similar '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.5 is similar to:</simpara>'>

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

<!ENTITY example.outputs.64bit '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example on 64 bit machines:</simpara>'>

<!ENTITY example.outputs.similar '<simpara xmlns="http://docbook.org/ns/docbook">The above example will output
something similar to:</simpara>'>

<!ENTITY examples.outputs '<simpara xmlns="http://docbook.org/ns/docbook">The above examples will output:</simpara>'>

<!ENTITY examples.outputs.similar '<simpara xmlns="http://docbook.org/ns/docbook">The above examples will output
something similar to:</simpara>'>

<!ENTITY array.resetspointer '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function will
<function>reset</function> the <type>array</type> pointer of the input array after
use.</simpara></note>'>

<!ENTITY array.changelog.by-ref '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  If <parameter>callback</parameter> expects a parameter to be passed
  by reference, this function will now emit an <constant>E_WARNING</constant>.
 </entry>
</row>'>

<!ENTITY array.changelog.require-only-one '<row xmlns="http://docbook.org/ns/docbook">
  <entry>8.0.0</entry>
  <entry>
  This function can now be called with only one parameter.
  Formerly, at least two parameters have been required.
  </entry>
</row>'>

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

<!ENTITY sort.flags.parameter '<varlistentry xmlns="http://docbook.org/ns/docbook">
  <term><parameter>flags</parameter></term>
  <listitem>
   <simpara>
    The optional second parameter <parameter>flags</parameter>
    may be used to modify the sorting behavior using these values:
   </simpara>
   <para>
    Sorting type flags:
    <itemizedlist>
     <listitem>
      <simpara><constant>SORT_REGULAR</constant> - compare items normally;
      the details are described in the <link linkend="language.operators.comparison">comparison operators</link> section</simpara>
     </listitem>
     <listitem>
      <simpara><constant>SORT_NUMERIC</constant> - compare items numerically</simpara>
     </listitem>
     <listitem>
      <simpara><constant>SORT_STRING</constant> - compare items as strings</simpara>
     </listitem>
     <listitem>
      <simpara>
       <constant>SORT_LOCALE_STRING</constant> - compare items as
       strings, based on the current locale. It uses the locale,
       which can be changed using <function>setlocale</function>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <constant>SORT_NATURAL</constant> - compare items as strings
       using "natural ordering" like <function>natsort</function>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <constant>SORT_FLAG_CASE</constant> - can be combined
       (bitwise OR) with
       <constant>SORT_STRING</constant> or
       <constant>SORT_NATURAL</constant> to sort strings case-insensitively
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
  </listitem>
 </varlistentry>
'>

<!ENTITY sort.callback.description '<simpara xmlns="http://docbook.org/ns/docbook">
 &return.callbacksort;
</simpara>
&callback.cmp;
<caution xmlns="http://docbook.org/ns/docbook">
 <simpara>
  Returning <emphasis>non-integer</emphasis> values from the comparison
  function, such as <type>float</type>, will result in an internal cast to
  <type>int</type> of the callback&apos;s return value. So values such as
  <literal>0.99</literal> and <literal>0.1</literal> will both be cast to an
  integer value of <literal>0</literal>, which will compare such values as equal.
 </simpara>
</caution>'>

<!ENTITY sort.callback.description.presort '<caution xmlns="http://docbook.org/ns/docbook">
 <para>
  The sorting callback must handle any value from any array in any order,
  regardless of the order they were originally provided.
  This is because each individual array is first sorted before being compared against other arrays.

  For example:
  <programlisting role="php">
<![CDATA[
<?php
$arrayA = ["string", 1];
$arrayB = [["value" => 1]];
// $item1 and $item2 can be any of "string", 1 or ["value" => 1]
$compareFunc = static function ($item1, $item2) {
    $value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);
    $value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);
    return $value1 <=> $value2;
};
?>
]]>
  </programlisting>
 </para>
</caution>'>

<!ENTITY ini.shorthandbytes '<simpara xmlns="http://docbook.org/ns/docbook">When an <type>int</type> is used, the
value is measured in bytes. Shorthand notation, as described
in <link linkend="faq.using.shorthandbytes">this FAQ</link>, may also be used.
</simpara>'>

<!ENTITY info.deprecated.alias 'For backward compatibility, the following
deprecated alias may be used: '>

<!ENTITY info.function.alias 'This function is an alias of: '>

<!ENTITY info.method.alias 'This method is an alias of: '>

<!ENTITY ext.windows.path.dll 'In order for this extension to work, there are
<acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> files that must be available to the Windows
system <envar xmlns="http://docbook.org/ns/docbook">PATH</envar>. For information on how to do this, see the
<acronym xmlns="http://docbook.org/ns/docbook">FAQ</acronym> entitled "<link
 xmlns="http://docbook.org/ns/docbook" linkend="faq.installation.addtopath">How do I add my PHP directory to the PATH
on Windows</link>". Although copying DLL
files from the PHP folder into the Windows system directory also works
(because the system directory is by default in the system&apos;s
<envar xmlns="http://docbook.org/ns/docbook">PATH</envar>), this is not recommended.
<emphasis xmlns="http://docbook.org/ns/docbook">This extension requires the following files to be in the
<envar>PATH</envar>:</emphasis> '>

<!ENTITY manual.migration.seealso 'See also the migration guides for PHP versions'>

<!ENTITY style.oop 'Object-oriented style'>
<!ENTITY style.procedural 'Procedural style'>

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

<!ENTITY parameter.context 'Refer to the <link xmlns="http://docbook.org/ns/docbook" linkend="context">context</link>
section of the manual for a description of <literal xmlns="http://docbook.org/ns/docbook">contexts</literal>.'>

<!ENTITY parameter.use_include_path 'When set to &true;, the filename is also
searched for within the <link xmlns="http://docbook.org/ns/docbook" linkend="ini.include-path">include_path</link>'>

<!-- Returns -->

<!ENTITY return.type.true '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.2.0</entry>
 <entry>
  The return type is &true; now; previously, it was <type>bool</type>.
 </entry>
</row>'>

<!ENTITY return.type.true.84 '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.4.0</entry>
 <entry>
  The return type is &true; now; previously, it was <type>bool</type>.
 </entry>
</row>'>

<!ENTITY return.type.true.85 '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.5.0</entry>
 <entry>
  The return type is &true; now; previously, it was <type>bool</type>.
 </entry>
</row>'>

<!ENTITY return.falseforfailure ' or &false; on failure'>
<!ENTITY return.falseforfailure.style.procedural '&style.procedural; returns &false; on failure.'>

<!ENTITY return.success 'Returns &true; on success&return.falseforfailure;.'>

<!ENTITY return.nullorfalse 'Returns &null; on success&return.falseforfailure;.'>

<!ENTITY return.void 'No value is returned.'>

<!ENTITY return.true.always 'Always returns &true;.'>

<!ENTITY return.callbacksort 'The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.'>

<!ENTITY return.falseproblem '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function may
return Boolean &false;, but may also return a non-Boolean value which
evaluates to &false;. Please read the section on <link
linkend="language.types.boolean">Booleans</link> for more
information. Use <link linkend="language.operators.comparison">the ===
operator</link> for testing the return value of this
function.</simpara></warning>'>

<!-- Standard -->
<!ENTITY standard.changelog.calling-on-objects '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.1.0</entry>
 <entry>
  Calling this function on &object;s is deprecated.
  Either convert the &object; to an &array; using <function>get_mangled_object_vars</function> first, or use the methods
  provided by a class that implements <interfacename>Iterator</interfacename>, such as <classname>ArrayIterator</classname>, instead.
 </entry>
</row>
<row xmlns="http://docbook.org/ns/docbook">
 <entry>7.4.0</entry>
 <entry>
  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.
 </entry>
</row>
'>

<!ENTITY standard.changelog.binary-safe-string-comparison '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.2.0</entry>
 <entry>
  This function is no longer guaranteed to return
  <code>strlen($string1) - strlen($string2)</code> when string lengths
  are not equal, but may now return <literal>-1</literal> or
  <literal>1</literal> instead.
 </entry>
</row>
'>

<!-- FileInfo -->
<!ENTITY fileinfo.parameters.finfo '<simpara xmlns="http://docbook.org/ns/docbook">An <classname>finfo</classname> instance, returned by <function>finfo_open</function>.</simpara>'>
<!ENTITY fileinfo.changelog.finfo-object '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.1.0</entry>
 <entry>
  The <parameter>finfo</parameter> parameter expects an <classname>finfo</classname>
  instance now; previously, a &resource; was expected.
 </entry>
</row>'>

<!-- OpenSSL -->
<!ENTITY openssl.param.x509 '<varlistentry xmlns="http://docbook.org/ns/docbook">
 <term><parameter>certificate</parameter></term>
 <listitem>
  <simpara>
   See <link linkend="openssl.certparams">Key/Certificate parameters</link> for a list of valid values.
  </simpara>
 </listitem>
</varlistentry>'>

<!ENTITY openssl.param.csr '<varlistentry xmlns="http://docbook.org/ns/docbook">
 <term><parameter>csr</parameter></term>
 <listitem>
  <simpara>
   See <link linkend="openssl.certparams">CSR parameters</link> for a list of valid values.
  </simpara>
 </listitem>
</varlistentry>'>

<!-- Image (GD) Notes -->

<!ENTITY note.freetype '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available if
PHP is compiled with freetype support (<option role="configure">--with-freetype-dir=DIR</option>)
</simpara></note>'>

<!ENTITY note.gd.notrequired '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function does not require the GD image library.</simpara></note>'>

<!ENTITY note.gd.interpolation '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is affected by the interpolation method set by <function>imagesetinterpolation</function>.</simpara></note>'>

<!ENTITY gd.image.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
<parameter>image</parameter></term><listitem><simpara>A <classname>GdImage</classname> object, returned by one of the image creation functions,
such as <function>imagecreatetruecolor</function>.</simpara></listitem></varlistentry>'>

<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
<parameter>font</parameter></term><listitem><simpara>Can be 1, 2, 3, 4, 5 for built-in
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or <classname>GdFont</classname> instance,
returned by <function>imageloadfont</function>.</simpara></listitem></varlistentry>'>

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

<!ENTITY gd.ttf.fontfile "
    <varlistentry xmlns='http://docbook.org/ns/docbook'>
     <term><parameter>fontfile</parameter></term>
     <listitem>
      <simpara>
       The path to the TrueType font you wish to use.
      </simpara>
      <simpara>
       Depending on which version of the GD library PHP is using, <emphasis>when
       <parameter>fontfile</parameter> does not begin with a leading
       <literal>/</literal> then <literal>.ttf</literal> will be appended</emphasis>
       to the filename and the library will attempt to search for that
       filename along a library-defined font path.
      </simpara>
      <simpara>
       When using versions of the GD library lower than 2.0.18, a <literal>space</literal> character,
       rather than a semicolon, was used as the 'path separator' for different font files.
       Unintentional use of this feature will result in the warning message:
       <literal>Warning: Could not find/open font</literal>. For these affected versions, the
       only solution is moving the font to a path which does not contain spaces.
      </simpara>
      <para>
       In many cases where a font resides in the same directory as the script using it
       the following trick will alleviate any include problems.
       <programlisting role='php'>
<![CDATA[
<?php
// Set the environment variable for GD
putenv('GDFONTPATH=' . realpath('.'));

// Name the font to be used (note the lack of the .ttf extension)
$font = 'SomeFont';
?>
]]>
       </programlisting>
      </para>
      <note>
       <simpara>
        Note that <link linkend='ini.open-basedir'>open_basedir</link> does
        <emphasis>not</emphasis> apply to <parameter>fontfile</parameter>.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
">

<!ENTITY gd.return.identifier 'Returns an image object on success, &false; on errors.'>

<!ENTITY gd.return.trueonerror '<caution xmlns="http://docbook.org/ns/docbook"><simpara>However, if libgd fails to output the image, this function returns &true;.</simpara></caution>'>

<!ENTITY gd.identifier.color "A color identifier created with <function xmlns='http://docbook.org/ns/docbook'>imagecolorallocate</function>.">

<!ENTITY gd.value.red 'Value of red component.'>

<!ENTITY gd.value.green 'Value of green component.'>

<!ENTITY gd.value.blue 'Value of blue component.'>

<!ENTITY gd.source.height 'Source height.'>

<!ENTITY gd.source.width 'Source width.'>

<!ENTITY gd.image.path 'The path or an open stream resource (which is automatically closed after this function returns) to save the file to. If not set or &null;, the raw image stream will be output directly.'>

<!ENTITY gd.image.new 'Create a new image from file or URL'>

<!ENTITY gd.image.source 'Source image resource.'>

<!ENTITY gd.image.destination 'Destination image resource.'>

<!ENTITY gd.image.output 'Output image to browser or file'>

<!ENTITY gd.image.colors 'If you created the image from a file, only colors used in the image are resolved. Colors present only in the palette are not resolved.'>

<!ENTITY gd.font.size 'The font size in points.'>

<!ENTITY gd.constants.types '<simpara xmlns="http://docbook.org/ns/docbook">
    Used as a return value by <function>imagetypes</function>
</simpara>'>

<!ENTITY gd.constants.color '<simpara xmlns="http://docbook.org/ns/docbook">
    Special color option which can be used instead of a color allocated with
    <function>imagecolorallocate</function> or
    <function>imagecolorallocatealpha</function>.
</simpara>'>

<!ENTITY gd.constants.affine '<simpara xmlns="http://docbook.org/ns/docbook">
    An affine transformation type constant used by the <function>imageaffinematrixget</function> function.
</simpara>'>

<!ENTITY gd.constants.arc '<simpara xmlns="http://docbook.org/ns/docbook">
    A style constant used by the <function>imagefilledarc</function> function.
</simpara>'>

<!ENTITY gd.constants.gd2 '<simpara xmlns="http://docbook.org/ns/docbook">
    A type constant used by the <function>imagegd2</function> function.
</simpara>'>

<!ENTITY gd.constants.effect '<simpara xmlns="http://docbook.org/ns/docbook">
    Alpha blending effect used by the <function>imagelayereffect</function> function.
</simpara>'>

<!ENTITY gd.constants.filter '<simpara xmlns="http://docbook.org/ns/docbook">
    Special GD filter used by the <function>imagefilter</function> function.
</simpara>'>

<!ENTITY gd.constants.type '<simpara xmlns="http://docbook.org/ns/docbook">
    Image type constant used by the <function>image_type_to_mime_type</function>
    and <function>image_type_to_extension</function> functions.
</simpara>'>

<!ENTITY gd.constants.png-filter '<simpara xmlns="http://docbook.org/ns/docbook">
    A special PNG filter, used by the <function>imagepng</function> function.
</simpara>'>

<!ENTITY gd.constants.flip '<simpara xmlns="http://docbook.org/ns/docbook">
    Used together with <function>imageflip</function>, available as of PHP 5.5.0.
</simpara>'>

<!ENTITY gd.constants.interpolation '<simpara xmlns="http://docbook.org/ns/docbook">
    Used together with <function>imagesetinterpolation</function>, available as of PHP 5.5.0.
</simpara>'>

<!ENTITY gd.deprecated.gd-formats '<warning xmlns="http://docbook.org/ns/docbook"><simpara>The GD
and GD2 image formats are proprietary image formats of libgd. They have to be regarded
<emphasis>obsolete</emphasis>, and should only be used for development and testing
purposes.</simpara></warning>'>

<!ENTITY gd.changelog.image-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>image</parameter> expects a <classname>GdImage</classname>
  instance now; previously, a valid <literal>gd</literal> <type>resource</type> was expected.
 </entry>
</row>'>

<!-- CSV -->
<!ENTITY warning.csv.escape-parameter '<warning xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"><simpara>
 When <parameter>escape</parameter> is set to anything other than an empty string
 (<literal>""</literal>) it can result in CSV that is not compliant with
 <link xlink:href="&url.rfc;4180">RFC 4180</link> or unable to survive a roundtrip
 through the PHP CSV functions. The default for <parameter>escape</parameter> is
 <literal>"\\"</literal> so it is recommended to set it to the empty string explicitly.
 The default value will change in a future version of PHP, no earlier than PHP 9.0.
</simpara></warning>'>

<!-- JSON notes -->

<!ENTITY json.implementation.superset '
 <note xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <simpara>
   PHP implements a superset of JSON as specified in the original
   <link xlink:href="&url.rfc;7159">RFC 7159</link>.
  </simpara>
 </note>
'>

<!-- cURL notes -->

<!ENTITY curl.ch.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>handle</parameter>
</term><listitem><simpara>A cURL handle returned by
<function>curl_init</function>.</simpara></listitem></varlistentry>'>

<!ENTITY curl.mh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>multi_handle</parameter>
</term><listitem><simpara>A cURL multi handle returned by
<function>curl_multi_init</function>.</simpara></listitem></varlistentry>'>

<!ENTITY curl.sh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>share_handle</parameter>
</term><listitem><simpara>A cURL share handle returned by
<function>curl_share_init</function>.</simpara></listitem></varlistentry>'>

<!ENTITY curl.changelog.handle-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>handle</parameter> expects a <classname>CurlHandle</classname>
  instance now; previously, a <type>resource</type> was expected.
 </entry>
</row>'>

<!ENTITY curl.changelog.multi-handle-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>multi_handle</parameter> expects a <classname>CurlMultiHandle</classname>
  instance now; previously, a <type>resource</type> was expected.
 </entry>
</row>'>

<!ENTITY curl.changelog.share-handle-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>share_handle</parameter> expects a <classname>CurlShareHandle</classname>
  instance now; previously, a <type>resource</type> was expected.
 </entry>
</row>'>

<!-- dba notes -->
<!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>.'>
<!ENTITY dba.changelog.dba-object '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.4.0</entry>
 <entry>
  The <parameter>dba</parameter> parameter expects a <classname>Dba\Connection</classname>
  instance now; previously, a valid <literal>dba</literal> &resource; was expected.
 </entry>
</row>'>

<!-- dbase notes -->

<!ENTITY dbase.type-conversion '<para xmlns="http://docbook.org/ns/docbook">
   Each field is converted to the appropriate PHP type, except:
   <itemizedlist>
    <listitem>
     <simpara>
      Dates are left as strings.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      DateTime values are converted to strings.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Integers outside the range
      <constant>PHP_INT_MIN</constant>..<constant>PHP_INT_MAX</constant> are
      returned as strings.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Before dbase 7.0.0, booleans (<literal>L</literal>) were converted to <literal>1</literal> or
      <literal>0</literal>.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>'>

<!-- enchant entities -->

<!ENTITY enchant.param.broker '<varlistentry xmlns="http://docbook.org/ns/docbook">
     <term><parameter>broker</parameter></term>
     <listitem>
      <simpara>
       An Enchant broker returned by <function>enchant_broker_init</function>.
      </simpara>
     </listitem>
    </varlistentry>'>

<!ENTITY enchant.param.dictionary '<varlistentry xmlns="http://docbook.org/ns/docbook">
     <term><parameter>dictionary</parameter></term>
     <listitem>
      <simpara>
       An Enchant dictionary returned by <function>enchant_broker_request_dict</function>
       or <function>enchant_broker_request_pwl_dict</function>.
      </simpara>
     </listitem>
    </varlistentry>'>

<!ENTITY enchant.changelog.broker-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>broker</parameter> expects an <classname>EnchantBroker</classname> instance now;
  previously, a &resource; was expected.
 </entry>
</row>'>

<!ENTITY enchant.changelog.dictionary-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>dictionary</parameter> expects an <classname>EnchantDictionary</classname> instance now;
  previously, a &resource; was expected.
 </entry>
</row>'>

<!-- IMAP notes -->

<!ENTITY imap.changelog.imap-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.1.0</entry>
 <entry>
  The <parameter>imap</parameter> parameter expects an <classname>IMAP\Connection</classname>
  instance now; previously, a valid <literal>imap</literal> &resource; was expected.
 </entry>
</row>'>

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

<!-- Deprecated -->

<!ENTITY imap.pattern '<simpara xmlns="http://docbook.org/ns/docbook">Specifies where in the mailbox hierarchy
to start searching.</simpara><simpara xmlns="http://docbook.org/ns/docbook">There are two special characters you can
pass as part of the <parameter>pattern</parameter>:
&apos;<literal>*</literal>&apos; and &apos;<literal>&#37;</literal>&apos;.
&apos;<literal>*</literal>&apos; means to return all mailboxes. If you pass
<parameter>pattern</parameter> as &apos;<literal>*</literal>&apos;, you will
get a list of the entire mailbox hierarchy.
&apos;<literal>&#37;</literal>&apos;
means to return the current level only.
&apos;<literal>&#37;</literal>&apos; as the <parameter>pattern</parameter>
parameter will return only the top level
mailboxes; &apos;<literal>~/mail/&#37;</literal>&apos; on <literal>UW_IMAPD</literal> will return every mailbox in the <filename>~/mail</filename> directory, but none in subfolders of that directory.</simpara>'>

<!ENTITY imap.mailboxname.insecure '<warning xmlns="http://docbook.org/ns/docbook"><simpara>
Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unless
<link linkend="ini.imap.enable-insecure-rsh">imap.enable_insecure_rsh</link> is disabled.
</simpara></warning>'>

<!-- intl notes -->

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

<!ENTITY intl.error.intl-calendar '<simpara 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>.</simpara>'>

<!ENTITY intl.codepoint.parameter '<simpara 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>)</simpara>'>

<!ENTITY intl.codepoint.return '<simpara 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.</simpara>'>

<!ENTITY intl.codepoint.example 'Testing different code points'>

<!ENTITY intl.locale-len.return '<simpara xmlns="http://docbook.org/ns/docbook">Returns &null; when the length of <parameter>locale</parameter> exceeds <constant>INTL_MAX_LOCALE_LEN</constant>.</simpara>'>

<!ENTITY intl.property.parameter '<simpara xmlns="http://docbook.org/ns/docbook">The Unicode property to lookup (see the <literal>IntlChar::PROPERTY_*</literal> constants).</simpara>'>

<!ENTITY intl.property.example 'Testing different properties'>

<!ENTITY intl.param.grapheme.locale '<simpara>Locale to use.</simpara>'>

<!ENTITY intl.changelog.grapheme.locale '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.5.0</entry>
 <entry>
  The optional parameter <parameter>locale</parameter> has been added.
 </entry>
</row>'>

<!-- LDAP notes -->

<!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>.'>

<!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>.'>

<!ENTITY ldap.parameter.entry 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\ResultEntry</classname> instance.'>

<!ENTITY ldap.warn.control-paged '<warning xmlns="http://docbook.org/ns/docbook">
 <simpara>
  This function has been <emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.
  Instead the <parameter>controls</parameter> parameter of <function>ldap_search</function> should be used.
  See also <link linkend="ldap.controls">LDAP Controls</link> for details.
 </simpara>
</warning>'>

<!ENTITY ldap.changelog.controls-nullable '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>controls</parameter> is nullable now; previously, it defaulted to <literal>[]</literal>.
 </entry>
</row>'>

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

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

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

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

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

<!ENTITY ldap.return-result 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance,&return.falseforfailure;.'>
<!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;.'>

<!ENTITY ldap.return-result-array-info '<simpara 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
<classname>LDAP\Connection</classname> instances, rather than a single one.
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.
These arrays must be of the same size as the <classname>LDAP\Connection</classname> instances array,
since the first entries of the arrays are used for one search, the second entries are used for another, and so on.
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;.</simpara>'>

<!-- mbstring notes -->

<!ENTITY note.mbstring.encoding.internal '<note xmlns="http://docbook.org/ns/docbook"><simpara>The internal encoding or the
character encoding specified by <function>mb_regex_encoding</function>
will be used as the character encoding for this function.</simpara></note>'>

<!ENTITY note.mbstring.encoding.current '<note xmlns="http://docbook.org/ns/docbook"><simpara>The
character encoding specified by <function>mb_regex_encoding</function>
will be used as the character encoding for this function by default.</simpara></note>'>

<!ENTITY mbstring.encoding.parameter '<simpara xmlns="http://docbook.org/ns/docbook">The <parameter>encoding</parameter>
parameter is the character encoding. If it is omitted or &null;, the internal character
encoding value will be used.</simpara>'>

<!ENTITY mbstring.warning.e-modifier '<warning xmlns="http://docbook.org/ns/docbook"><simpara>Never use the <literal>e</literal> modifier when working on untrusted input. No automatic escaping will happen (as known from <function>preg_replace</function>). Not taking care of this will most likely create remote code execution vulnerabilities in your application.</simpara></warning>'>

<!ENTITY mbstring.changelog.encoding-nullable '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>encoding</parameter> is nullable now.
 </entry>
</row>'>

<!ENTITY mbstring.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>needle</parameter> now accepts an empty string.
 </entry>
</row>'>

<!ENTITY mbstring.errors.encoding-invalid '<para xmlns="http://docbook.org/ns/docbook">
 As of PHP 8.0.0, a <exceptionname>ValueError</exceptionname> is thrown if
 <parameter>encoding</parameter> is an invalid encoding.
 Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was emitted instead.
</para>'>

<!ENTITY mbstring.changelog.encoding-invalid '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  Now throws a <exceptionname>ValueError</exceptionname> if
  <parameter>encoding</parameter> is an invalid encoding.
  Previously, an <constant>E_WARNING</constant> was emitted
  and &false; was returned.
 </entry>
</row>'>

<!-- mcrypt notes -->

<!ENTITY mcrypt.parameter.cipher '<simpara xmlns="http://docbook.org/ns/docbook">One of the <constant>MCRYPT_ciphername</constant> constants, or the name of the algorithm as string.</simpara>'>

<!ENTITY mcrypt.parameter.iv.strict '<simpara xmlns="http://docbook.org/ns/docbook">Used for the initialization in CBC, CFB, OFB modes, and in some algorithms in STREAM mode. If the provided IV size is not supported by the chaining mode or no IV was provided, but the chaining mode requires one, the function will emit a warning and return &false;.</simpara>'>

<!ENTITY mcrypt.parameter.mode '<simpara xmlns="http://docbook.org/ns/docbook">One of the <constant>MCRYPT_MODE_modename</constant> constants, or one of the following strings: "ecb", "cbc", "cfb", "ofb", "nofb" or "stream".</simpara>'>

<!-- memcached notes -->

<!ENTITY memcached.note.delete-time '<note xmlns="http://docbook.org/ns/docbook"><simpara>
       As of memcached 1.3.0 (released 2009) this feature is no longer
       supported. Passing a non-zero <parameter>time</parameter> will cause
       the deletion to fail. <methodname>Memcached::getResultCode</methodname>
       will return <constant>MEMCACHED_INVALID_ARGUMENTS</constant>.
      </simpara></note>
'>

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

<!ENTITY memcached.parameter.server_key 'The key identifying the server to store the value on or retrieve it from. Instead of hashing on the actual key for the item, we hash on the server key when deciding which memcached server to talk to. This allows related items to be grouped together on a single server for efficiency with multi operations.'>

<!ENTITY memcached.parameter.items 'An array of key/value pairs to store on the server.'>

<!ENTITY memcached.parameter.key 'The key under which to store the value.'>

<!ENTITY memcached.parameter.value 'The value to store.'>

<!ENTITY memcached.result.getresultcode 'Use <methodname xmlns="http://docbook.org/ns/docbook">Memcached::getResultCode</methodname> if necessary.'>

<!ENTITY memcached.result.delete-multi '<simpara xmlns="http://docbook.org/ns/docbook">
   Returns an array indexed by <parameter>keys</parameter>. Each element
   is &true; if the corresponding key was deleted, or one of the
   <constant>Memcached::RES_<replaceable>*</replaceable></constant> constants if the corresponding deletion
   failed.
   </simpara>
  <simpara xmlns="http://docbook.org/ns/docbook">
   The <methodname>Memcached::getResultCode</methodname> will return
   the result code for the last executed delete operation, that is, the delete
   operation for the last element of <parameter>keys</parameter>.
  </simpara>
'>

<!-- password notes -->

<!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.'>

<!ENTITY password.parameter.hash 'A hash created by <function xmlns="http://docbook.org/ns/docbook">password_hash</function>.'>

<!ENTITY password.parameter.options 'An associative array containing options. See the <link xmlns="http://docbook.org/ns/docbook" linkend="password.constants">password algorithm constants</link> for documentation on the supported options for each algorithm.'>

<!ENTITY password.parameter.password 'The user&apos;s password.'>

<!-- pspell notes -->

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

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

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

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

<!-- RNP -->

<!ENTITY rnp.parameter.ffi-description 'The FFI object returned by <function xmlns="http://docbook.org/ns/docbook">rnp_ffi_create</function>.'>

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

<!ENTITY rnp.parameter.loadsave-flags 'See <constant xmlns="http://docbook.org/ns/docbook">RNP_LOAD_SAVE_<replaceable>*</replaceable></constant> flags description.'>

<!-- socket entities -->

<!ENTITY sockets.changelog.socket-param '<row xmlns="http://docbook.org/ns/docbook">
  <entry>8.0.0</entry>
  <entry>
   <parameter>socket</parameter> is a <classname>Socket</classname> instance now;
   previously, it was a <type>resource</type>.
  </entry>
 </row>'>

<!ENTITY sockets.changelog.address-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>address</parameter> is an <classname>AddressInfo</classname> instance now;
  previously, it was a <type>resource</type>.
 </entry>
</row>'>

<!-- geaman notes -->

<!ENTITY gearman.parameter.host 'The job server host name.'>

<!ENTITY gearman.parameter.port 'The job server port.'>

<!ENTITY gearman.parameter.functionname 'A registered function the worker is to execute'>

<!ENTITY gearman.parameter.workload 'Serialized data to be processed'>

<!ENTITY gearman.parameter.context 'Application context to associate with a task'>

<!ENTITY gearman.parameter.unique 'A unique ID used to identify a particular task'>

<!ENTITY gearman.parameter.jobhandle 'The job handle assigned by the Gearman server'>

<!ENTITY gearman.parameter.callback '<varlistentry xmlns="http://docbook.org/ns/docbook">
 <term><parameter>callback</parameter></term>
 <listitem>
  <simpara>
   A function or method to call.
   It should return a valid <link linkend="gearman.constants">Gearman return value</link>.
  </simpara>
  <simpara>
   If no return statement is present, it defaults to <constant>GEARMAN_SUCCESS</constant>.
  </simpara>
  <methodsynopsis>
   <type>int</type><methodname><replaceable>callback</replaceable></methodname>
   <methodparam><type>GearmanTask</type><parameter>task</parameter></methodparam>
   <methodparam><type>mixed</type><parameter>context</parameter></methodparam>
  </methodsynopsis>
  <variablelist>
   <varlistentry>
    <term><parameter>task</parameter></term>
    <listitem>
     <simpara>
      The task this callback is called for.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>context</parameter></term>
    <listitem>
     <simpara>
      Whatever has been passed to <methodname>GearmanClient::addTask</methodname> (or equivalent method) as <parameter>context</parameter>.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </listitem>
</varlistentry>'>

<!ENTITY gearman.note.callback '<note xmlns="http://docbook.org/ns/docbook">
 <simpara>
  The callback will only be triggered for tasks that are added (e.g. by calling <methodname>GearmanClient::addTask</methodname>)
  after calling this method.
 </simpara>
</note>'>

<!-- Date and time entities -->
<!ENTITY date.timezone.intro.title '<title xmlns="http://docbook.org/ns/docbook">List of Supported Timezones</title>'>

<!ENTITY date.timezone.intro "<para xmlns='http://docbook.org/ns/docbook'>
Here you'll find the complete list of timezones supported by PHP, which are
meant to be used with e.g. <function>date_default_timezone_set</function>.
<caution><simpara>The behavior of timezones not listed here is undefined.</simpara></caution>
</para><note xmlns='http://docbook.org/ns/docbook'><simpara>The latest version of the timezone database can be
installed via PECL's <link xlink:href='&url.pecl.package.get;timezonedb' xmlns:xlink='http://www.w3.org/1999/xlink'>timezonedb</link>.
</simpara></note>">

<!ENTITY date.timezone.bc '<simpara xmlns="http://docbook.org/ns/docbook">Please do not use any of the timezones
listed here (besides UTC), they only exist for backward compatible reasons, and may expose erroneous behavior.
Furthermore, these timezones may be removed from the IANA timezone database at any time.
</simpara>'>

<!ENTITY date.timezone.posix-signs '<simpara xmlns="http://docbook.org/ns/docbook">
 If you disregard the above warning, please also note that the IANA
 timezone database that provides PHP&apos;s timezone support uses POSIX style
 signs, which results in the <literal>Etc/GMT+n</literal> and
 <literal>Etc/GMT-n</literal> time zones being reversed from common usage.
</simpara>
<simpara xmlns="http://docbook.org/ns/docbook">
 For example, the time zone 8 hours ahead of GMT that is used in China and
 Western Australia (among other places) is actually
 <literal>Etc/GMT-8</literal> in this database, not
 <literal>Etc/GMT+8</literal> as you would normally expect.
</simpara>
<simpara xmlns="http://docbook.org/ns/docbook">
 Once again, it is strongly recommended that you use the correct time zone
 for your location, such as <literal>Asia/Shanghai</literal> or
 <literal>Australia/Perth</literal> for the above examples.
</simpara>'>

<!ENTITY date.timezone.errors.description '<simpara xmlns="http://docbook.org/ns/docbook">
Every call to a date/time function will generate a <constant>E_WARNING</constant>
if the time zone is not valid. See also <function>date_default_timezone_set</function></simpara>'>

<!ENTITY date.timestamp.description '
<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>timestamp</parameter></term><listitem><simpara>
The optional <parameter>timestamp</parameter> parameter is an
<type>int</type> Unix timestamp that defaults to the current
local time if <parameter>timestamp</parameter> is omitted or &null;. In other
words, it defaults to the value of <function>time</function>.
</simpara></listitem></varlistentry>'>

<!ENTITY date.datetime.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>object</parameter></term>
<listitem><simpara>Procedural style only: A <classname>DateTime</classname> object
returned by <function>date_create</function></simpara></listitem></varlistentry>'>

<!ENTITY date.datetime.description.modified '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>object</parameter></term>
<listitem><simpara>Procedural style only: A <classname>DateTime</classname> object
returned by <function>date_create</function>.
The function modifies this object.</simpara></listitem></varlistentry>'>

<!ENTITY date.datetimezone.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
<parameter>object</parameter></term><listitem><simpara>Procedural style only: A <classname>DateTimeZone</classname> object
returned by <function>timezone_open</function></simpara></listitem></varlistentry>'>

<!ENTITY date.datetime.return.modifiedobject 'Returns the modified <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining.'>
<!ENTITY date.datetimeimmutable.return.modifiedobject 'Returns a new <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object with the modified data.'>

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

<!ENTITY date.timezone.africa 'Africa'>
<!ENTITY date.timezone.america 'America'>
<!ENTITY date.timezone.antarctica 'Antarctica'>
<!ENTITY date.timezone.arctic 'Arctic'>
<!ENTITY date.timezone.asia 'Asia'>
<!ENTITY date.timezone.atlantic 'Atlantic'>
<!ENTITY date.timezone.australia 'Australia'>
<!ENTITY date.timezone.europe 'Europe'>
<!ENTITY date.timezone.indian 'Indian'>
<!ENTITY date.timezone.pacific 'Pacific'>
<!ENTITY date.timezone.others 'Others'>

<!ENTITY date.formats 'Valid formats are explained in <link xmlns="http://docbook.org/ns/docbook" linkend="datetime.formats">Date and Time Formats</link>.'>
<!ENTITY date.formats.parameter 'A date/time string. &date.formats;'>

<!-- Dom Notes -->
<!ENTITY dom.node.inserted 'This node will not show up in the document unless
it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNode::appendChild</function>.'>

<!ENTITY dom.malformederror '<simpara xmlns="http://docbook.org/ns/docbook">While malformed HTML should load successfully, this function may generate <constant>E_WARNING</constant> errors when it encounters bad markup. <link linkend="function.libxml-use-internal-errors">libxml&apos;s error handling functions</link> may be used to handle these errors.</simpara>'>
<!ENTITY dom.note.utf8 '<note xmlns="http://docbook.org/ns/docbook"><simpara>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.</simpara></note>'>
<!ENTITY dom.note.modern.utf8 '<note xmlns="http://docbook.org/ns/docbook">
 <simpara>
  The DOM extension uses UTF-8 encoding when working with methods or properties.
  The parser methods auto-detect the encoding or allow the caller to specify an encoding.
 </simpara>
</note>'>
<!ENTITY dom.note.json '<note xmlns="http://docbook.org/ns/docbook"><simpara>When using <function>json_encode</function> on a <classname>DOMDocument</classname> object the result will be that of encoding an empty object.</simpara></note>'>
<!ENTITY dom.domdocument.html5 '<warning xmlns="http://docbook.org/ns/docbook">
 <simpara>
  Use <classname>Dom\HTMLDocument</classname> to parse and process modern HTML
  instead of <classname>DOMDocument</classname>.
 </simpara>
 <simpara>
  This function parses the input using an HTML 4 parser. The parsing rules
  of HTML 5, which is what modern web browsers use, are different. Depending
  on the input this might result in a different DOM structure. Therefore
  this function cannot be safely used for sanitizing HTML.
 </simpara>
 <simpara>
  The behavior when parsing HTML can depend on the version of
  <literal>libxml</literal> that is being used, particularly with regards to
  edge conditions and error handling.
  For parsing that conforms to the HTML5 specification,
  use <methodname>Dom\HTMLDocument::createFromString</methodname> or
  <methodname>Dom\HTMLDocument::createFromFile</methodname>, added in PHP 8.4.
 </simpara>
 <simpara>
  As an example, some HTML elements will implicitly close a parent element
  when encountered. The rules for automatically closing parent elements
  differ between HTML 4 and HTML 5 and thus the resulting DOM structure that
  <classname>DOMDocument</classname> sees might be different from the DOM
  structure a web browser sees, possibly allowing an attacker to break the
  resulting HTML.
 </simpara>
</warning>'>
<!ENTITY dom.tokenlist.errors '<itemizedlist xmlns="http://docbook.org/ns/docbook">
 <listitem>
  <simpara>
   Throws a <exceptionname>ValueError</exceptionname> if
   a token contains any null bytes.
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   Throws a <exceptionname>Dom\DOMException</exceptionname> with code
   <constant>Dom\SYNTAX_ERR</constant> if a token is the empty string.
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   Throws a <exceptionname>Dom\DOMException</exceptionname> with code
   <constant>Dom\INVALID_CHARACTER_ERR</constant> if a token contains any
   ASCII whitespace.
  </simpara>
 </listitem>
</itemizedlist>'>

<!-- Dom Examples -->
<!ENTITY dom.book.example '<simpara xmlns="http://docbook.org/ns/docbook">The following examples use <filename>book.xml</filename> which contains the following:</simpara>
<programlisting role="xml" xmlns="http://docbook.org/ns/docbook">
<![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE books [
  <!ELEMENT books   (book+)>
  <!ELEMENT book    (title, author+, xhtml:blurb?)>
  <!ELEMENT title   (#PCDATA)>
  <!ELEMENT blurb   (#PCDATA)>
  <!ELEMENT author  (#PCDATA)>
  <!ATTLIST books   xmlns        CDATA  #IMPLIED>
  <!ATTLIST books   xmlns:xhtml  CDATA  #IMPLIED>
  <!ATTLIST book    id           ID     #IMPLIED>
  <!ATTLIST author  email        CDATA  #IMPLIED>
]>
<?xml-stylesheet type="text/xsl" href="style.xsl"?>
<books xmlns="http://books.php/" xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <book id="php-basics">
    <title>PHP Basics</title>
    <author email="jim.smith@basics.php">Jim Smith</author>
    <author email="jane.smith@basics.php">Jane Smith</author>
    <xhtml:blurb><![CDATA[
<p><em>PHP Basics</em> provides an introduction to PHP.</p>
]]]]><![CDATA[></xhtml:blurb>
  </book>
  <book id="php-advanced">
    <title>PHP Advanced Programming</title>
    <author email="jon.doe@advanced.php">Jon Doe</author>
  </book>
</books>
]]></programlisting>'>

<!-- Dom entities -->
<!ENTITY dom.parameter.options '<simpara xmlns="http://docbook.org/ns/docbook">
  <link linkend="language.operators.bitwise">Bitwise <literal>OR</literal></link>
  of the <link linkend="libxml.constants">libxml option constants</link>.
</simpara>'>

<!ENTITY dom.parameter.compliant.options '&dom.parameter.options;
 <simpara xmlns="http://docbook.org/ns/docbook">
  It is also possible to pass <constant>Dom\HTML_NO_DEFAULT_NS</constant>
  to disable the use of the HTML namespace and the template element.
  This should only be used if the implications are properly understood.
</simpara>'>

<!ENTITY dom.parameter.compliant.encoding '<simpara xmlns="http://docbook.org/ns/docbook">
 The encoding that the document was created in.
 If not provided, it will attempt to determine the encoding that is most likely used.
</simpara>'>

<!ENTITY dom.parser.compliant.note.whitespace '<refsect1 role="notes" xmlns="http://docbook.org/ns/docbook">
 &reftitle.notes;
 <note>
  <simpara>
   Whitespace in the <literal>html</literal> and <literal>head</literal> tags
   is not considered significant and may lose formatting.
  </simpara>
 </note>
</refsect1>'>

<!ENTITY dom.parameters.register_node_ns '<varlistentry xmlns="http://docbook.org/ns/docbook">
 <term><parameter>registerNodeNS</parameter></term>
 <listitem>
  <simpara>
   Whether to automatically register the in-scope namespace prefixes of the context node to the <classname>DOMXPath</classname> object.
   This can be used to avoid needing to call <methodname>DOMXPath::registerNamespace</methodname> manually for each in-scope namespaces.
   When a namespace prefix conflict exists, only the nearest descendant namespace prefix is registered.
  </simpara>
 </listitem>
</varlistentry>'>

<!ENTITY dom.parameters.serialize.options '<simpara xmlns="http://docbook.org/ns/docbook">
 Additional Options.
 The <constant>LIBXML_NOEMPTYTAG</constant>
 and <constant>LIBXML_NOXMLDECL</constant> options are supported.
 Prior to PHP 8.3.0, only the <constant>LIBXML_NOEMPTYTAG</constant>
 option is supported.
</simpara>'>

<!ENTITY dom.errors.hierarchy.parent '<varlistentry xmlns="http://docbook.org/ns/docbook">
 <term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
  <listitem>
  <simpara>
    Raised if the parent is of a type that does not allow children of the
    type of one of the passed <parameter>nodes</parameter>, or if the node to
    put in is one of this node&#39;s ancestors or this node itself.
  </simpara>
 </listitem>
</varlistentry>'>

<!ENTITY dom.errors.hierarchy.self '<varlistentry xmlns="http://docbook.org/ns/docbook">
 <term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
  <listitem>
  <simpara>
    Raised if this node is of a type that does not allow children of the
    type of one of the passed <parameter>nodes</parameter>, or if the node to
    put in is one of this node&#39;s ancestors or this node itself.
  </simpara>
 </listitem>
</varlistentry>'>

<!ENTITY dom.errors.wrong_document '<varlistentry xmlns="http://docbook.org/ns/docbook">
 <term><constant>DOM_WRONG_DOCUMENT_ERR</constant></term>
  <listitem>
  <simpara>
    Raised if one of the passed <parameter>nodes</parameter> was created from a different
    document than the one that created this node.
  </simpara>
 </listitem>
</varlistentry>'>

<!ENTITY dom.errors.compliant.wrong_document '<listitem xmlns="http://docbook.org/ns/docbook">
 <simpara>
  Throws a <exceptionname>Dom\DOMException</exceptionname> with code
  <constant>Dom\WRONG_DOCUMENT_ERR</constant> if <parameter>node</parameter>
  is from another document.
 </simpara>
</listitem>'>

<!ENTITY dom.errors.compliant.common '<listitem xmlns="http://docbook.org/ns/docbook">
 <simpara>
  Throws a <exceptionname>ValueError</exceptionname> if
  <parameter>options</parameter> contains an invalid option.
 </simpara>
</listitem>
<listitem>
 <simpara>
  Throws a <exceptionname>ValueError</exceptionname> if
  <parameter>overrideEncoding</parameter> is an unknown encoding.
 </simpara>
</listitem>'>

<!ENTITY dom.changelog.previous_hierarchy_exception 'Previously this threw a
 <classname xmlns="http://docbook.org/ns/docbook">DOMException</classname> with code
 <constant xmlns="http://docbook.org/ns/docbook">DOM_HIERARCHY_REQUEST_ERR</constant>.'>

<!ENTITY dom.c14n.xpath_array '<listitem xmlns="http://docbook.org/ns/docbook">
  <para>
   An array of XPaths to filter the nodes by.
   Each entry in this array is an associative array with:
   <itemizedlist>
    <listitem>
     <simpara>
      A required <literal>query</literal> key containing the XPath expression as a string.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      An optional <literal>namespaces</literal> key containing an array that maps namespace prefixes (keys) to namespace URIs (values).
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
 </listitem>'>

<!-- FileSystem entities -->
<!ENTITY fs.emits.warning.on.failure '<simpara xmlns="http://docbook.org/ns/docbook">
Upon failure, an <constant>E_WARNING</constant> is emitted.
</simpara>'>

<!ENTITY fs.validfp.all '<simpara xmlns="http://docbook.org/ns/docbook">The file pointer must be valid, and must point to
a file successfully opened by <function>fopen</function> or
<function>fsockopen</function> (and not yet closed by
<function>fclose</function>).</simpara>'>

<!ENTITY fs.file.pointer '<simpara xmlns="http://docbook.org/ns/docbook">A file system pointer <type>resource</type>
that is typically created using <function>fopen</function>.</simpara>'>

<!ENTITY fs.file.32bit '<note xmlns="http://docbook.org/ns/docbook"><simpara>
    Because PHP&apos;s integer type is signed and many platforms use 32bit integers,
    some filesystem functions may return unexpected results for files which
    are larger than 2GB.
   </simpara></note>'>

<!ENTITY ini.scanner.typed '<simpara xmlns="http://docbook.org/ns/docbook">
    As of PHP 5.6.1 can also be specified as <constant>INI_SCANNER_TYPED</constant>.
    In this mode boolean, null and integer types are preserved when possible.
    String values <literal>"true"</literal>, <literal>"on"</literal> and <literal>"yes"</literal>
    are converted to &true;. <literal>"false"</literal>, <literal>"off"</literal>, <literal>"no"</literal>
    and <literal>"none"</literal> are considered &false;. <literal>"null"</literal> is converted to &null;
    in typed mode. Also, all numeric strings are converted to integer type if it is possible.
   </simpara>'>

<!-- GNUPG -->
<!ENTITY gnupg.identifier '<simpara xmlns="http://docbook.org/ns/docbook">The gnupg identifier, from a call to
<function>gnupg_init</function> or <classname>gnupg</classname>.</simpara>'>

<!ENTITY gnupg.fingerprint '<simpara xmlns="http://docbook.org/ns/docbook">The fingerprint key.</simpara>'>

<!-- ODBC -->
<!ENTITY odbc.connection.id '<simpara xmlns="http://docbook.org/ns/docbook">The ODBC connection object,
see <function>odbc_connect</function> for details.</simpara>'>

<!ENTITY odbc.result.object 'The ODBC result object'>

<!ENTITY odbc.result.object-return 'Returns an ODBC result object'>

<!ENTITY odbc.result.object-return-falseforfailure '&odbc.result.object-return;&return.falseforfailure;.'>

<!ENTITY odbc.parameter.catalog 'The catalog (&apos;qualifier&apos; in ODBC 2 parlance).'>

<!ENTITY odbc.parameter.schema 'The schema (&apos;owner&apos; in ODBC 2 parlance).'>

<!ENTITY odbc.parameter.search 'This parameter accepts the following search patterns:
<literal xmlns="http://docbook.org/ns/docbook">&#x25;</literal> to match zero or more characters,
and <literal xmlns="http://docbook.org/ns/docbook">_</literal> to match a single character.'>

<!ENTITY odbc.result.driver-specific 'Drivers can report additional columns.'>

<!ENTITY odbc.changelog.connection-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.4.0</entry>
 <entry>
  <parameter>odbc</parameter> expects an <classname>Odbc\Connection</classname>
  instance now; previously, a <type>resource</type> was expected.
 </entry>
</row>'>

<!ENTITY odbc.changelog.connection-return '<row xmlns="http://docbook.org/ns/docbook">
  <entry>8.4.0</entry>
  <entry>
   This function returns a <classname>Odbc\Connection</classname> instance now;
   previously, a <type>resource</type> was returned.
  </entry>
 </row>'>

<!ENTITY odbc.changelog.credential-params '<row xmlns="http://docbook.org/ns/docbook">
  <entry>8.4.0</entry>
  <entry>
   <parameter>user</parameter> and <parameter>password</parameter> are now nullable,
   they are now also optional and default to &null;.
  </entry>
 </row>
 <row xmlns="http://docbook.org/ns/docbook">
  <entry>8.4.0</entry>
  <entry>
   Previously, using an empty string for <parameter>password</parameter> would not include
   <literal>pwd</literal> in the generated connection string for <parameter>dsn</parameter>.
   It is now generated to include a <literal>pwd</literal> which has an empty string as its value.
   To restore the previous behaviour <parameter>password</parameter> can now be set to &null;.
  </entry>
 </row>
 <row xmlns="http://docbook.org/ns/docbook">
  <entry>8.4.0</entry>
  <entry>
   Previously, if <parameter>dsn</parameter> contained <literal>uid</literal> or <literal>pwd</literal>
   both <parameter>user</parameter> and <parameter>password</parameter> parameters were ignored.
   Now <parameter>user</parameter> is only ignored if <parameter>dsn</parameter> contains
   <literal>uid</literal>, and <parameter>password</parameter>  is only ignored if
   <parameter>dsn</parameter> contains <literal>pwd</literal>.
  </entry>
 </row>'>

<!ENTITY odbc.changelog.result-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.4.0</entry>
 <entry>
  <parameter>statement</parameter> expects an <classname>Odbc\Result</classname>
  instance now; previously, a <type>resource</type> was expected.
 </entry>
</row>'>

<!ENTITY odbc.changelog.result-return '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.4.0</entry>
 <entry>
  This function returns an <classname>Odbc\Result</classname>
  instance now; previously, a <type>resource</type> was returned.
 </entry>
</row>'>

<!-- OAUTH -->
<!ENTITY oauth.callback.error 'Emits an <constant xmlns="http://docbook.org/ns/docbook">E_ERROR</constant> level
error if the callback function cannot be called, or was not specified.'>

<!ENTITY oauth.changelog.error.null 'Previously returned &null; on failure, instead of &false;.'>

<!-- Oracle -->
<!ENTITY oci.db "<simpara xmlns='http://docbook.org/ns/docbook' xmlns:xlink='http://www.w3.org/1999/xlink'>Contains
the <literal>Oracle instance</literal> to connect to. It can be
an <link xlink:href='&url.oracle.oic.connect;'>Easy Connect
string</link>, or a Connect Name from
the <filename>tnsnames.ora</filename> file, or the name of a local
Oracle instance.
</simpara>
<simpara xmlns='http://docbook.org/ns/docbook'>If not specified or &null;, PHP uses
environment variables such as <constant>TWO_TASK</constant> (on Linux)
or <constant>LOCAL</constant> (on Windows)
and <constant>ORACLE_SID</constant> to determine the
<literal>Oracle instance</literal> to connect to.
</simpara>
<simpara xmlns='http://docbook.org/ns/docbook'>
To use the Easy Connect naming method, PHP must be linked with Oracle
10<emphasis>g</emphasis> or greater Client libraries. The Easy Connect string for Oracle
10<emphasis>g</emphasis> is of the form:
<emphasis>[//]host_name[:port][/service_name]</emphasis>. From Oracle
11<emphasis>g</emphasis>, the syntax is:
<emphasis>[//]host_name[:port][/service_name][:server_type][/instance_name]</emphasis>.
Further options were introduced with Oracle 19c, including timeout and keep-alive
settings.  Refer to Oracle documentation.  Service names can be found by running
the Oracle utility <literal>lsnrctl status</literal> on the database server
machine.
</simpara>
<simpara xmlns='http://docbook.org/ns/docbook'>
The <filename>tnsnames.ora</filename> file can be in the Oracle Net search path,
which
includes <filename>/your/path/to/instantclient/network/admin</filename>, <filename>$ORACLE_HOME/network/admin</filename>
and <filename>/etc</filename>.  Alternatively set <literal>TNS_ADMIN</literal>
so that <filename>$TNS_ADMIN/tnsnames.ora</filename> is read.  Make sure the web
daemon has read access to the file.
</simpara>">

<!ENTITY oci.charset "<simpara xmlns='http://docbook.org/ns/docbook'>Determines
the character set used by the Oracle Client libraries.  The character
set does not need to match the character set used by the database.  If
it doesn't match, Oracle will do its best to convert data to and from
the database character set.  Depending on the character sets this may
not give usable results.  Conversion also adds some time overhead.
</simpara>
<simpara xmlns='http://docbook.org/ns/docbook'>If not specified, the
Oracle Client libraries determine a character set from
the <constant>NLS_LANG</constant> environment variable.
</simpara>
<simpara xmlns='http://docbook.org/ns/docbook'>Passing this parameter can
reduce the time taken to connect.
</simpara>">

<!ENTITY oci.sessionmode '<simpara xmlns="http://docbook.org/ns/docbook">This
parameter is available since version PHP 5 (PECL OCI8 1.1) and accepts the
following values: <constant>OCI_DEFAULT</constant>,
<constant>OCI_SYSOPER</constant> and <constant>OCI_SYSDBA</constant>.
If either <constant>OCI_SYSOPER</constant> or
<constant>OCI_SYSDBA</constant> were specified, this function will try
to establish privileged connection using external credentials.
Privileged connections are disabled by default. To enable them you
need to set <link linkend="ini.oci8.privileged-connect">oci8.privileged_connect</link>
to <literal>On</literal>.
</simpara>
<simpara xmlns="http://docbook.org/ns/docbook">
PHP 5.3 (PECL OCI8 1.3.4) introduced the
<constant>OCI_CRED_EXT</constant> mode value. This tells Oracle to use
External or OS authentication, which must be configured in the
database.  The <constant>OCI_CRED_EXT</constant> flag can only be used
with username of &quot;/&quot; and a empty password.
<link linkend="ini.oci8.privileged-connect">oci8.privileged_connect</link>
may be <literal>On</literal> or <literal>Off</literal>.
</simpara>
<simpara xmlns="http://docbook.org/ns/docbook">
<constant>OCI_CRED_EXT</constant> may be combined with the
<constant>OCI_SYSOPER</constant> or
<constant>OCI_SYSDBA</constant> modes.
</simpara>
<simpara xmlns="http://docbook.org/ns/docbook">
<constant>OCI_CRED_EXT</constant> is not supported on Windows for
security reasons.
</simpara>'>

<!ENTITY oci.datatypes '<simpara xmlns="http://docbook.org/ns/docbook">For details on the data type mapping performed by
the OCI8 extension, see the <link linkend="oci8.datatypes">datatypes
supported by the driver</link></simpara>'>

<!ENTITY oci.parameter.connection '<simpara xmlns="http://docbook.org/ns/docbook">An Oracle connection identifier,
returned by <function>oci_connect</function>, <function>oci_pconnect</function>,
or <function>oci_new_connect</function>.</simpara>'>

<!ENTITY oci.availability.note.10g '<note xmlns="http://docbook.org/ns/docbook"><title>Oracle version requirement</title>
<simpara>This function is available when PHP is linked with Oracle Database
libraries from version 10<emphasis>g</emphasis> onwards.</simpara></note>'>

<!ENTITY oci.clientinfo.tip '<tip xmlns="http://docbook.org/ns/docbook"><title>Performance</title><simpara>With older versions of
OCI8 or the Oracle Database, the client information can be set using the Oracle
<literal>DBMS_APPLICATION_INFO</literal> package. This is less efficient than
using <function>oci_set_client_info</function>.</simpara></tip>'>

<!ENTITY oci.roundtrip.caution '<caution xmlns="http://docbook.org/ns/docbook"><title>Round-trip Gotcha</title>
<simpara>Some but not all OCI8 functions cause round-trips.  Round-trips to the
database may not occur with queries when result caching is enabled.
</simpara></caution>'>

<!ENTITY oci.use.setprefetch '<simpara xmlns="http://docbook.org/ns/docbook">For
queries returning a large number of rows, performance can be
significantly improved by
increasing <link linkend="ini.oci8.default-prefetch">oci8.default_prefetch</link>
or using <function>oci_set_prefetch</function>.
</simpara>'>

<!ENTITY oci.arg.statement.id
"<simpara xmlns='http://docbook.org/ns/docbook'>A valid OCI8 statement
identifier created by <function>oci_parse</function> and executed
by <function>oci_execute</function>, or a <literal>REF
CURSOR</literal> statement identifier.</simpara>">

<!-- PCNTL Notes -->
<!ENTITY pcntl.parameter.status '<simpara xmlns="http://docbook.org/ns/docbook">The <parameter>status</parameter>
parameter is the status parameter supplied to a successful
call to <function>pcntl_waitpid</function>.</simpara>'>

<!-- PS Notes -->
<!ENTITY ps.note.visible '<simpara xmlns="http://docbook.org/ns/docbook">The note will not be visible if the document
is printed or viewed but it will show up if the document is converted to
pdf by either Acrobat Distiller™ or Ghostview.</simpara>'>

<!ENTITY note.open-basedir.func '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is affected by <link
linkend="ini.open-basedir">open_basedir</link>.</simpara></note>'>

<!ENTITY note.language-construct '<note xmlns="http://docbook.org/ns/docbook"><simpara>Because this is a
language construct and not a function, it cannot be called using
<link linkend="functions.variable-functions">variable functions</link>,
or <link linkend="functions.named-arguments">named arguments</link>.</simpara>
</note>'>

<!-- Common pieces in partintro-sections -->
<!ENTITY no.config '<simpara xmlns="http://docbook.org/ns/docbook">This extension has no configuration directives defined in &php.ini;.</simpara>'>
<!ENTITY no.requirement '<simpara xmlns="http://docbook.org/ns/docbook">No external libraries are needed to build this extension.</simpara>'>
<!ENTITY no.install '<simpara xmlns="http://docbook.org/ns/docbook">There is no installation needed to use these
functions; they are part of the PHP core.</simpara>'>

<!-- Used in every chapter that has directive descriptions -->
<!ENTITY ini.descriptions.title '<simpara xmlns="http://docbook.org/ns/docbook">Here&apos;s a short explanation of
the configuration directives.</simpara>'>

<!-- Used in reference/$extname/ini.xml -->
<!ENTITY extension.runtime '<simpara xmlns="http://docbook.org/ns/docbook">
The behaviour of these functions is affected by settings in &php.ini;.
</simpara>'>

<!ENTITY ini.php.constants 'For further details and definitions of the
INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>

<!-- Used in reference/$extname/constants.xml -->
<!ENTITY extension.constants '<simpara xmlns="http://docbook.org/ns/docbook">
The constants below are defined by this extension, and
will only be available when the extension has either
been compiled into PHP or dynamically loaded at runtime.
</simpara>'>

<!-- For STANDARD Constants used in reference/$extname/constants.xml -->
<!ENTITY extension.constants.core '<simpara xmlns="http://docbook.org/ns/docbook">
The constants below are always available as part of the PHP core.
</simpara>'>

<!-- PDO entities -->
<!ENTITY pdo.driver-constants '<simpara xmlns="http://docbook.org/ns/docbook">The constants below are defined by
this driver, and will only be available when the extension has been either
compiled into PHP or dynamically loaded at runtime. In addition, these
driver-specific constants should only be used if you are using this driver.
Using driver-specific attributes with another driver may result in
unexpected behaviour. <function>PDO::getAttribute</function> may be used to
obtain the <constant>PDO::ATTR_DRIVER_NAME</constant> attribute to check the
driver, if your code can run against multiple drivers.</simpara>'>

<!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>'>

<!-- PDO errors -->

<!ENTITY pdo.errors '<simpara xmlns="http://docbook.org/ns/docbook">
Emits an error with level <constant>E_WARNING</constant> if the attribute <constant>PDO::ATTR_ERRMODE</constant> is set
to <constant>PDO::ERRMODE_WARNING</constant>.
</simpara>
<simpara xmlns="http://docbook.org/ns/docbook">
Throws a <classname>PDOException</classname> if the attribute <constant>PDO::ATTR_ERRMODE</constant>
is set to <constant>PDO::ERRMODE_EXCEPTION</constant>.
</simpara>'>

<!-- PECL entities -->
<!ENTITY pecl.moved 'This &link.pecl; extension is not bundled with PHP.'>

<!ENTITY pecl.info 'Information for installing this PECL extension may be
found in the manual chapter titled <link xmlns="http://docbook.org/ns/docbook" linkend="install.pecl">Installation
of PECL extensions</link>. Additional information such as new releases,
downloads, source files, maintainer information, and a CHANGELOG, can be
located here: '>

<!ENTITY pecl.info.dead 'This extension is considered unmaintained and dead. However, the source code for
this extension is still available within <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym>
<acronym xmlns="http://docbook.org/ns/docbook">SVN</acronym> here: '>

<!ENTITY pecl.info.dead.git 'This extension is considered unmaintained and dead. However, the source code for
this extension is still available within <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym>
<acronym xmlns="http://docbook.org/ns/docbook">GIT</acronym> here: '>

<!ENTITY pecl.windows.download 'A <acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> for this
<acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension is currently unavailable. See also the
<link xmlns="http://docbook.org/ns/docbook" linkend="install.windows.building">building on Windows</link>
section.'>

<!ENTITY pecl.windows.download.avail 'Windows binaries (<acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> files)
for this <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension are available from the PECL website.'>

<!ENTITY pecl.moved-ver 'This extension has been moved to the &link.pecl;
repository and is no longer bundled with PHP as of PHP '>

<!ENTITY pecl.moving.to.pie '<warning xmlns="http://docbook.org/ns/docbook">
 <simpara>
  PECL is deprecated.
  PHP Installer for Extensions (<acronym>PIE</acronym>) replaces PECL and is recommended to install extensions.
  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>
 </simpara>
</warning>'>

<!ENTITY warn.pecl.unmaintained '<warning xmlns="http://docbook.org/ns/docbook">
 <simpara>This extension is <emphasis>unmaintained</emphasis>.</simpara>
</warning>'>

<!-- PGSQL entities -->

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

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

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

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

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

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

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

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

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

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

<!-- Common pieces for reference part END -->

<!ENTITY windows.builtin '<simpara xmlns="http://docbook.org/ns/docbook">The Windows version of PHP has built-in
support for this extension. You do not need to load any additional
extensions in order to use these functions.</simpara>'>

<!-- These are here as helpers for manual consistency and brievety-->

<!ENTITY sqlsafemode '<link xmlns="http://docbook.org/ns/docbook" linkend="ini.sql.safe-mode">SQL safe mode</link>'>

<!-- CTYPE Notes -->
<!ENTITY note.ctype.parameter.integer '<note xmlns="http://docbook.org/ns/docbook"><simpara>
If an <type>int</type> between -128 and 255 inclusive is provided, it is interpreted as
the ASCII value of a single character (negative values have 256 added in order to allow
characters in the Extended ASCII range). Any other integer is interpreted as a string
containing the decimal digits of the integer.</simpara></note>'>

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

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

<!-- FTP Notes -->
<!ENTITY ftp.changelog.ftp-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.1.0</entry>
 <entry>
  The <parameter>ftp</parameter> parameter expects an <classname>FTP\Connection</classname>
  instance now; previously, a &resource; was expected.
 </entry>
</row>'>
<!ENTITY ftp.parameter.ftp '<simpara xmlns="http://docbook.org/ns/docbook">An <classname>FTP\Connection</classname> instance.</simpara>'>

<!-- GMP Notes -->
<!ENTITY gmp.return 'A <classname xmlns="http://docbook.org/ns/docbook">GMP</classname> object.'>
<!ENTITY gmp.parameter '<simpara xmlns="http://docbook.org/ns/docbook">
 A <classname>GMP</classname> object, an &integer;,
 or a &string; that can be interpreted as a number following the same logic
 as if the string was used in <function>gmp_init</function> with automatic
 base detection (i.e. when <parameter>base</parameter> is equal to 0).
</simpara>'>

<!-- MySQLi Notes -->
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
<parameter>result</parameter></term><listitem><simpara>Procedural style only: A <classname>mysqli_result</classname>
object returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>,
<function>mysqli_use_result</function> or <function>mysqli_stmt_get_result</function>.</simpara></listitem></varlistentry>'>
<!ENTITY mysqli.link.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
<parameter>mysql</parameter></term><listitem><simpara>Procedural style only: A <classname>mysqli</classname> object
returned by <function>mysqli_connect</function> or <function>mysqli_init</function>
</simpara></listitem></varlistentry>'>
<!ENTITY mysqli.stmt.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
<parameter>statement</parameter></term><listitem><simpara>Procedural style only: A <classname>mysqli_stmt</classname> object
returned by <function>mysqli_stmt_init</function>.</simpara></listitem></varlistentry>'>
<!ENTITY mysqli.available.mysqlnd 'Available only with <link xmlns="http://docbook.org/ns/docbook"
linkend="book.mysqlnd">mysqlnd</link>.'>
<!ENTITY mysqli.charset.note '<note xmlns="http://docbook.org/ns/docbook">
<simpara>MySQLnd always assumes the server default charset. This charset is sent during connection
hand-shake/authentication, which mysqlnd will use.</simpara><simpara>Libmysqlclient uses the default charset set in the
<filename>my.cnf</filename> or by an explicit call to <function>mysqli_options</function> prior to
calling <function>mysqli_real_connect</function>, but after <function>mysqli_init</function>.</simpara></note>'>
<!ENTITY mysqli.integer.overflow.as.string.note '<note xmlns="http://docbook.org/ns/docbook">
<simpara>If the number of rows is greater than <constant>PHP_INT_MAX</constant>,
the number will be returned as a &string;.</simpara></note>'>
<!ENTITY mysqli.sqlinjection.warning '<warning xmlns="http://docbook.org/ns/docbook">
<title>Security warning: SQL injection</title><simpara>If the query contains any variable
input then <link linkend="mysqli.quickstart.prepared-statements">parameterized
prepared statements</link> should be used instead. Alternatively, the
data must be properly formatted and all strings must be escaped using
the <function>mysqli_real_escape_string</function>
function.</simpara></warning>'>
<!ENTITY mysqli.conditionalexception '<simpara xmlns="http://docbook.org/ns/docbook">
If mysqli error reporting is enabled (<constant>MYSQLI_REPORT_ERROR</constant>) and the requested operation fails,
a warning is generated. If, in addition, the mode is set to <constant>MYSQLI_REPORT_STRICT</constant>,
a <classname>mysqli_sql_exception</classname> is thrown instead.</simpara>'>

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

<!-- Notes for SAPI/Apache -->
<!ENTITY apache.req.module '<simpara xmlns="http://docbook.org/ns/docbook">This function is supported when PHP
is installed as an Apache module webserver.
</simpara>'>

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

<!-- SimpleXML Notes -->
<!ENTITY simplexml.iteration '<note xmlns="http://docbook.org/ns/docbook"><simpara>SimpleXML has made a rule of adding
iterative properties to most methods. They cannot be viewed using <function>var_dump</function>
or anything else which can examine objects.</simpara></note>'>

<!-- Database Notes -->
<!ENTITY database.field-case '<note xmlns="http://docbook.org/ns/docbook"><simpara>Field names returned by this function
are <emphasis>case-sensitive</emphasis>.</simpara></note>'>

<!ENTITY database.fetch-null '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function sets NULL fields to
the PHP &null; value.</simpara></note>'>

<!-- The mysql.*.description entities are used in the parameters refsect1 -->
<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
<parameter>link_identifier</parameter></term><listitem><simpara>The MySQL connection. If the
link identifier is not specified, the last link opened by
<function>mysql_connect</function> is assumed. If no such link is found, it
will try to create one as if <function>mysql_connect</function> had been called
with no arguments. If no connection is found or established, an
<constant>E_WARNING</constant> level error is generated.</simpara></listitem>
</varlistentry>'>

<!ENTITY mysql.linkid-noreopen.description '<varlistentry
xmlns="http://docbook.org/ns/docbook"><term>
<parameter>link_identifier</parameter></term><listitem><simpara>The MySQL connection. If the
link identifier is not specified, the last link opened by
<function>mysql_connect</function> is assumed. If no connection is found or
established, an <constant>E_WARNING</constant> level error is
generated.</simpara></listitem></varlistentry>'>

<!ENTITY mysql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
<parameter>result</parameter></term><listitem><simpara>The result <type>resource</type> that
is being evaluated. This result comes from a call to
<function>mysql_query</function>.</simpara></listitem></varlistentry>'>

<!ENTITY mysql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
<parameter>field_offset</parameter></term><listitem><simpara>The numerical field offset. The
<parameter>field_offset</parameter> starts at <literal>0</literal>. If
<parameter>field_offset</parameter> does not exist, an error of level
<constant>E_WARNING</constant> is also issued.</simpara></listitem></varlistentry>'>

<!ENTITY mysql.alternative.note '<simpara xmlns="http://docbook.org/ns/docbook">This extension was deprecated in PHP 5.5.0, and it was removed in PHP 7.0.0.
Instead, the <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extension should be used.
See also <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
Alternatives to this function include:</simpara>'>

<!ENTITY mysql.alternative.note.4-3-0 '<simpara xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 4.3.0, and it
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
Alternatives to this function include:</simpara>'>

<!ENTITY mysql.alternative.note.5-3-0 '<simpara xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 5.3.0, and it
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
Alternatives to this function include:</simpara>'>

<!ENTITY mysql.alternative.note.5-4-0 '<simpara xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 5.4.0, and it
and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.
Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.
Alternatives to this function include:</simpara>'>

<!ENTITY mysql.close.connections.result.sets '<simpara xmlns="http://docbook.org/ns/docbook">
Open non-persistent MySQL connections and result sets are automatically destroyed when a
PHP script finishes its execution. So, while explicitly closing open
connections and freeing result sets is optional, doing so is recommended.
This will immediately return resources to PHP and MySQL, which can
improve performance. For related information, see
<link linkend="language.types.resource.self-destruct">freeing resources</link></simpara>'>

<!-- Xattr entities -->
<!ENTITY xattr.namespace '<simpara xmlns="http://docbook.org/ns/docbook">Extended attributes have two different namespaces: user
and root. The user namespace is available to all users, while the root namespace
is available only to users with root privileges. xattr operates on the user
namespace  by default, but this can be changed with the
<parameter>flags</parameter> parameter.</simpara>'>

<!-- Notes for IPv6 -->
<!ENTITY ipv6.brackets '<note xmlns="http://docbook.org/ns/docbook"><simpara>When specifying a numerical IPv6 address
(e.g. <literal>fe80::1</literal>), you must enclose the IP in square
brackets—for example, <literal>tcp://[fe80::1]:80</literal>.</simpara></note>'>

<!-- Notes for tidy -->
<!ENTITY tidy.object 'The <classname xmlns="http://docbook.org/ns/docbook">Tidy</classname> object.'>

<!-- Snippets for the installation section -->
<!ENTITY warn.install.third-party-support '<warning xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <simpara>
  Builds from third-parties are considered unofficial and not directly
  supported by the PHP project. Any bugs encountered should be reported to the
  provider of those unofficial builds unless they can be reproduced using the
  builds from <link xlink:href="&url.php.downloads;">the official download
  area</link>.
 </simpara>
</warning>'>

<!ENTITY note.apache.slashes '<note xmlns="http://docbook.org/ns/docbook"><simpara>Remember that when adding
path values in the Apache configuration files on Windows, all backslashes
such as <filename>c:\directory\file.ext</filename> should be converted to
forward slashes: <filename>c:/directory/file.ext</filename>. A trailing
slash may also be necessary for directories.</simpara></note>'>

<!-- Snippets and titles for the contributors section -->
<!ENTITY Credit.Authors.and.Contributors 'Authors and Contributors'>

<!ENTITY Credit.Introduction '<simpara xmlns="http://docbook.org/ns/docbook"> There is a large number of contributors who
currently help in our work or have provided a great amount of help to the project
in the past. There are also a lot of unnamed people who help out with user
notes on manual pages, which continually get included in the references, the
work of whom we are also very thankful for. All of the lists provided below are in
alphabetical order.
</simpara>'>

<!ENTITY Credit.Authors.and.Editors 'Authors and Editors'>

<!ENTITY Credit.Past.Authors.Text 'The following contributors should be
recognized for the impact they have made and/or continue to make by adding
content to the manual:'>

<!ENTITY Credit.Past.Editors.Text 'The following contributors have done
significant work editing the manual:'>

<!ENTITY Credit.Note.Editors.Title 'User Note Maintainers'>

<!ENTITY Credit.Note.Editors.Active 'The currently most active maintainers are:'>

<!ENTITY Credit.Note.Editors.Inactive 'These people have also put a lot of effort
into managing user notes:'>

<!ENTITY listendand ' and'>

<!-- runkit entities -->
<!ENTITY note.runkit.selfmanipulation '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function cannot
be used to manipulate the currently running (or chained) method.</simpara>
</note>'>

<!ENTITY note.runkit.internal-override '<note xmlns="http://docbook.org/ns/docbook"><simpara>By default, only
userspace functions may be removed, renamed, or modified.  In order to
override internal functions, you must enable the
<literal>runkit.internal_override</literal> setting in &php.ini;.</simpara>
</note>'>

<!-- SSH2 Extension -->
<!ENTITY note.ssh2.subsystem.publickey '<note xmlns="http://docbook.org/ns/docbook"><simpara>The public key subsystem
is used for managing public keys on a server to which the client is
<emphasis>already</emphasis> authenticated.  To authenticate to a remote system
using public key authentication, use the
<function>ssh2_auth_pubkey_file</function> function instead.</simpara></note>'>

<!-- Session notes -->
<!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.'>

<!-- XMLWriter Notes -->
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>
<parameter>writer</parameter></term><listitem><simpara>Only for procedural calls.
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>.</simpara></listitem></varlistentry>'>

<!ENTITY xmlwriter.changelog.writer-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>writer</parameter> expects an <classname>XMLWriter</classname>
  instance now; previously, a <type>resource</type> was expected.
 </entry>
</row>'>

<!-- SOAP notes -->
<!ENTITY soap.wsdl.mode.only "<note xmlns='http://docbook.org/ns/docbook'><simpara>This function only works in WSDL mode.</simpara></note>">

<!-- Stomp notes -->
<!ENTITY stomp.param.link "<varlistentry xmlns='http://docbook.org/ns/docbook'><term><parameter>link</parameter></term><listitem><simpara>Procedural style only: The stomp link identifier returned by <function>stomp_connect</function>.</simpara></listitem></varlistentry>">
<!ENTITY stomp.param.headers "<varlistentry xmlns='http://docbook.org/ns/docbook'><term><parameter>headers</parameter></term><listitem><simpara>Associative array containing the additional headers (example: receipt).</simpara></listitem></varlistentry>">
<!ENTITY stomp.note.transaction "<note xmlns='http://docbook.org/ns/docbook'><simpara>A transaction header may be specified, indicating that the message acknowledgment should be part of the named transaction.</simpara></note>">
<!ENTITY stomp.note.sync "<tip xmlns='http://docbook.org/ns/docbook'><simpara>Stomp is inherently asynchronous. Synchronous communication can be implemented adding a receipt header. This will cause methods to not return anything until the server has acknowledged receipt of the message or until read timeout was reached.</simpara></tip>">

<!-- SVN notes -->
<!ENTITY svn.relativepath "<note xmlns='http://docbook.org/ns/docbook'><simpara>Relative paths will be resolved as if the current working directory was the one that contains the PHP binary. To use the calling script&apos;s working directory, use <function>realpath</function> or dirname(__FILE__).</simpara></note>">
<!ENTITY svn.referto.status 'Refer to <link xmlns="http://docbook.org/ns/docbook" linkend="svn.constants.status">status constants</link> for possible values.'>
<!ENTITY svn.referto.type 'Refer to <link xmlns="http://docbook.org/ns/docbook" linkend="svn.constants.type">type constants</link> for possible values.'>

<!-- FANN notes -->
<!ENTITY fann.ann.description '<simpara xmlns="http://docbook.org/ns/docbook">Neural network <type>resource</type>.</simpara>'>
<!ENTITY fann.train.description '<simpara xmlns="http://docbook.org/ns/docbook">Neural network training data <type>resource</type>.</simpara>'>
<!ENTITY fann.errdat.description '<simpara xmlns="http://docbook.org/ns/docbook">Either neural network <type>resource</type> or neural network trainining data <type>resource</type>.</simpara>'>
<!ENTITY fann.return.void '<simpara xmlns="http://docbook.org/ns/docbook">No value is returned.</simpara>'>
<!ENTITY fann.return.bool '<simpara xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</simpara>'>
<!ENTITY fann.return.ann '<simpara xmlns="http://docbook.org/ns/docbook"> Returns a neural network <type>resource</type> on success, or &false; on error.</simpara>'>
<!ENTITY fann.return.train '<simpara xmlns="http://docbook.org/ns/docbook"> Returns a train data <type>resource</type> on success, or &false; on error.</simpara>'>
<!ENTITY fann.note.function.fann-2.2 '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available if the fann extension has been build against libfann &gt;= 2.2.</simpara></note>'>

<!-- Imagick generic return types -->
<!ENTITY imagick.return.success 'Returns &true; on success.'>
<!ENTITY imagick.imagick.throws 'Throws ImagickException on error.'>

<!-- Imagick version infos -->
<!ENTITY imagick.method.available.0x629 'This method is available if Imagick has been compiled against ImageMagick version 6.2.9 or newer.'>
<!ENTITY imagick.method.available.0x631 'This method is available if Imagick has been compiled against ImageMagick version 6.3.1 or newer.'>
<!ENTITY imagick.method.available.0x632 'This method is available if Imagick has been compiled against ImageMagick version 6.3.2 or newer.'>
<!ENTITY imagick.method.available.0x636 'This method is available if Imagick has been compiled against ImageMagick version 6.3.6 or newer.'>
<!ENTITY imagick.method.available.0x637 'This method is available if Imagick has been compiled against ImageMagick version 6.3.7 or newer.'>
<!ENTITY imagick.method.available.0x638 'This method is available if Imagick has been compiled against ImageMagick version 6.3.8 or newer.'>
<!ENTITY imagick.method.available.0x639 'This method is available if Imagick has been compiled against ImageMagick version 6.3.9 or newer.'>
<!ENTITY imagick.method.available.0x640 'This method is available if Imagick has been compiled against ImageMagick version 6.4.0 or newer.'>
<!ENTITY imagick.method.available.0x644 'This method is available if Imagick has been compiled against ImageMagick version 6.4.4 or newer.'>
<!ENTITY imagick.method.available.0x645 'This method is available if Imagick has been compiled against ImageMagick version 6.4.5 or newer.'>
<!ENTITY imagick.method.available.0x647 'This method is available if Imagick has been compiled against ImageMagick version 6.4.7 or newer.'>
<!ENTITY imagick.method.available.0x649 'This method is available if Imagick has been compiled against ImageMagick version 6.4.9 or newer.'>
<!ENTITY imagick.method.available.0x657 'This method is available if Imagick has been compiled against ImageMagick version 6.5.7 or newer.'>

<!ENTITY imagick.method.not.available.0x700 'This method is not available if Imagick has been compiled against ImageMagick version 7.0.0 or newer.'>

<!ENTITY imagick.constant.available 'This constant is available if Imagick has been compiled against ImageMagick version'>

<!ENTITY imagick.deprecated.function-3-4-4 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function has been <emphasis>DEPRECATED</emphasis> as of Imagick 3.4.4. Relying on this function is highly discouraged.</simpara></warning>'>

<!-- Imagick default channel information -->
<!ENTITY imagick.default.channel.info 'Defaults to <constant xmlns="http://docbook.org/ns/docbook">Imagick::CHANNEL_DEFAULT</constant>. Refer to this list of <link xmlns="http://docbook.org/ns/docbook" linkend="imagick.constants.channel">channel constants</link>'>

<!-- Fuzz parameter -->
<!ENTITY imagick.parameter.fuzz 'The amount of fuzz. For example, set fuzz to 10 and the color red at intensities of 100 and 102 respectively are now interpreted as the same color.'>

<!-- Channel parameter -->
<!ENTITY imagick.parameter.channel 'Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine <link xmlns="http://docbook.org/ns/docbook" linkend="imagick.constants.channel">channel constants</link> using bitwise operators. &imagick.default.channel.info;'>

<!-- Alpha parameter -->
<!ENTITY imagick.parameter.alpha 'The level of transparency: 1.0 is fully opaque and 0.0 is fully transparent.'>

<!ENTITY imagick.imagickexception.throw 'Throw an
<classname xmlns="http://docbook.org/ns/docbook">ImagickException</classname> on error.'>

<!ENTITY imagick.bestfit.note '<note xmlns="http://docbook.org/ns/docbook">
 <simpara>
  The behavior of the parameter <parameter>bestfit</parameter> changed in Imagick 3.0.0.
  Before this version given dimensions 400x400 an image of dimensions 200x150 would be
  left untouched. In Imagick 3.0.0 and later the image would be scaled up to size 400x300 as
  this is the "best fit" for the given dimensions. If <parameter>bestfit</parameter>
  parameter is used both width and height must be given.
 </simpara>
</note>'>

<!ENTITY note.openssl.cnf '<note xmlns="http://docbook.org/ns/docbook">
 <simpara>
  You need to have a valid <filename>openssl.cnf</filename> installed for
  this function to operate correctly.
  See the notes under <link linkend="openssl.installation">the installation
  section</link> for more information.
 </simpara>
</note>'>
<!ENTITY note.openssl.param-notext '<simpara xmlns="http://docbook.org/ns/docbook">
 The optional parameter <parameter>notext</parameter> affects
 the verbosity of the output; if it is &false;, then additional human-readable
 information is included in the output. The default value of
 <parameter>notext</parameter> is &true;.
</simpara>'>

<!-- COM/Dotnet -->
<!ENTITY com.variant-arith '<note xmlns="http://docbook.org/ns/docbook">
<simpara>
 As with all the variant arithmetic functions, the parameters for this function
 can be either a PHP native type (integer, string, floating point, boolean or
 &null;), or an instance of a COM, VARIANT or DOTNET class.  PHP native types
 will be converted to variants using the same rules as found in the constructor
 for the <xref linkend="class.variant"/> class.  COM and DOTNET objects
 will have the value of their default property taken and used as the variant value.
</simpara>
<simpara>
 The variant arithmetic functions are wrappers around the similarly named
 functions in the COM library; for more information on these functions, consult
 the MSDN library.  The PHP functions are named slightly differently; for example
 <function>variant_add</function> in PHP corresponds to <literal>VarAdd()
 </literal> in the MSDN documentation.
</simpara>
</note>
'>

<!-- phar -->
<!ENTITY phar.write '<note xmlns="http://docbook.org/ns/docbook"><simpara>This
method requires the &php.ini; setting <literal>phar.readonly</literal> to be
set to <literal>0</literal> in order to work for <classname>Phar</classname>
objects.  Otherwise, a <classname>PharException</classname> will be thrown.</simpara></note>'>

<!ENTITY phar.note.performance '<note xmlns="http://docbook.org/ns/docbook">
 <simpara>
  <function>Phar::addFile</function>, <function>Phar::addFromString</function> and <function>Phar::offsetSet</function>
  save a new phar archive each time they are called. If performance is a concern,
  <function>Phar::buildFromDirectory</function> or <function>Phar::buildFromIterator</function>
  should be used instead.
 </simpara>
</note>'>

<!ENTITY phardata.note.performance '<note xmlns="http://docbook.org/ns/docbook">
 <simpara>
  <function>PharData::addFile</function>, <function>PharData::addFromString</function> and <function>PharData::offsetSet</function>
  save a new phar archive each time they are called. If performance is a concern,
  <function>PharData::buildFromDirectory</function> or <function>PharData::buildFromIterator</function>
  should be used instead.
 </simpara>
</note>'>

<!-- XML -->
<!ENTITY libxml.required '<simpara xmlns="http://docbook.org/ns/docbook">
 This extension requires the <link linkend="book.libxml">libxml</link> PHP extension.
 This means passing the <option role="configure">--with-libxml</option>,
 or prior to PHP 7.4 the <option role="configure">--enable-libxml</option>,
 configuration flag, although this is implicitly accomplished because libxml
 is enabled by default.
</simpara>'>

<!-- XMLReader -->
<!ENTITY xmlreader.libxml20620.note '<caution xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when PHP is compiled against libxml 20620 or later.</simpara></caution>'>

<!-- inotify -->
<!ENTITY inotify.instance.description 'Resource returned by
<function xmlns="http://docbook.org/ns/docbook">inotify_init</function>'>

<!-- User streams -->
<!ENTITY userstream.not.implemented.warning '<simpara xmlns="http://docbook.org/ns/docbook">Emits
<constant>E_WARNING</constant> if call to this method fails
(i.e. not implemented).</simpara>'>
<!ENTITY userstream.updates.context '<note xmlns="http://docbook.org/ns/docbook"><simpara>The
<varname linkend="streamwrapper.props.context">streamWrapper::$context</varname>
property is updated if a valid context is passed to the caller function.</simpara></note>'>

<!ENTITY stream.bucket.param '<parameter>bucket</parameter> expects a <classname>StreamBucket</classname> instance now; previously, an <classname>stdClass</classname> was expected.'>
<!ENTITY stream.bucket.return 'This function returns a <classname>StreamBucket</classname> instance now; previously, an <classname>stdClass</classname> was returned.'>

<!-- Gmagick -->
<!ENTITY gmagick.gmagickexception.throw 'Throws an
<classname xmlns="http://docbook.org/ns/docbook">GmagickException</classname> on error.'>

<!-- Reflection -->
<!ENTITY reflection.export.return 'If the <parameter xmlns="http://docbook.org/ns/docbook">return</parameter> parameter
is set to &true;, then the export is returned as a <type xmlns="http://docbook.org/ns/docbook">string</type>,
otherwise &null; is returned.'>

<!ENTITY reflection.export.param.return 'Setting to &true; will return the export,
as opposed to emitting it. Setting to &false; (the default) will do the opposite.'>

<!ENTITY reflection.invoke.reference 'If the function has arguments that need
to be references, then they must be references in the passed argument list.'>

<!ENTITY reflection.export.param.name 'The reflection to export.'>

<!ENTITY reflection.getattributes.param.name '<varlistentry xmlns="http://docbook.org/ns/docbook">
<term><parameter>name</parameter></term>
<listitem>
 <simpara>
  Filter the results to include only <classname>ReflectionAttribute</classname>
  instances for attributes matching this class name.
 </simpara>
</listitem>
</varlistentry>'>

<!ENTITY reflection.getattributes.param.flags '<varlistentry xmlns="http://docbook.org/ns/docbook">
<term><parameter>flags</parameter></term>
<listitem>
 <simpara>
  Flags for determining how to filter the results, if <parameter>name</parameter>
  is provided.
 </simpara>
 <simpara>
  Default is <literal>0</literal> which will only return results for attributes that
  are of the class <parameter>name</parameter>.
 </simpara>
 <simpara>
  The only other option available, is to use <constant>ReflectionAttribute::IS_INSTANCEOF</constant>,
  which will instead use <literal>instanceof</literal> for filtering.
 </simpara>
</listitem>
</varlistentry>'>

<!-- ZIP -->
<!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>'>

<!-- Win32Service -->
<!ENTITY win32service.false.error ', &false; if there is a problem with the parameters or a <link xmlns="http://docbook.org/ns/docbook" linkend="win32service.constants.errors">Win32 Error Code</link> on failure.'>
<!ENTITY win32service.noerror.false.error 'returned <constant xmlns="http://docbook.org/ns/docbook">WIN32_NO_ERROR</constant> on success&win32service.false.error;'>

<!-- SNMP -->
<!ENTITY snmp.set.type.values '<simpara xmlns="http://docbook.org/ns/docbook">
 The <acronym>MIB</acronym> defines the type of each object id. It has to be specified as a single character from the below list.
</simpara>
<table xmlns="http://docbook.org/ns/docbook">
 <title>types</title>
 <tgroup cols="2">
  <tbody>
   <row><entry>=</entry><entry>The type is taken from the MIB</entry></row>
   <row><entry>i</entry><entry>INTEGER</entry> </row>
   <row><entry>u</entry><entry>INTEGER</entry></row>
   <row><entry>s</entry><entry>STRING</entry></row>
   <row><entry>x</entry><entry>HEX STRING</entry></row>
   <row><entry>d</entry><entry>DECIMAL STRING</entry></row>
   <row><entry>n</entry><entry>NULLOBJ</entry></row>
   <row><entry>o</entry><entry>OBJID</entry></row>
   <row><entry>t</entry><entry>TIMETICKS</entry></row>
   <row><entry>a</entry><entry>IPADDRESS</entry></row>
   <row><entry>b</entry><entry>BITS</entry></row>
  </tbody>
 </tgroup>
</table>
<simpara xmlns="http://docbook.org/ns/docbook">
 If <constant>OPAQUE_SPECIAL_TYPES</constant> was defined while compiling the <acronym>SNMP</acronym> library, the following are also valid:
</simpara>
<table xmlns="http://docbook.org/ns/docbook">
 <title>types</title>
 <tgroup cols="2">
  <tbody>
   <row><entry>U</entry><entry>unsigned int64</entry></row>
   <row><entry>I</entry><entry>signed int64</entry></row>
   <row><entry>F</entry><entry>float</entry></row>
   <row><entry>D</entry><entry>double</entry></row>
  </tbody>
 </tgroup>
</table>
'>
<!ENTITY snmp.set.type.values.asn.mapping '<simpara xmlns="http://docbook.org/ns/docbook">
 Most of these will use the obvious corresponding ASN.1 type.  &apos;s&apos;, &apos;x&apos;, &apos;d&apos; and &apos;b&apos; are all different ways of specifying an OCTET STRING value, and
 the &apos;u&apos; unsigned type is also used for handling Gauge32 values.
</simpara>
'>
<!ENTITY snmp.set.type.values.equal.note '<simpara xmlns="http://docbook.org/ns/docbook">
 If the MIB-Files are loaded by into the MIB Tree with "snmp_read_mib" or by specifying it in the libsnmp config, &apos;=&apos; may be used as
 the <parameter>type</parameter> parameter for all object ids as the type can then be automatically read from the MIB.
</simpara>
'>
<!ENTITY snmp.set.type.values.bitset.note '<simpara xmlns="http://docbook.org/ns/docbook">
 Note that there are two ways to set a variable of the type BITS like e.g.
 "SYNTAX    BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}":
</simpara>
<itemizedlist xmlns="http://docbook.org/ns/docbook">
 <listitem>
  <simpara>
   Using type "b" and a list of bit numbers. This method is not recommended since GET query for the same OID would return e.g. 0xF8.
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   Using type "x" and a hex number but without(!) the usual "0x" prefix.
  </simpara>
 </listitem>
</itemizedlist>
<simpara xmlns="http://docbook.org/ns/docbook">
 See examples section for more details.
</simpara>
'>
<!ENTITY snmp.methods.exceptions_enable.refsect '<refsect1 role="errors" xmlns="http://docbook.org/ns/docbook">
&reftitle.errors;
<simpara>
 This method does not throw any exceptions by default.
 To enable throwing an SNMPException exception when some of library errors occur
 the SNMP class parameter <parameter>exceptions_enabled</parameter>
 should be set to a corresponding value. See <link linkend="snmp.props.exceptions-enabled">
 <parameter>SNMP::$exceptions_enabled</parameter> explanation</link> for more details.
</simpara>
</refsect1>
'>

<!-- Eio -->
<!ENTITY eio.callback.proto '<para xmlns="http://docbook.org/ns/docbook">
<parameter xmlns="http://docbook.org/ns/docbook">callback</parameter> function is called when the request is done.
It should match the following prototype: <programlisting role="php"><![CDATA[
void callback(mixed $data, int $result[, resource $req]);
]]></programlisting>
<variablelist xmlns="http://docbook.org/ns/docbook">
<varlistentry xmlns="http://docbook.org/ns/docbook">
<term><parameter>data</parameter></term>
<listitem><simpara>is custom data passed to the request.</simpara></listitem>
</varlistentry>
<varlistentry xmlns="http://docbook.org/ns/docbook">
<term><parameter>result</parameter></term>
<listitem><simpara>request-specific result value; basically, the value returned by corresponding
system call.</simpara></listitem>
</varlistentry>
<varlistentry xmlns="http://docbook.org/ns/docbook">
<term><parameter>req</parameter></term>
<listitem><simpara>is optional request resource which can be used with functions like <function>eio_get_last_error</function>.</simpara></listitem>
</varlistentry>
</variablelist>
</para>
'>

<!ENTITY eio.request.pri.values '<simpara
xmlns="http://docbook.org/ns/docbook">The request priority: <constant
xmlns="http://docbook.org/ns/docbook">EIO_PRI_DEFAULT</constant>, <constant
xmlns="http://docbook.org/ns/docbook">EIO_PRI_MIN</constant>, <constant
xmlns="http://docbook.org/ns/docbook">EIO_PRI_MAX</constant>, or &null;.
If &null; passed, <parameter
xmlns="http://docbook.org/ns/docbook">pri</parameter> internally is set to
<constant xmlns="http://docbook.org/ns/docbook">EIO_PRI_DEFAULT</constant>.
</simpara>
'>

<!ENTITY eio.warn.relpath '<warning
xmlns="http://docbook.org/ns/docbook"><simpara xmlns="http://docbook.org/ns/docbook">Avoid relative
paths</simpara></warning>
'>

<!ENTITY trader.arg.array.of.real 'Array of real values.'>
<!ENTITY trader.arg.array.of.real.high 'High price, array of real values.'>
<!ENTITY trader.arg.array.of.real.low 'Low price, array of real values.'>
<!ENTITY trader.arg.array.of.real.close 'Closing price, array of real values.'>
<!ENTITY trader.arg.array.of.real.open 'Opening price, array of real values.'>
<!ENTITY trader.arg.array.of.real.volume 'Volume traded, array of real values.'>
<!ENTITY trader.arg.array.of.real.periods 'Array of real values.'>
<!ENTITY trader.arg.penetration 'Percentage of penetration of a candle within another candle.'>
<!ENTITY trader.arg.vfactor 'Volume Factor. Valid range from 1 to 0.'>
<!ENTITY trader.arg.time.period 'Number of period. Valid range from 2 to 100000.'>
<!ENTITY trader.arg.fast.period 'Number of period for the fast MA. Valid range from 2 to 100000.'>
<!ENTITY trader.arg.slow.period 'Number of period for the slow MA. Valid range from 2 to 100000.'>
<!ENTITY trader.arg.signal.period 'Smoothing for the signal line (nb of period). Valid range from 1 to 100000.'>
<!ENTITY trader.arg.fastk.period 'Time period for building the Fast-K line. Valid range from 1 to 100000.'>
<!ENTITY trader.arg.fastd.period 'Smoothing for making the Fast-D line. Valid range from 1 to 100000, usually set to 3.'>
<!ENTITY trader.arg.slowk.period 'Smoothing for making the Slow-K line. Valid range from 1 to 100000, usually set to 3.'>
<!ENTITY trader.arg.slowd.period 'Smoothing for making the Slow-D line. Valid range from 1 to 100000.'>
<!ENTITY trader.arg.min.period 'Value less than minimum will be changed to Minimum period. Valid range from 2 to 100000'>
<!ENTITY trader.arg.max.period 'Value higher than minimum will be changed to Maximum period. Valid range from 2 to 100000'>
<!ENTITY trader.arg.ma.type 'Type of Moving Average. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>
<!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.'>
<!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.'>
<!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.'>
<!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.'>
<!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.'>
<!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.'>
<!ENTITY trader.arg.nbdevup 'Deviation multiplier for upper band. Valid range from <link xmlns="http://docbook.org/ns/docbook" linkend="constant.trader-real-min">TRADER_REAL_MIN</link> to <link xmlns="http://docbook.org/ns/docbook" linkend="constant.trader-real-max">TRADER_REAL_MAX</link>.'>
<!ENTITY trader.arg.nbdevdn 'Deviation multiplier for lower band. Valid range from <link xmlns="http://docbook.org/ns/docbook" linkend="constant.trader-real-min">TRADER_REAL_MIN</link> to <link xmlns="http://docbook.org/ns/docbook" linkend="constant.trader-real-max">TRADER_REAL_MAX</link>.'>
<!ENTITY trader.arg.fast.limit 'Upper limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.'>
<!ENTITY trader.arg.slow.limit 'Lower limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.'>

<!-- mongodb -->
<!ENTITY mongodb.changelog.class-removed '
       <row xmlns="http://docbook.org/ns/docbook">
        <entry>PECL mongodb 2.0.0</entry>
        <entry>
         This class was removed.
        </entry>
       </row>
'>

<!ENTITY mongodb.changelog.function-removed '
       <row xmlns="http://docbook.org/ns/docbook">
        <entry>PECL mongodb 2.0.0</entry>
        <entry>
         This function was removed.
        </entry>
       </row>
'>

<!ENTITY mongodb.changelog.method-removed '
       <row xmlns="http://docbook.org/ns/docbook">
        <entry>PECL mongodb 2.0.0</entry>
        <entry>
         This method was removed.
        </entry>
       </row>
'>

<!ENTITY mongodb.changelog.serializable-interface-removed '
       <row xmlns="http://docbook.org/ns/docbook">
        <entry>PECL mongodb 2.0.0</entry>
        <entry>
         <simpara>
          This class no longer implements the
          <interfacename>Serializable</interfacename> interface.
         </simpara>
        </entry>
       </row>
'>

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

<!ENTITY mongodb.changelog.tentative-return-types-enforced '
       <row xmlns="http://docbook.org/ns/docbook">
        <entry>PECL mongodb 2.0.0</entry>
        <entry>
         Return types previously declared as tentative are now enforced.
        </entry>
       </row>
'>

<!ENTITY mongodb.changelog.throw-unacknowledged-write '
       <row xmlns="http://docbook.org/ns/docbook">
        <entry>PECL mongodb 2.0.0</entry>
        <entry>
         <simpara>
          This method now throws an exception when called for an unacknowledged write instead of returning &null;.
         </simpara>
        </entry>
       </row>
'>

<!ENTITY mongodb.option.collation '
         <row xmlns="http://docbook.org/ns/docbook">
          <entry>collation</entry>
          <entry><type class="union"><type>array</type><type>object</type></type></entry>
          <entry>
           <simpara>
            <link xlink:href="&url.mongodb.docs.collation;" xmlns:xlink="http://www.w3.org/1999/xlink">Collation</link> allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the <literal>"locale"</literal> field is mandatory; all other collation fields are optional. For descriptions of the fields, see <link xlink:href="&url.mongodb.docs.collation;#collation-document" xmlns:xlink="http://www.w3.org/1999/xlink">Collation Document</link>.
           </simpara>
           <simpara>
            If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons.
           </simpara>
           <simpara>
            This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.
           </simpara>
          </entry>
         </row>
'>
<!ENTITY mongodb.option.let '
         <row xmlns="http://docbook.org/ns/docbook">
          <entry>let</entry>
          <entry><type class="union"><type>array</type><type>object</type></type></entry>
          <entry>
           <simpara>
            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>).
           </simpara>
           <simpara>
            This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.
           </simpara>
          </entry>
         </row>
'>
<!ENTITY mongodb.option.encryption.keyVaultClient '
         <row xmlns="http://docbook.org/ns/docbook">
          <entry>keyVaultClient</entry>
          <entry><classname>MongoDB\Driver\Manager</classname></entry>
          <entry>The Manager used to route data key queries to a separate MongoDB cluster. By default, the current Manager and cluster is used.</entry>
         </row>
'>
<!ENTITY mongodb.option.encryption.keyVaultNamespace '
         <row xmlns="http://docbook.org/ns/docbook">
          <entry>keyVaultNamespace</entry>
          <entry><type>string</type></entry>
          <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>
         </row>
'>
<!ENTITY mongodb.option.encryption.kmsProviders '
         <row xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
          <entry>kmsProviders</entry>
          <entry><type>array</type></entry>
          <entry>
           <simpara>
            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.
           </simpara>
           <simpara>
            If an empty document is specified for <literal>"aws"</literal>,
            <literal>"azure"</literal>, or <literal>"gcp"</literal>, the driver
            will attempt to configure the provider using
            <link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#automatic-credentials">Automatic Credentials</link>.
           </simpara>
           <simpara>
            The format for <literal>"aws"</literal> is as follows:
           </simpara>
           <programlisting role="javascript">
<![CDATA[
aws: {
    accessKeyId: <string>,
    secretAccessKey: <string>,
    sessionToken: <optional string>
}
]]>
           </programlisting>
           <simpara>
            The format for <literal>"azure"</literal> is as follows:
           </simpara>
           <programlisting role="javascript">
<![CDATA[
azure: {
    tenantId: <string>,
    clientId: <string>,
    clientSecret: <string>,
    identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
}
]]>
           </programlisting>
           <simpara>
            The format for <literal>"gcp"</literal> is as follows:
           </simpara>
           <programlisting role="javascript">
<![CDATA[
gcp: {
    email: <string>,
    privateKey: <base64 string>|<MongoDB\BSON\Binary>,
    endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
}
]]>
           </programlisting>
           <simpara>
            The format for <literal>"kmip"</literal> is as follows:
           </simpara>
           <programlisting role="javascript">
<![CDATA[
kmip: {
    endpoint: <string>
}
]]>
           </programlisting>
           <simpara>
            The format for <literal>"local"</literal> is as follows:
           </simpara>
           <programlisting role="javascript">
<![CDATA[
local: {
    // 96-byte master key used to encrypt/decrypt data keys
    key: <base64 string>|<MongoDB\BSON\Binary>
}
]]>
           </programlisting>
          </entry>
         </row>
'>
<!ENTITY mongodb.option.encryption.masterKey-options-by-provider '
  <para xmlns="http://docbook.org/ns/docbook">
   <table>
    <title><literal>"aws"</literal> provider options</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Option</entry>
       <entry>Type</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>region</entry>
       <entry>string</entry>
       <entry>Required.</entry>
      </row>
      <row>
       <entry>key</entry>
       <entry>string</entry>
       <entry>Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).</entry>
      </row>
      <row>
       <entry>endpoint</entry>
       <entry>string</entry>
       <entry>Optional. An alternate host identifier to send KMS requests to. May include port number.</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para xmlns="http://docbook.org/ns/docbook">
   <table>
    <title><literal>"azure"</literal> provider options</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Option</entry>
       <entry>Type</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>keyVaultEndpoint</entry>
       <entry>string</entry>
       <entry>Required. Host with optional port (e.g. "example.vault.azure.net").</entry>
      </row>
      <row>
       <entry>keyName</entry>
       <entry>string</entry>
       <entry>Required.</entry>
      </row>
      <row>
       <entry>keyVersion</entry>
       <entry>string</entry>
       <entry>Optional. A specific version of the named key. Defaults to using the key&apos;s primary version.</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para xmlns="http://docbook.org/ns/docbook">
   <table>
    <title><literal>"gcp"</literal> provider options</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Option</entry>
       <entry>Type</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>projectId</entry>
       <entry>string</entry>
       <entry>Required.</entry>
      </row>
      <row>
       <entry>location</entry>
       <entry>string</entry>
       <entry>Required.</entry>
      </row>
      <row>
       <entry>keyRing</entry>
       <entry>string</entry>
       <entry>Required.</entry>
      </row>
      <row>
       <entry>keyName</entry>
       <entry>string</entry>
       <entry>Required.</entry>
      </row>
      <row>
       <entry>keyVersion</entry>
       <entry>string</entry>
       <entry>Optional. A specific version of the named key. Defaults to using the key&apos;s primary version.</entry>
      </row>
      <row>
       <entry>endpoint</entry>
       <entry>string</entry>
       <entry>Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para xmlns="http://docbook.org/ns/docbook">
   <table>
    <title><literal>"kmip"</literal> provider options</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Option</entry>
       <entry>Type</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>keyId</entry>
       <entry>string</entry>
       <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>
      </row>
      <row>
       <entry>endpoint</entry>
       <entry>string</entry>
       <entry>Optional. Host with optional port.</entry>
      </row>
      <row>
       <entry>delegated</entry>
       <entry>bool</entry>
       <entry>Optional. If true, this key should be decrypted by the KMIP server.</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
'>
<!ENTITY mongodb.option.encryption.tlsOptions '
         <row xmlns="http://docbook.org/ns/docbook">
          <entry>tlsOptions</entry>
          <entry><type>array</type></entry>
          <entry>
           <simpara>
            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:
           </simpara>
           <programlisting role="javascript">
<![CDATA[
<provider>: {
    tlsCaFile: <optional string>,
    tlsCertificateKeyFile: <optional string>,
    tlsCertificateKeyFilePassword: <optional string>,
    tlsDisableOCSPEndpointCheck: <optional bool>
}
]]>
           </programlisting>
          </entry>
         </row>
'>
<!ENTITY mongodb.option.maxCommitTimeMS '
         <row xmlns="http://docbook.org/ns/docbook">
          <entry>maxCommitTimeMS</entry>
          <entry>integer</entry>
          <entry>
           <simpara>
            The maximum amount of time in milliseconds to allow a single
            <literal>commitTransaction</literal> command to run.
           </simpara>
           <simpara>
            If specified, <literal>maxCommitTimeMS</literal> must be a signed
            32-bit integer greater than or equal to zero.
           </simpara>
          </entry>
         </row>
'>
<!ENTITY mongodb.option.readConcern '
         <row xmlns="http://docbook.org/ns/docbook">
          <entry>readConcern</entry>
          <entry><classname>MongoDB\Driver\ReadConcern</classname></entry>
          <entry>
           <simpara>
            A read concern to apply to the operation.
           </simpara>
           <simpara>
            This option is available in MongoDB 3.2+ and will result in an
            exception at execution time if specified for an older server
            version.
           </simpara>
          </entry>
         </row>
'>
<!ENTITY mongodb.option.readPreference '
         <row xmlns="http://docbook.org/ns/docbook">
          <entry>readPreference</entry>
          <entry><classname>MongoDB\Driver\ReadPreference</classname></entry>
          <entry>
           <simpara>
            A read preference to use for selecting a server for the operation.
           </simpara>
          </entry>
         </row>
'>
<!ENTITY mongodb.option.session '
         <row xmlns="http://docbook.org/ns/docbook">
          <entry>session</entry>
          <entry><classname>MongoDB\Driver\Session</classname></entry>
          <entry>
           <simpara>
            A session to associate with the operation.
           </simpara>
          </entry>
         </row>
'>
<!ENTITY mongodb.option.transactionReadWriteConcern '
     <warning xmlns="http://docbook.org/ns/docbook">
      <simpara>
       If you are using a <literal>"session"</literal> which has a transaction
       in progress, you cannot specify a <literal>"readConcern"</literal> or
       <literal>"writeConcern"</literal> option. This will result in an
       <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname>
       being thrown. Instead, you should set these two options when you create
       the transaction with
       <methodname>MongoDB\Driver\Session::startTransaction</methodname>.
      </simpara>
     </warning>
'>
<!ENTITY mongodb.option.writeConcern '
         <row xmlns="http://docbook.org/ns/docbook">
          <entry>writeConcern</entry>
          <entry><classname>MongoDB\Driver\WriteConcern</classname></entry>
          <entry>
           <simpara>
            A write concern to apply to the operation.
           </simpara>
          </entry>
         </row>
'>
<!ENTITY mongodb.parameter.namespace '
   <varlistentry xmlns="http://docbook.org/ns/docbook">
    <term><parameter>namespace</parameter> (<type>string</type>)</term>
    <listitem>
     <simpara>
      A fully qualified namespace (e.g. <literal>"databaseName.collectionName"</literal>).
     </simpara>
    </listitem>
   </varlistentry>
'>
<!ENTITY mongodb.parameter.db '
   <varlistentry xmlns="http://docbook.org/ns/docbook">
    <term><parameter>db</parameter> (<type>string</type>)</term>
    <listitem>
     <simpara>
      The name of the database on which to execute the command.
     </simpara>
    </listitem>
   </varlistentry>
'>
<!ENTITY mongodb.parameter.bulkwrite '
   <varlistentry xmlns="http://docbook.org/ns/docbook">
    <term><parameter>bulk</parameter> (<classname>MongoDB\Driver\BulkWrite</classname>)</term>
    <listitem>
     <simpara>
      The write(s) to execute.
     </simpara>
    </listitem>
   </varlistentry>
'>
<!ENTITY mongodb.parameter.bulkwritecommand '
   <varlistentry xmlns="http://docbook.org/ns/docbook">
    <term><parameter>bulk</parameter> (<classname>MongoDB\Driver\BulkWriteCommand</classname>)</term>
    <listitem>
     <simpara>
      The write(s) to execute.
     </simpara>
    </listitem>
   </varlistentry>
'>
<!ENTITY mongodb.parameter.command '
   <varlistentry xmlns="http://docbook.org/ns/docbook">
    <term><parameter>command</parameter> (<classname>MongoDB\Driver\Command</classname>)</term>
    <listitem>
     <simpara>
      The command to execute.
     </simpara>
    </listitem>
   </varlistentry>
'>
<!ENTITY mongodb.parameter.encryptOpts '
   <varlistentry xmlns="http://docbook.org/ns/docbook">
    <term><parameter>options</parameter></term>
    <listitem>
     <para>
      <table>
       <title>Encryption options</title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry>Option</entry>
          <entry>Type</entry>
          <entry>Description</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>algorithm</entry>
          <entry><type>string</type></entry>
          <entry>
           <simpara>
            The encryption algorithm to be used. This option is required.
            Specify one of the following
            <link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
           </simpara>
           <simplelist>
            <member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC</constant></member>
            <member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM</constant></member>
            <member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant></member>
            <member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED</constant></member>
            <member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant></member>
           </simplelist>
          </entry>
         </row>
         <row>
          <entry>contentionFactor</entry>
          <entry><type>int</type></entry>
          <entry>
           <simpara>
            The contention factor for evaluating queries with indexed, encrypted
            payloads.
           </simpara>
           <simpara>
            This option only applies and may only be specified when
            <literal>algorithm</literal> is
            <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
            or
            <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant>.
           </simpara>
          </entry>
         </row>
         <row>
          <entry>keyAltName</entry>
          <entry><type>string</type></entry>
          <entry>
           <simpara>
            Identifies a key vault collection document by
            <literal>keyAltName</literal>. This option is mutually exclusive
            with <literal>keyId</literal> and exactly one is required.
           </simpara>
          </entry>
         </row>
         <row>
          <entry>keyId</entry>
          <entry><classname>MongoDB\BSON\Binary</classname></entry>
          <entry>
           <simpara>
            Identifies a data key by <literal>_id</literal>. The value is a UUID
            (binary subtype 4). This option is mutually exclusive with
            <literal>keyAltName</literal> and exactly one is required.
           </simpara>
          </entry>
         </row>
         <row>
          <entry>queryType</entry>
          <entry><type>string</type></entry>
          <entry>
           <simpara>
            The query type for evaluating queries with indexed, encrypted
            payloads. Specify one of the following
            <link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:
           </simpara>
           <simplelist>
            <member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY</constant></member>
            <member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE</constant></member>
           </simplelist>
           <simpara>
            This option only applies and may only be specified when
            <literal>algorithm</literal> is
            <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>
            or <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant>.
           </simpara>
          </entry>
         </row>
         <row>
          <entry>rangeOpts</entry>
          <entry><type>array</type></entry>
          <entry>
           <simpara>
            Index options for a queryable encryption field supporting "range"
            queries. The options below must match the values set in the
            <literal>encryptedFields</literal> of the target collection. For
            double and decimal128 BSON field types, <literal>min</literal>,
            <literal>max</literal>, and <literal>precision</literal> must all be
            set, or all be unset.
           </simpara>
           <para>
            <table>
             <title>Range index options</title>
             <tgroup cols="3">
              <thead>
               <row>
                <entry>Option</entry>
                <entry>Type</entry>
                <entry>Description</entry>
               </row>
              </thead>
              <tbody>
               <row>
                <entry>min</entry>
                <entry><type>mixed</type></entry>
                <entry>
                 Required if <literal>precision</literal> is set. The minimum
                 BSON value of the range.
                </entry>
               </row>
               <row>
                <entry>max</entry>
                <entry><type>mixed</type></entry>
                <entry>
                 Required if <literal>precision</literal> is set. The maximum
                 BSON value of the range.
                </entry>
               </row>
               <row>
                <entry>sparsity</entry>
                <entry><type>int</type></entry>
                <entry>Optional. Positive 64-bit integer.</entry>
               </row>
               <row>
                <entry>precision</entry>
                <entry><type>int</type></entry>
                <entry>
                 Optional. Positive 32-bit integer specifying precision to use
                 for explicit encryption. May only be set for double or
                 decimal128 BSON field types.
                </entry>
               </row>
               <row>
                <entry>trimFactor</entry>
                <entry><type>int</type></entry>
                <entry>Optional. Positive 32-bit integer.</entry>
               </row>
              </tbody>
             </tgroup>
            </table>
           </para>
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
    </listitem>
   </varlistentry>
'>
<!ENTITY mongodb.parameter.query '
   <varlistentry xmlns="http://docbook.org/ns/docbook">
    <term><parameter>query</parameter> (<classname>MongoDB\Driver\Query</classname>)</term>
    <listitem>
     <simpara>
      The query to execute.
     </simpara>
    </listitem>
   </varlistentry>
'>
<!ENTITY mongodb.parameter.typeMap '
   <varlistentry xmlns="http://docbook.org/ns/docbook">
    <term><parameter>typeMap</parameter> (<type>array</type>)</term>
    <listitem>
     <simpara>
      <link linkend="mongodb.persistence.typemaps">Type map configuration</link>.
     </simpara>
    </listitem>
   </varlistentry>
'>
<!ENTITY mongodb.parameter.filter '
   <varlistentry xmlns="http://docbook.org/ns/docbook">
    <term><parameter>filter</parameter> (<type class="union"><type>array</type><type>object</type></type>)</term>
    <listitem>
     <simpara>
      The <link xlink:href="&url.mongodb.docs;tutorial/query-documents/" xmlns:xlink="http://www.w3.org/1999/xlink">query predicate</link>.
      An empty predicate will match all documents in the collection.
     </simpara>
     <note>
      <simpara>
       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&apos;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>).
      </simpara>
     </note>
    </listitem>
   </varlistentry>
'>
<!ENTITY mongodb.returns.cursor '<simpara xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\Cursor</classname> on success.</simpara>'>
<!ENTITY mongodb.returns.writeresult '<simpara xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\WriteResult</classname> on success.</simpara>'>
<!ENTITY mongodb.returns.bulkwritecommandresult '<simpara xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\BulkWriteCommandResult</classname> on success.</simpara>'>
<!ENTITY mongodb.throws.std '&mongodb.throws.argumentparsing;&mongodb.throws.connection;&mongodb.throws.authentication;'>
<!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>'>
<!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>'>
<!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>'>
<!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>'>
<!ENTITY mongodb.throws.argumentparsing '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> on argument parsing errors.</member>'>
<!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>'>
<!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>'>
<!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>'>
<!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>'>

<!-- Not used in EN anymore -->

<!ENTITY mongodb.note.decimal128 '
   <note xmlns="http://docbook.org/ns/docbook">
    <simpara>
     <classname>MongoDB\BSON\Decimal128</classname> is only compatible with
     MongoDB 3.4+. Attempting to use the BSON type with an earlier version of
     MongoDB will result in an error.
    </simpara>
   </note>
'>
<!ENTITY mongodb.note.extended-json '
  <note xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
   <simpara>
    The output is consistent with the <function>MongoDB\BSON\toJSON</function>
    function, which uses the driver-specific legacy extended JSON format. This
    does not necessarily match the
    <link xlink:href="&url.mongodb.specs.extendedjson;#relaxed-extended-json-example">relaxed</link>
    or <link xlink:href="&url.mongodb.specs.extendedjson;#canonical-extended-json-example">canonical</link>
    extended JSON representations used by
    <function>MongoDB\BSON\toRelaxedExtendedJSON</function> and
    <function>MongoDB\BSON\toCanonicalExtendedJSON</function>, respectively.
   </simpara>
  </note>
'>
<!ENTITY mongodb.note.forking '
   <note xmlns="http://docbook.org/ns/docbook">
    <simpara>
     On Unix platforms, the extension is sensitive to scripts that use the
     fork() system call without also calling exec(). Users are advised not to
     re-use <classname>MongoDB\Driver\Manager</classname> instances in a forked
     child process.
    </simpara>
   </note>
'>

<!ENTITY mongodb.note.uint32 '
  <note xmlns="http://docbook.org/ns/docbook">
   <simpara>
    Because PHP&apos;s integer type is signed, some values returned by this
    method may appear as negative integers on 32-bit platforms. The
    <literal>"&#37;u"</literal> formatter of <function>sprintf</function> may be
    used to obtain a string representation of the unsigned decimal value.
   </simpara>
  </note>
'>

<!ENTITY mongodb.note.server.readpreference '
  <note xmlns="http://docbook.org/ns/docbook">
   <simpara>
    The <literal>"readPreference"</literal> option does not control the server
    to which the driver issues the operation; it will always be executed on
    this server object. Instead, it may be used when issuing the operation to a
    secondary (from a replica set connection, not standalone) or mongos node to
    ensure that the driver sets the wire protocol accordingly or adds the read
    preference to the operation, respectively.
   </simpara>
  </note>
'>

<!ENTITY mongodb.note.server.write '
  <note xmlns="http://docbook.org/ns/docbook">
   <simpara>
    It is the caller&apos;s responsibility to ensure that the server is capable
    of executing the write operation. For example, executing a write operation
    on a secondary (excluding its "local" database) will fail.
   </simpara>
  </note>
'>

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

<!-- Radius -->
<!ENTITY radius.request.required '<note xmlns="http://docbook.org/ns/docbook"><simpara>A request must be created via <function>radius_create_request</function> before this function can be called.</simpara></note>'>
<!ENTITY radius.parameter.attribute-type '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>type</parameter></term><listitem><simpara>The attribute type.</simpara></listitem></varlistentry>'>
<!ENTITY radius.parameter.handle '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>radius_handle</parameter></term><listitem><simpara>The RADIUS resource.</simpara></listitem></varlistentry>'>
<!ENTITY radius.parameter.options '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>options</parameter></term><listitem><simpara>A bitmask of the attribute options. The available options include <link linkend="constant.radius-option-tagged"><constant>RADIUS_OPTION_TAGGED</constant></link> and <link linkend="constant.radius-option-salt"><constant>RADIUS_OPTION_SALT</constant></link>.</simpara></listitem></varlistentry>'>
<!ENTITY radius.parameter.tag '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>tag</parameter></term><listitem><simpara>The attribute tag. This parameter is ignored unless the <link linkend="constant.radius-option-tagged"><constant>RADIUS_OPTION_TAGGED</constant></link> option is set.</simpara></listitem></varlistentry>'>
<!ENTITY radius.parameter.vendor '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>vendor</parameter></term><listitem><simpara>The vendor ID.</simpara></listitem></varlistentry>'>

<!-- posix snippets -->
<!ENTITY posix.parameter.fd '<varlistentry xmlns="http://docbook.org/ns/docbook">
 <term><parameter>file_descriptor</parameter></term>
 <listitem>
  <simpara>
   The file descriptor, which is expected to be either a file
   <type>resource</type> or an <type>int</type>. An <type>int</type>
   will be assumed to be a file descriptor that can be passed directly to
   the underlying system call.
  </simpara>
 </listitem>
</varlistentry>'>

<!ENTITY posix.rlimits '
<simpara xmlns="http://docbook.org/ns/docbook">
  Each resource has an associated soft and hard limit.  The soft
  limit is the value that the kernel enforces for the corresponding
  resource.  The hard limit acts as a ceiling for the soft limit.
  An unprivileged process may only set its soft limit to a value
  from 0 to the hard limit, and irreversibly lower its hard limit.
</simpara>
'>

<!-- strings snippets -->
<!ENTITY strings.stripped.characters '
 <itemizedlist xmlns="http://docbook.org/ns/docbook">
    <listitem>
     <simpara>
      <literal>" "</literal>: <acronym>ASCII</acronym> <acronym>SP</acronym> character
      <literal>0x20</literal>, an ordinary space.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\t"</literal>: <acronym>ASCII</acronym> <acronym>HT</acronym> character
      <literal>0x09</literal>, a tab.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\n"</literal>: <acronym>ASCII</acronym> <acronym>LF</acronym> character
      <literal>0x0A</literal>, a new line (line feed).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\r"</literal>: <acronym>ASCII</acronym> <acronym>CR</acronym> character
      <literal>0x0D</literal>, a carriage return.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\0"</literal>: <acronym>ASCII</acronym> <acronym>NUL</acronym> character
      <literal>0x00</literal>, the NUL-byte.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\v"</literal>: <acronym>ASCII</acronym> <acronym>VT</acronym>
      character <literal>0x0B</literal>, a vertical tab.
     </simpara>
    </listitem>
   </itemizedlist>
'>

<!ENTITY strings.stripped.unicode '
 <itemizedlist xmlns="http://docbook.org/ns/docbook">
    <listitem>
     <simpara>
      <literal>" "</literal> (<acronym>Unicode</acronym> U+0020), an ordinary space.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\t"</literal> (<acronym>Unicode</acronym> U+0009), a tab.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\n"</literal> (<acronym>Unicode</acronym> U+000A), a new line (line feed).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\r"</literal> (<acronym>Unicode</acronym> U+000D), a carriage return.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\0"</literal> (<acronym>Unicode</acronym> U+0000), the NUL-byte.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\v"</literal> (<acronym>Unicode</acronym> U+000B), a vertical tab.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\f"</literal> (<acronym>Unicode</acronym> U+000C), a form feed.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\u00A0"</literal> (<acronym>Unicode</acronym> U+00A0), a NO-BREAK SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\u1680"</literal> (<acronym>Unicode</acronym> U+1680), a OGHAM SPACE MARK.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\u2000"</literal> (<acronym>Unicode</acronym> U+2000), a EN QUAD.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\u2001"</literal> (<acronym>Unicode</acronym> U+2001), a EM QUAD.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\u2002"</literal> (<acronym>Unicode</acronym> U+2002), a EN SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\u2003"</literal> (<acronym>Unicode</acronym> U+2003), a EM SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\u2004"</literal> (<acronym>Unicode</acronym> U+2004), a THREE-PER-EM SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\u2005"</literal> (<acronym>Unicode</acronym> U+2005), a FOUR-PER-EM SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>"\u2006"</literal> (<acronym>Unicode</acronym> U+2006), a SIX-PER-EM SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     <literal>"\u2007"</literal> (<acronym>Unicode</acronym> U+2007), a FIGURE SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     <literal>"\u2008"</literal> (<acronym>Unicode</acronym> U+2008), a PUNCTUATION SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     <literal>"\u2009"</literal> (<acronym>Unicode</acronym> U+2009), a THIN SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     <literal>"\u200A"</literal> (<acronym>Unicode</acronym> U+200A), a HAIR SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     <literal>"\u2028"</literal> (<acronym>Unicode</acronym> U+2028), a LINE SEPARATOR.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     <literal>"\u2029"</literal> (<acronym>Unicode</acronym> U+2029), a PARAGRAPH SEPARATOR.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     <literal>"\u202F"</literal> (<acronym>Unicode</acronym> U+202F), a NARROW NO-BREAK SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     <literal>"\u205F"</literal> (<acronym>Unicode</acronym> U+205F), a MEDIUM MATHEMATICAL SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     <literal>"\u3000"</literal> (<acronym>Unicode</acronym> U+3000), a IDEOGRAPHIC SPACE.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     <literal>"\u0085"</literal> (<acronym>Unicode</acronym> U+0085), a NEXT LINE (NEL).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     <literal>"\u180E"</literal> (<acronym>Unicode</acronym> U+180E), a MONGOLIAN VOWEL SEPARATOR.
     </simpara>
    </listitem>
   </itemizedlist>
'>

<!ENTITY strings.parameter.characters.optional '
 <simpara xmlns="http://docbook.org/ns/docbook">
  Optionally, the stripped characters can also be specified using
  the <parameter>characters</parameter> parameter.
  Simply list all characters that need to be stripped.
  With <literal>..</literal> it is possible to specify an incrementing range of characters.
 </simpara>
'>

<!ENTITY strings.parameter.unicode.optional '
 <simpara xmlns="http://docbook.org/ns/docbook">
  Optionally, the stripped characters can also be specified using
  the <parameter>characters</parameter> parameter.
  Simply list all characters that need to be stripped.
 </simpara>
'>

<!ENTITY strings.parameter.encoding '
 <simpara xmlns="http://docbook.org/ns/docbook">
  An optional argument defining the encoding used when converting characters.
 </simpara>

 <simpara xmlns="http://docbook.org/ns/docbook">
  If omitted, <parameter>encoding</parameter> defaults to the value of the
  <link linkend="ini.default-charset">default_charset</link> configuration
  option.
 </simpara>

 <simpara xmlns="http://docbook.org/ns/docbook">
  Although this argument is technically optional, you are highly encouraged to
  specify the correct value for your code
  if the <link linkend="ini.default-charset">default_charset</link>
  configuration option may be set incorrectly for the given input.
 </simpara>
'>

<!ENTITY strings.parameter.format '
<varlistentry xmlns="http://docbook.org/ns/docbook">
 <term><parameter>format</parameter></term>
 <listitem>
  <simpara>
   The format string is composed of zero or more directives:
   ordinary characters (excluding <literal>&#37;</literal>) that are
   copied directly to the result and <emphasis>conversion
   specifications</emphasis>, each of which results in fetching its
   own parameter.
  </simpara>

  <simpara>
   A conversion specification follows this prototype:
   <literal>&#37;[argnum$][flags][width][.precision]specifier</literal>.
  </simpara>

  <formalpara>
   <title>Argnum</title>
   <para>
    An integer followed by a dollar sign <literal>$</literal>,
    to specify which number argument to treat in the conversion.
   </para>
  </formalpara>

  <formalpara>
   <title>Flags</title>
   <para>
    <informaltable>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Flag</entry>
        <entry>&Description;</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry><literal>-</literal></entry>
        <entry>
         Left-justify within the given field width;
         Right justification is the default
        </entry>
       </row>
       <row>
        <entry><literal>+</literal></entry>
        <entry>
         Prefix positive numbers with a plus sign
         <literal>+</literal>; Default only negative
         are prefixed with a negative sign.
        </entry>
       </row>
       <row>
        <entry><literal> </literal>(space)</entry>
        <entry>
         Pads the result with spaces.
         This is the default.
        </entry>
       </row>
       <row>
        <entry><literal>0</literal></entry>
        <entry>
         Only left-pads numbers with zeros.
         With <literal>s</literal> specifiers this can
         also right-pad with zeros.
        </entry>
       </row>
       <row>
        <entry><literal>&apos;</literal>(char)</entry>
        <entry>
         Pads the result with the character (char).
        </entry>
       </row>
      </tbody>
     </tgroup>
    </informaltable>
   </para>
  </formalpara>

  <formalpara>
   <title>Width</title>
   <para>
    Either an integer that says how many characters (minimum)
    this conversion should result in, or <literal>*</literal>.
    If <literal>*</literal> is used, then the width is supplied
    as an additional integer value preceding the one formatted
    by the specifier.
   </para>
  </formalpara>

  <formalpara>
   <title>Precision</title>
   <para>
    A period <literal>.</literal> optionally followed by
    either an integer or <literal>*</literal>,
    whose meaning depends on the specifier:
    <itemizedlist>
     <listitem>
      <simpara>
       For <literal>e</literal>, <literal>E</literal>,
       <literal>f</literal> and <literal>F</literal>
       specifiers: this is the number of digits to be printed
       after the decimal point (by default, this is 6).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       For <literal>g</literal>, <literal>G</literal>,
       <literal>h</literal> and <literal>H</literal>
       specifiers: this is the maximum number of significant
       digits to be printed.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       For <literal>s</literal> specifier: it acts as a cutoff point,
       setting a maximum character limit to the string.
      </simpara>
     </listitem>
    </itemizedlist>
    <note>
     <simpara>
      If the period is specified without an explicit value for precision,
      0 is assumed. If <literal>*</literal> is used, the precision is
      supplied as an additional integer value preceding the one formatted
      by the specifier.
     </simpara>
    </note>
   </para>
  </formalpara>

  <para>
   <table>
    <title>Specifiers</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Specifier</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>&#37;</literal></entry>
       <entry>
        A literal percent character. No argument is required.
       </entry>
      </row>
      <row>
       <entry><literal>b</literal></entry>
       <entry>
        The argument is treated as an integer and presented
        as a binary number.
       </entry>
      </row>
      <row>
       <entry><literal>c</literal></entry>
       <entry>
        The argument is treated as an integer and presented
        as the character with that ASCII.
       </entry>
      </row>
      <row>
       <entry><literal>d</literal></entry>
       <entry>
        The argument is treated as an integer and presented
        as a (signed) decimal number.
       </entry>
      </row>
      <row>
       <entry><literal>e</literal></entry>
       <entry>
        The argument is treated as scientific notation (e.g. 1.2e+2).
       </entry>
      </row>
      <row>
       <entry><literal>E</literal></entry>
       <entry>
        Like the <literal>e</literal> specifier but uses
        uppercase letter (e.g. 1.2E+2).
       </entry>
      </row>
      <row>
       <entry><literal>f</literal></entry>
       <entry>
        The argument is treated as a float and presented
        as a floating-point number (locale aware).
       </entry>
      </row>
      <row>
       <entry><literal>F</literal></entry>
       <entry>
        The argument is treated as a float and presented
        as a floating-point number (non-locale aware).
       </entry>
      </row>
      <row>
       <entry><literal>g</literal></entry>
       <entry>
        <simpara>
         General format.
        </simpara>
        <simpara>
         Let P equal the precision if nonzero, 6 if the precision is omitted,
         or 1 if the precision is zero.
         Then, if a conversion with style E would have an exponent of X:
        </simpara>
        <simpara>
         If P > X ≥ −4, the conversion is with style f and precision P − (X + 1).
         Otherwise, the conversion is with style e and precision P − 1.
        </simpara>
       </entry>
      </row>
      <row>
       <entry><literal>G</literal></entry>
       <entry>
        Like the <literal>g</literal> specifier but uses
        <literal>E</literal> and <literal>f</literal>.
       </entry>
      </row>
      <row>
       <entry><literal>h</literal></entry>
       <entry>
        Like the <literal>g</literal> specifier but uses <literal>F</literal>.
        Available as of PHP 8.0.0.
       </entry>
      </row>
      <row>
       <entry><literal>H</literal></entry>
       <entry>
        Like the <literal>g</literal> specifier but uses
        <literal>E</literal> and <literal>F</literal>. Available as of PHP 8.0.0.
       </entry>
      </row>
      <row>
       <entry><literal>o</literal></entry>
       <entry>
        The argument is treated as an integer and presented
        as an octal number.
       </entry>
      </row>
      <row>
       <entry><literal>s</literal></entry>
       <entry>
        The argument is treated and presented as a string.
       </entry>
      </row>
      <row>
       <entry><literal>u</literal></entry>
       <entry>
        The argument is treated as an integer and presented
        as an unsigned decimal number.
       </entry>
      </row>
      <row>
       <entry><literal>x</literal></entry>
       <entry>
        The argument is treated as an integer and presented
        as a hexadecimal number (with lowercase letters).
       </entry>
      </row>
      <row>
       <entry><literal>X</literal></entry>
       <entry>
        The argument is treated as an integer and presented
        as a hexadecimal number (with uppercase letters).
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>

  <warning>
   <simpara>
    The <literal>c</literal> type specifier ignores padding and width.
   </simpara>
  </warning>

  <warning>
   <simpara>
    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.
   </simpara>
  </warning>

  <para>
   Variables will be co-erced to a suitable type for the specifier:
   <table>
    <title>Type Handling</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Type</entry>
       <entry>Specifiers</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><type>string</type></entry>
       <entry><literal>s</literal></entry>
      </row>
      <row>
       <entry><type>int</type></entry>
       <entry>
        <literal>d</literal>,
        <literal>u</literal>,
        <literal>c</literal>,
        <literal>o</literal>,
        <literal>x</literal>,
        <literal>X</literal>,
        <literal>b</literal>
       </entry>
      </row>
      <row>
       <entry><type>float</type></entry>
       <entry>
        <literal>e</literal>,
        <literal>E</literal>,
        <literal>f</literal>,
        <literal>F</literal>,
        <literal>g</literal>,
        <literal>G</literal>,
        <literal>h</literal>,
        <literal>H</literal>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </listitem>
</varlistentry>
'>

<!ENTITY strings.scanf.parameter.format '
<varlistentry xmlns="http://docbook.org/ns/docbook">
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       The interpreted format for <parameter>string</parameter>, which is
       described in the documentation for <function>sprintf</function> with
       following differences:
       <simplelist>
        <member>
         Function is not locale-aware.
        </member>
        <member>
         <literal>F</literal>, <literal>g</literal>, <literal>G</literal> and
         <literal>b</literal> are not supported.
        </member>
        <member>
         <literal>D</literal> stands for decimal number.
        </member>
        <member>
         <literal>i</literal> stands for integer with base detection.
        </member>
        <member>
         <literal>n</literal> stands for number of characters processed so far.
        </member>
        <member>
         <literal>s</literal> stops reading at any whitespace character.
        </member>
        <member>
         <literal>*</literal> instead of <literal>argnum$</literal> suppresses
         the assignment of this conversion specification.
        </member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
'>

<!ENTITY strings.parameter.needle.non-string '
 <simpara xmlns="http://docbook.org/ns/docbook">
  Prior to PHP 8.0.0, if <parameter>needle</parameter> is not a string, it is converted
  to an integer and applied as the ordinal value of a character.
  This behavior is deprecated as of PHP 7.3.0, and relying on it is highly
  discouraged. Depending on the intended behavior, the
  <parameter>needle</parameter> should either be explicitly cast to string,
  or an explicit call to <function>chr</function> should be performed.
 </simpara>
'>

<!ENTITY strings.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>needle</parameter> now accepts an empty string.
 </entry>
</row>'>

<!ENTITY strings.changelog.ascii-case-conversion '
 <row xmlns="http://docbook.org/ns/docbook">
  <entry>8.2.0</entry>
  <entry>
   Case conversion no longer depends on the locale set with
   <function>setlocale</function>. Only ASCII characters will be converted.
  </entry>
 </row>
'>

<!ENTITY strings.changelog.ascii-case-folding '
 <row xmlns="http://docbook.org/ns/docbook">
  <entry>8.2.0</entry>
  <entry>
   Case folding no longer depends on the locale set with
   <function>setlocale</function>. Only ASCII case folding will be done.
   Non-ASCII bytes will be compared by their byte value.
  </entry>
 </row>
'>

<!ENTITY strings.changelog.sprintf '
  <informaltable xmlns="http://docbook.org/ns/docbook">
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.0.0</entry>
      <entry>
       This function no longer returns &false; on failure.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Throw a <classname>ValueError</classname> if the number of arguments is zero;
       previously this function emitted a <constant>E_WARNING</constant> instead.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
       previously this function emitted a <constant>E_WARNING</constant> instead.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
       previously this function emitted a <constant>E_WARNING</constant> instead.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Throw a <classname>ArgumentCountError</classname> when less arguments are given than required;
       previously this function emitted a <constant>E_WARNING</constant> instead.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
'>

<!ENTITY strings.changelog.vsprintf '
  <informaltable xmlns="http://docbook.org/ns/docbook">
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.0.0</entry>
      <entry>
       This function no longer returns &false; on failure.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Throw a <classname>ValueError</classname> if the number of arguments is zero;
       previously this function emitted a <constant>E_WARNING</constant> instead.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
       previously this function emitted a <constant>E_WARNING</constant> instead.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;
       previously this function emitted a <constant>E_WARNING</constant> instead.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Throw a <classname>ValueError</classname> when less arguments are given than required;
       previously this function emitted a <constant>E_WARNING</constant> instead.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
'>

<!ENTITY strings.errors.sprintf '
  <simpara xmlns="http://docbook.org/ns/docbook">
   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
  </simpara>
  <simpara xmlns="http://docbook.org/ns/docbook">
   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>.
   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
  </simpara>
  <simpara xmlns="http://docbook.org/ns/docbook">
   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>.
   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
  </simpara>
  <simpara xmlns="http://docbook.org/ns/docbook">
   As of PHP 8.0.0, a <classname>ArgumentCountError</classname> is thrown when less arguments are given than required.
   Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
  </simpara>
'>

<!ENTITY strings.errors.vsprintf '
  <simpara xmlns="http://docbook.org/ns/docbook">
   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.
   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
  </simpara>
  <simpara xmlns="http://docbook.org/ns/docbook">
   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>.
   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
  </simpara>
  <simpara xmlns="http://docbook.org/ns/docbook">
   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>.
   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
  </simpara>
  <simpara xmlns="http://docbook.org/ns/docbook">
   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown when less arguments are given than required.
   Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.
  </simpara>
'>

<!ENTITY strings.comparison.return '
  <simpara xmlns="http://docbook.org/ns/docbook">
   Returns a value less than 0 if <parameter>string1</parameter>
   is less than <parameter>string2</parameter>; a value greater
   than 0 if <parameter>string1</parameter> is greater than
   <parameter>string2</parameter>, and <literal>0</literal> if they
   are equal.
   No particular meaning can be reliably inferred from the value aside
   from its sign.
  </simpara>
'>

<!-- csprng snippets -->
<!ENTITY csprng.sources '
<simpara xmlns="http://docbook.org/ns/docbook">
 The sources of randomness in the order of priority are as follows:
</simpara>
<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <listitem>
  <simpara>
   Linux: <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   FreeBSD &gt;= 12 (PHP &gt;= 7.3): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   Windows (PHP &gt;= 7.2): <link xlink:href="&url.csprng.cng-api;">CNG-API</link>
  </simpara>
  <simpara>
   Windows: <link xlink:href="&url.csprng.crypt-gen-random;">CryptGenRandom</link>
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   macOS (PHP &gt;= 8.2; &gt;= 8.1.9; &gt;= 8.0.22 if CCRandomGenerateBytes is available at compile time): CCRandomGenerateBytes()
  </simpara>
  <simpara>
   macOS (PHP &gt;= 8.1; &gt;= 8.0.2): arc4random_buf(), <filename>/dev/urandom</filename>
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   NetBSD &gt;= 7 (PHP &gt;= 7.1; &gt;= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   OpenBSD &gt;= 5.5 (PHP &gt;= 7.1; &gt;= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   DragonflyBSD (PHP &gt;= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   Solaris (PHP &gt;= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   Any combination of operating system and PHP version not previously mentioned: <filename>/dev/urandom</filename>
  </simpara>
 </listitem>
 <listitem>
  <simpara>
   If none of the sources are available or they all fail to generate
   randomness, then a <classname>Random\RandomException</classname>
   will be thrown.
  </simpara>
 </listitem>
</itemizedlist>
'>
<!ENTITY csprng.errors '
 <listitem xmlns="http://docbook.org/ns/docbook">
  <simpara>
   If an appropriate source of randomness cannot be found,
   a <classname>Random\RandomException</classname> will be thrown.
  </simpara>
 </listitem>
'>
<!ENTITY csprng.function.backport '
 <note xmlns="http://docbook.org/ns/docbook">
  <simpara>
   Although this function was added to PHP in PHP 7.0, a
   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.csprng.compat;">userland implementation</link>
   is available for PHP 5.2 to 5.6, inclusive.
  </simpara>
 </note>
'>

<!-- Random snippets -->
<!ENTITY random.engineErrors '
 <listitem xmlns="http://docbook.org/ns/docbook">
  <simpara>
   Any <classname>Throwable</classname>s thrown by the <methodname>Random\Engine::generate</methodname> method
   of the underlying <link linkend="random-randomizer.props.engine"><literal>Random\Randomizer::$engine</literal></link>.
  </simpara>
 </listitem>
'>

<!-- URI snippets -->
<!ENTITY uri.errors.invalidUriException '
  <simpara>
   If the resulting URI is invalid, a <exceptionname>Uri\InvalidUriException</exceptionname> is thrown.
  </simpara>
'>

<!ENTITY uri.errors.invalidUrlException '
  <simpara>
   If the resulting URL is invalid, a <exceptionname>Uri\WhatWg\InvalidUrlException</exceptionname> is thrown.
  </simpara>
'>

<!-- UOPZ snippets -->

<!ENTITY uopz.warn.removed.function-5-0-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
<emphasis>REMOVED</emphasis> in PECL uopz 5.0.0.</simpara></warning>'>

<!-- XML snippets -->
<!ENTITY xml.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
 <term><parameter>parser</parameter></term>
 <listitem>
  <simpara>
   The XML parser.
  </simpara>
 </listitem>
</varlistentry>'>

<!ENTITY xml.handler.description '<para xmlns="http://docbook.org/ns/docbook">
 If &null; is passed, the handler is reset to its default state.
 <warning>
  <simpara>
    An empty string will also reset the handler,
    however this is deprecated as of PHP 8.4.0.
  </simpara>
 </warning>
</para>
<simpara xmlns="http://docbook.org/ns/docbook">
 If <parameter>handler</parameter> is a <type>callable</type>,
 the callable is set as the handler.
</simpara>
<para xmlns="http://docbook.org/ns/docbook">
 If <parameter>handler</parameter> is a <type>string</type>,
 it can be the name of a method of an object set with
 <function>xml_set_object</function>.
 <warning>
  <simpara>
   This is deprecated as of PHP 8.4.0.
  </simpara>
 </warning>
</para>
<warning xmlns="http://docbook.org/ns/docbook">
 <simpara>
  As of PHP 8.4.0, the callable is checked to be valid while setting the handler,
  not when it is called.
  This means that <function>xml_set_object</function> must be called prior to
  setting a method string as the callback.
  However, as this behaviour is also deprecated as of PHP 8.4.0,
  using a proper <type>callable</type> for the method is recommended instead.
 </simpara>
</warning>
'>

<!ENTITY xml.handler.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
 <term><parameter>parser</parameter></term>
 <listitem>
  <simpara>
   The XML parser calling the handler.
  </simpara>
 </listitem>
</varlistentry>'>

<!ENTITY xml.changelog.handler-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.4.0</entry>
 <entry>
  Passing a non-<type>callable</type> <type>string</type> to
  <parameter>handler</parameter> is now deprecated,
  use a proper callable for methods, or &null; to reset the handler.
 </entry>
</row>
<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.4.0</entry>
 <entry>
  The validity of <parameter>handler</parameter> as a <type>callable</type>
  is now checked when setting the handler instead of checking when calling it.
 </entry>
</row>'>

<!ENTITY xml.changelog.parser-param '<row xmlns="http://docbook.org/ns/docbook">
 <entry>8.0.0</entry>
 <entry>
  <parameter>parser</parameter> expects an <classname>XMLParser</classname>
  instance now; previously, a valid <literal>xml</literal> <type>resource</type> was expected.
 </entry>
</row>'>

<!-- Migration Guide snippets -->
<!ENTITY migration56.openssl.peer-verification '
   <simpara xmlns="http://docbook.org/ns/docbook">
    All encrypted client streams now enable peer verification by default. By
    default, this will use OpenSSL&apos;s default CA bundle to verify the peer
    certificate. In most cases, no changes will need to be made to communicate
    with servers with valid SSL certificates, as distributors generally
    configure OpenSSL to use known good CA bundles.
   </simpara>

   <simpara xmlns="http://docbook.org/ns/docbook">
    The default CA bundle may be overridden on a global basis by setting
    either the openssl.cafile or openssl.capath configuration setting, or on a
    per request basis by using the
    <link linkend="context.ssl.cafile"><parameter>cafile</parameter></link> or
    <link linkend="context.ssl.capath"><parameter>capath</parameter></link>
    context options.
   </simpara>

   <simpara xmlns="http://docbook.org/ns/docbook">
    While not recommended in general, it is possible to disable peer
    certificate verification for a request by setting the
    <link linkend="context.ssl.verify-peer"><parameter>verify_peer</parameter></link>
    context option to &false;, and to disable peer name validation by setting
    the <link linkend="context.ssl.verify-peer-name"><parameter>verify_peer_name</parameter></link>
    context option to &false;.
   </simpara>
'>

<!-- Sodium -->
<!ENTITY sodium.changelog.aes256gcm-aarch64 '
  <informaltable xmlns="http://docbook.org/ns/docbook">
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.4.0</entry>
      <entry>
       This function is now also defined on aarch64.
       Previously it was only defined on x86 and x86_64.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
'>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: fen fdm=syntax fdl=2 si
vim: et tw=78
vi: ts=1 sw=1
-->