PHP: Documentation Tools

language-snippets.ent
187032b3ea20fa28f1c9f29ba38d06820428f849

...

@@ -18,21 +18,46 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been

highly discouraged.</simpara></warning>'>

<!-- Cautions -->

<!ENTITY caution.cryptographically-insecure '<caution xmlns="http://docbook.org/ns/docbook"><para>This function does not

generate cryptographically secure values, and should not be used for cryptographic purposes. If you need a

cryptographically secure value, consider using <function>random_int</function>, <function>random_bytes</function>, or

<function>openssl_random_pseudo_bytes</function> instead.</para></caution>'>

<!ENTITY caution.cryptographically-insecure '<caution xmlns="http://docbook.org/ns/docbook">

 <para>

  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.

 </para>

 <para>

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

 </para>

</caution>'>

<!ENTITY caution.mt19937-tiny-seed '<caution xmlns="http://docbook.org/ns/docbook">

 <para>

  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.

 </para>

 <para>

  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.

 </para>

 <para>

  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.

 </para>

</caution>'>

<!-- Notes -->

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

binary-safe.</simpara></note>'>

<!ENTITY note.locale-single-byte '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is locale-aware

and will handle input according to the currently set locale.  However, it only works on single-byte character sets.

If you need to use multibyte characters (most non-western-European languages) look at the

<link linkend="book.mbstring">multibyte</link> or <link linkend="book.intl">intl</link> extensions instead.</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>'>

...

@@ -208,6 +233,9 @@ the names of its functions and any other documentation surrounding this

208

233

extension may change without notice in a future release of PHP.

209

234

This extension should be used at your own risk.</simpara></warning>'>

210

235

236

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

237

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

238

211

239

<!ENTITY warn.deprecated.feature-5-3-0 '<warning

212

240

xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been

213

241

<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature

...

@@ -309,6 +337,10 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been

309

337

<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. Relying on this function

310

338

is highly discouraged.</simpara></warning>'>

311

339

340

<!ENTITY warn.feature.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook">

341

<simpara>This feature was <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara>

342

</warning>'>

343

312

344

<!ENTITY warn.deprecated.function-8-0-0 '<warning

313

345

xmlns="http://docbook.org/ns/docbook"><simpara>This function has been

314

346

<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0. Relying on this function

...

@@ -324,6 +356,26 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been

324

356

<emphasis>DEPRECATED</emphasis> as of PHP 8.2.0. Relying on this function

325

357

is highly discouraged.</simpara></warning>'>

326

358

359

<!ENTITY warn.deprecated.feature-8-3-0 '<warning

360

xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been

361

<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this feature

362

is highly discouraged.</simpara></warning>'>

363

364

<!ENTITY warn.deprecated.function-8-3-0 '<warning

365

xmlns="http://docbook.org/ns/docbook"><simpara>This function has been

366

<emphasis>DEPRECATED</emphasis> as of PHP 8.3.0. Relying on this function

367

is highly discouraged.</simpara></warning>'>

368

369

<!ENTITY warn.deprecated.feature-8-4-0 '<warning

370

xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been

371

<emphasis>DEPRECATED</emphasis> as of PHP 8.4.0. Relying on this feature

372

is highly discouraged.</simpara></warning>'>

373

374

<!ENTITY warn.deprecated.function-8-4-0 '<warning

375

xmlns="http://docbook.org/ns/docbook"><simpara>This function has been

376

<emphasis>DEPRECATED</emphasis> as of PHP 8.4.0. Relying on this function

377

is highly discouraged.</simpara></warning>'>

378

327

379

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

328

380

certainly be <emphasis xmlns="http://docbook.org/ns/docbook">removed</emphasis> in the future.'>

329

381

...

@@ -580,6 +632,16 @@ is highly discouraged.</simpara></warning>

580

632

581

633

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

582

634

635

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

636

637

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

638

639

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

640

641

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

642

643

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

644

583

645

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

584

646

585

647

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

...

@@ -665,6 +727,44 @@ use.</simpara></note>'>

665

727

 </varlistentry>

666

728

'>

667

729

730

<!ENTITY sort.callback.description '<para xmlns="http://docbook.org/ns/docbook">

731

 &return.callbacksort;

732

</para>

733

&callback.cmp;

734

<caution xmlns="http://docbook.org/ns/docbook">

735

 <para>

736

  Returning <emphasis>non-integer</emphasis> values from the comparison

737

  function, such as <type>float</type>, will result in an internal cast to

738

  <type>int</type> of the callback&apos;s return value. So values such as

739

  <literal>0.99</literal> and <literal>0.1</literal> will both be cast to an

740

  integer value of <literal>0</literal>, which will compare such values as equal.

741

 </para>

742

</caution>'>

743

744

<!ENTITY sort.callback.description.presort '<caution xmlns="http://docbook.org/ns/docbook">

745

 <para>

746

  The sorting callback must handle any value from any array in any order,

747

  regardless of the order they were originally provided.

748

  This is because each individual array is first sorted before being compared against other arrays.

749

750

  For example:

751

  <programlisting role="php">

752

<![CDATA[

753

<?php

754

$arrayA = ["string", 1];

755

$arrayB = [["value" => 1]];

756

// $item1 and $item2 can be any of "string", 1 or ["value" => 1]

757

$compareFunc = static function ($item1, $item2) {

758

    $value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);

759

    $value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);

760

    return $value1 <=> $value2;

761

};

762

?>

763

]]>

764

  </programlisting>

765

 </para>

766

</caution>'>

767

668

768

<!ENTITY ini.shorthandbytes '<simpara xmlns="http://docbook.org/ns/docbook">When an <type>int</type> is used, the

669

769

value is measured in bytes. Shorthand notation, as described

670

770

in <link linkend="faq.using.shorthandbytes">this FAQ</link>, may also be used.

...

@@ -699,11 +799,7 @@ files from the PHP folder into the Windows system directory also works

699

799

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

700

800

<!ENTITY style.procedural 'Procedural style'>

701

801

702

<!ENTITY resource '<link xmlns="http://docbook.org/ns/docbook" linkend="language.types.resource">resource</link>'>

703

704

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

705

706

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

802

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

707

803

708

804

<!ENTITY parameter.context 'Refer to the <link xmlns="http://docbook.org/ns/docbook" linkend="context">context</link>

709

805

section of the manual for a description of <literal xmlns="http://docbook.org/ns/docbook">contexts</literal>.'>

...

@@ -713,6 +809,13 @@ searched for within the <link xmlns="http://docbook.org/ns/docbook" linkend="ini

713

809

714

810

<!-- Returns -->

715

811

812

<!ENTITY return.type.true '<row xmlns="http://docbook.org/ns/docbook">

813

 <entry>8.2.0</entry>

814

 <entry>

815

  The return type is &true; now; previously, it was <type>bool</type>.

816

 </entry>

817

</row>'>

818

716

819

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

717

820

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

718

821

...

@@ -739,7 +842,25 @@ function.</simpara></warning>'>

739

842

 <entry>8.1.0</entry>

740

843

 <entry>

741

844

  Calling this function on &object;s is deprecated.

742

  Either use <function>get_mangled_object_vars</function> on the &object; first, or use <classname>ArrayIterator</classname>.

845

  Either convert the &object; to an &array; using <function>get_mangled_object_vars</function> first, or use the methods

846

  provided by a class that implements <interfacename>Iterator</interfacename>, such as <classname>ArrayIterator</classname>, instead.

847

 </entry>

848

</row>

849

<row xmlns="http://docbook.org/ns/docbook">

850

 <entry>7.4.0</entry>

851

 <entry>

852

  Instances of <link xmlns="http://docbook.org/ns/docbook" linkend="book.spl">SPL</link> classes are now treated like empty objects that have no properties instead of calling the <interfacename>Iterator</interfacename> method with the same name as this function.

853

 </entry>

854

</row>

855

'>

856

857

<!ENTITY standard.changelog.binary-safe-string-comparison '<row xmlns="http://docbook.org/ns/docbook">

858

 <entry>8.2.0</entry>

859

 <entry>

860

  This function is no longer guaranteed to return

861

  <code>strlen($string1) - strlen($string2)</code> when string lengths

862

  are not equal, but may now return <literal>-1</literal> or

863

  <literal>1</literal> instead.

743

864

 </entry>

744

865

</row>

745

866

'>

...

@@ -948,10 +1069,20 @@ purposes.</simpara></warning>'>

948

1069

 <entry>8.0.0</entry>

949

1070

 <entry>

950

1071

  <parameter>image</parameter> expects a <classname>GdImage</classname>

951

  instance now; previously, a <type>resource</type> was expected.

1072

  instance now; previously, a valid <literal>gd</literal> <type>resource</type> was expected.

952

1073

 </entry>

953

1074

</row>'>

954

1075

1076

<!-- CSV -->

1077

<!ENTITY warning.csv.escape-parameter '<warning xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"><simpara>

1078

 When <parameter>escape</parameter> is set to anything other than an empty string

1079

 (<literal>""</literal>) it can result in CSV that is not compliant with

1080

 <link xlink:href="&url.rfc;4180">RFC 4180</link> or unable to survive a roundtrip

1081

 through the PHP CSV functions. The default for <parameter>escape</parameter> is

1082

 <literal>"\\"</literal> so it is recommended to set it to the empty string explicitly.

1083

 The default value will change in a future version of PHP, no earlier than PHP 9.0.

1084

</simpara></warning>'>

1085

955

1086

<!-- DBM notes -->

956

1087

957

1088

<!ENTITY dbm.dbm-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

...

@@ -1007,6 +1138,16 @@ returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>

1007

1138

 </entry>

1008

1139

</row>'>

1009

1140

1141

<!-- dba notes -->

1142

<!ENTITY dba.parameter.dba 'A <classname xmlns="http://docbook.org/ns/docbook">Dba\Connection</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">dba_open</function> or <function xmlns="http://docbook.org/ns/docbook">dba_popen</function>.'>

1143

<!ENTITY dba.changelog.dba-object '<row xmlns="http://docbook.org/ns/docbook">

1144

 <entry>8.4.0</entry>

1145

 <entry>

1146

  The <parameter>dba</parameter> parameter expects a <classname>Dba\Connection</classname>

1147

  instance now; previously, a valid <literal>dba</literal> &resource; was expected.

1148

 </entry>

1149

</row>'>

1150

1010

1151

<!-- dbase notes -->

1011

1152

1012

1153

<!ENTITY dbase.type-conversion '<para xmlns="http://docbook.org/ns/docbook">

...

@@ -1081,7 +1222,7 @@ returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>

1081

1222

 <entry>8.1.0</entry>

1082

1223

 <entry>

1083

1224

  The <parameter>imap</parameter> parameter expects an <classname>IMAP\Connection</classname>

1084

  instance now; previously, a &resource; was expected.

1225

  instance now; previously, a valid <literal>imap</literal> &resource; was expected.

1085

1226

 </entry>

1086

1227

</row>'>

1087

1228

...

@@ -1156,7 +1297,7 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles

1156

1297

 <entry>8.1.0</entry>

1157

1298

 <entry>

1158

1299

  The <parameter>ldap</parameter> parameter expects an <classname>LDAP\Connection</classname>

1159

  instance now; previously, a &resource; was expected.

1300

  instance now; previously, a valid <literal>ldap link</literal> &resource; was expected.

1160

1301

 </entry>

1161

1302

</row>'>

1162

1303

...

@@ -1164,7 +1305,7 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles

1164

1305

 <entry>8.1.0</entry>

1165

1306

 <entry>

1166

1307

  The <parameter>entry</parameter> parameter expects an <classname>LDAP\ResultEntry</classname>

1167

  instance now; previously, a &resource; was expected.

1308

  instance now; previously, a valid <literal>ldap result entry</literal> &resource; was expected.

1168

1309

 </entry>

1169

1310

</row>'>

1170

1311

...

@@ -1172,7 +1313,7 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles

1172

1313

 <entry>8.1.0</entry>

1173

1314

 <entry>

1174

1315

  The <parameter>result</parameter> parameter expects an <classname>LDAP\Result</classname>

1175

  instance now; previously, a &resource; was expected.

1316

  instance now; previously, a valid <literal>ldap result</literal> &resource; was expected.

1176

1317

 </entry>

1177

1318

</row>'>

1178

1319

...

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

1250

1391

1251

1392

<!-- memcached notes -->

1252

1393

1394

<!ENTITY memcached.note.delete-time '<note xmlns="http://docbook.org/ns/docbook"><simpara>

1395

       As of memcached 1.3.0 (released 2009) this feature is no longer

1396

       supported. Passing a non-zero <parameter>time</parameter> will cause

1397

       the deletion to fail. <methodname>Memcached::getResultCode</methodname>

1398

       will return <constant>MEMCACHED_INVALID_ARGUMENTS</constant>.

1399

      </simpara></note>

1400

'>

1401

1253

1402

<!ENTITY memcached.parameter.expiration 'The expiration time, defaults to 0. See <link

1254

1403

 linkend="memcached.expiration" xmlns="http://docbook.org/ns/docbook">Expiration Times</link> for more info.'>

1255

1404

...

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

1263

1412

1264

1413

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

1265

1414

1415

<!ENTITY memcached.result.delete-multi '<para xmlns="http://docbook.org/ns/docbook">

1416

   Returns an array indexed by <parameter>keys</parameter>. Each element

1417

   is &true; if the corresponding key was deleted, or one of the

1418

   <constant>Memcached::RES_<replaceable>*</replaceable></constant> constants if the corresponding deletion

1419

   failed.

1420

   </para>

1421

  <para xmlns="http://docbook.org/ns/docbook">

1422

   The <methodname>Memcached::getResultCode</methodname> will return

1423

   the result code for the last executed delete operation, that is, the delete

1424

   operation for the last element of <parameter>keys</parameter>.

1425

  </para>

1426

'>

1427

1266

1428

<!-- password notes -->

1267

1429

1268

1430

<!ENTITY password.parameter.algo 'A <link xmlns="http://docbook.org/ns/docbook" linkend="password.constants">password algorithm constant</link> denoting the algorithm to use when hashing the password.'>

...

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

1295

1457

1296

1458

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

1297

1459

1460

<!-- RNP -->

1461

1462

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

1463

1464

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

1465

1466

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

1467

1298

1468

<!-- socket entities -->

1299

1469

1300

1470

<!ENTITY sockets.changelog.socket-param '<row xmlns="http://docbook.org/ns/docbook">

...

@@ -1331,6 +1501,49 @@ encoding value will be used.</para>'>

1331

1501

1332

1502

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

1333

1503

1504

<!ENTITY gearman.parameter.callback '<varlistentry xmlns="http://docbook.org/ns/docbook">

1505

 <term><parameter>callback</parameter></term>

1506

 <listitem>

1507

  <para>

1508

   A function or method to call.

1509

   It should return a valid <link linkend="gearman.constants">Gearman return value</link>.

1510

  </para>

1511

  <para>

1512

   If no return statement is present, it defaults to <constant>GEARMAN_SUCCESS</constant>.

1513

  </para>

1514

  <methodsynopsis>

1515

   <type>int</type><methodname><replaceable>callback</replaceable></methodname>

1516

   <methodparam><type>GearmanTask</type><parameter>task</parameter></methodparam>

1517

   <methodparam><type>mixed</type><parameter>context</parameter></methodparam>

1518

  </methodsynopsis>

1519

  <variablelist>

1520

   <varlistentry>

1521

    <term><parameter>task</parameter></term>

1522

    <listitem>

1523

     <para>

1524

      The task this callback is called for.

1525

     </para>

1526

    </listitem>

1527

   </varlistentry>

1528

   <varlistentry>

1529

    <term><parameter>context</parameter></term>

1530

    <listitem>

1531

     <para>

1532

      Whatever has been passed to <methodname>GearmanClient::addTask</methodname> (or equivalent method) as <parameter>context</parameter>.

1533

     </para>

1534

    </listitem>

1535

   </varlistentry>

1536

  </variablelist>

1537

 </listitem>

1538

</varlistentry>'>

1539

1540

<!ENTITY gearman.note.callback '<note xmlns="http://docbook.org/ns/docbook">

1541

 <para>

1542

  The callback will only be triggered for tasks that are added (e.g. by calling <methodname>GearmanClient::addTask</methodname>)

1543

  after calling this method.

1544

 </para>

1545

</note>'>

1546

1334

1547

<!-- Date and time entities -->

1335

1548

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

1336

1549

...

@@ -1401,7 +1614,9 @@ The function modifies this object.</para></listitem></varlistentry>'>

1401

1614

returned by <function>timezone_open</function></para></listitem></varlistentry>'>

1402

1615

1403

1616

<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the modified <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining&return.falseforfailure;.'>

1617

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

1404

1618

<!ENTITY date.datetimeimmutable.return.modifiedobjectorfalseforfailure 'Returns a new <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object with the modified data &return.falseforfailure;.'>

1619

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

1405

1620

1406

1621

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

1407

1622

...

@@ -1421,21 +1636,68 @@ returned by <function>timezone_open</function></para></listitem></varlistentry>'

1421

1636

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

1422

1637

<!ENTITY date.formats.parameter 'A date/time string. &date.formats;'>

1423

1638

1424

<!-- DomXml Notes -->

1425

<!ENTITY node.inserted 'This node will not show up in the document unless it

1426

is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">domnode_append_child</function>.'>

1427

1428

1429

1639

<!-- Dom Notes -->

1430

1640

<!ENTITY dom.node.inserted 'This node will not show up in the document unless

1431

1641

it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNode::appendChild</function>.'>

1432

1642

1433

<!ENTITY dom.allowstatic '<para xmlns="http://docbook.org/ns/docbook">Prior to PHP 8.0.0 this method

1434

<emphasis>could</emphasis> be called statically, but would issue an <constant>E_DEPRECATED</constant> error.

1435

As of PHP 8.0.0 calling this method statically throws an <classname>Error</classname> exception</para>'>

1436

1643

<!ENTITY dom.malformederror '<para xmlns="http://docbook.org/ns/docbook">While malformed HTML should load successfully, this function may generate <constant>E_WARNING</constant> errors when it encounters bad markup. <link linkend="function.libxml-use-internal-errors">libxml&apos;s error handling functions</link> may be used to handle these errors.</para>'>

1437

1644

<!ENTITY dom.note.utf8 '<note xmlns="http://docbook.org/ns/docbook"><para>The DOM extension uses UTF-8 encoding. Use <function>mb_convert_encoding</function>, <methodname>UConverter::transcode</methodname>, or <function>iconv</function> to handle other encodings.</para></note>'>

1645

<!ENTITY dom.note.modern.utf8 '<note xmlns="http://docbook.org/ns/docbook">

1646

 <simpara>

1647

  The DOM extension uses UTF-8 encoding when working with methods or properties.

1648

  The parser methods auto-detect the encoding or allow the caller to specify an encoding.

1649

 </simpara>

1650

</note>'>

1438

1651

<!ENTITY dom.note.json '<note xmlns="http://docbook.org/ns/docbook"><para>When using <function>json_encode</function> on a <classname>DOMDocument</classname> object the result will be that of encoding an empty object.</para></note>'>

1652

<!ENTITY dom.domdocument.html5 '<warning xmlns="http://docbook.org/ns/docbook">

1653

 <simpara>

1654

  Use <classname>Dom\HTMLDocument</classname> to parse and process modern HTML

1655

  instead of <classname>DOMDocument</classname>.

1656

 </simpara>

1657

 <simpara>

1658

  This function parses the input using an HTML 4 parser. The parsing rules

1659

  of HTML 5, which is what modern web browsers use, are different. Depending

1660

  on the input this might result in a different DOM structure. Therefore

1661

  this function cannot be safely used for sanitizing HTML.

1662

 </simpara>

1663

 <simpara>

1664

  The behavior when parsing HTML can depend on the version of

1665

  <literal>libxml</literal> that is being used, particularly with regards to

1666

  edge conditions and error handling.

1667

  For parsing that conforms to the HTML5 specification,

1668

  use <methodname>Dom\HTMLDocument::createFromString</methodname> or

1669

  <methodname>Dom\HTMLDocument::createFromFile</methodname>, added in PHP 8.4.

1670

 </simpara>

1671

 <simpara>

1672

  As an example, some HTML elements will implicitly close a parent element

1673

  when encountered. The rules for automatically closing parent elements

1674

  differ between HTML 4 and HTML 5 and thus the resulting DOM structure that

1675

  <classname>DOMDocument</classname> sees might be different from the DOM

1676

  structure a web browser sees, possibly allowing an attacker to break the

1677

  resulting HTML.

1678

 </simpara>

1679

</warning>'>

1680

<!ENTITY dom.tokenlist.errors '<itemizedlist xmlns="http://docbook.org/ns/docbook">

1681

 <listitem>

1682

  <simpara>

1683

   Throws a <exceptionname>ValueError</exceptionname> if

1684

   a token contains any null bytes.

1685

  </simpara>

1686

 </listitem>

1687

 <listitem>

1688

  <simpara>

1689

   Throws a <exceptionname>Dom\DOMException</exceptionname> with code

1690

   <constant>Dom\SYNTAX_ERR</constant> if a token is the empty string.

1691

  </simpara>

1692

 </listitem>

1693

 <listitem>

1694

  <simpara>

1695

   Throws a <exceptionname>Dom\DOMException</exceptionname> with code

1696

   <constant>Dom\INVALID_CHARACTER_ERR</constant> if a token contains any

1697

   ASCII whitespace.

1698

  </simpara>

1699

 </listitem>

1700

</itemizedlist>'>

1439

1701

1440

1702

1441

1703

...

@@ -1473,6 +1735,128 @@ As of PHP 8.0.0 calling this method statically throws an <classname>Error</class

1473

1735

</books>

1474

1736

]]></programlisting>'>

1475

1737

1738

<!-- Dom entities -->

1739

<!ENTITY dom.parameter.options '<para xmlns="http://docbook.org/ns/docbook">

1740

  <link linkend="language.operators.bitwise">Bitwise <literal>OR</literal></link>

1741

  of the <link linkend="libxml.constants">libxml option constants</link>.

1742

</para>'>

1743

1744

<!ENTITY dom.parameter.compliant.options '&dom.parameter.options;

1745

 <simpara xmlns="http://docbook.org/ns/docbook">

1746

  It is also possible to pass <constant>Dom\HTML_NO_DEFAULT_NS</constant>

1747

  to disable the use of the HTML namespace and the template element.

1748

  This should only be used if the implications are properly understood.

1749

</simpara>'>

1750

1751

<!ENTITY dom.parameter.compliant.encoding '<simpara xmlns="http://docbook.org/ns/docbook">

1752

 The encoding that the document was created in.

1753

 If not provided, it will attempt to determine the encoding that is most likely used.

1754

</simpara>'>

1755

1756

<!ENTITY dom.parser.compliant.note.whitespace '<refsect1 role="notes" xmlns="http://docbook.org/ns/docbook">

1757

 &reftitle.notes;

1758

 <note>

1759

  <simpara>

1760

   Whitespace in the <literal>html</literal> and <literal>head</literal> tags

1761

   is not considered significant and may lose formatting.

1762

  </simpara>

1763

 </note>

1764

</refsect1>'>

1765

1766

<!ENTITY dom.parameters.register_node_ns '<varlistentry xmlns="http://docbook.org/ns/docbook">

1767

 <term><parameter>registerNodeNS</parameter></term>

1768

 <listitem>

1769

  <para>

1770

   Whether to automatically register the in-scope namespace prefixes of the context node to the <classname>DOMXPath</classname> object.

1771

   This can be used to avoid needing to call <methodname>DOMXPath::registerNamespace</methodname> manually for each in-scope namespaces.

1772

   When a namespace prefix conflict exists, only the nearest descendant namespace prefix is registered.

1773

  </para>

1774

 </listitem>

1775

</varlistentry>'>

1776

1777

<!ENTITY dom.parameters.serialize.options '<simpara xmlns="http://docbook.org/ns/docbook">

1778

 Additional Options.

1779

 The <constant>LIBXML_NOEMPTYTAG</constant>

1780

 and <constant>LIBXML_NOXMLDECL</constant> options are supported.

1781

 Prior to PHP 8.3.0, only the <constant>LIBXML_NOEMPTYTAG</constant>

1782

 option is supported.

1783

</simpara>'>

1784

1785

<!ENTITY dom.errors.hierarchy.parent '<varlistentry xmlns="http://docbook.org/ns/docbook">

1786

 <term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>

1787

  <listitem>

1788

  <para>

1789

    Raised if the parent is of a type that does not allow children of the

1790

    type of one of the passed <parameter>nodes</parameter>, or if the node to

1791

    put in is one of this node&#39;s ancestors or this node itself.

1792

  </para>

1793

 </listitem>

1794

</varlistentry>'>

1795

1796

<!ENTITY dom.errors.hierarchy.self '<varlistentry xmlns="http://docbook.org/ns/docbook">

1797

 <term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>

1798

  <listitem>

1799

  <para>

1800

    Raised if this node is of a type that does not allow children of the

1801

    type of one of the passed <parameter>nodes</parameter>, or if the node to

1802

    put in is one of this node&#39;s ancestors or this node itself.

1803

  </para>

1804

 </listitem>

1805

</varlistentry>'>

1806

1807

<!ENTITY dom.errors.wrong_document '<varlistentry xmlns="http://docbook.org/ns/docbook">

1808

 <term><constant>DOM_WRONG_DOCUMENT_ERR</constant></term>

1809

  <listitem>

1810

  <para>

1811

    Raised if one of the passed <parameter>nodes</parameter> was created from a different

1812

    document than the one that created this node.

1813

  </para>

1814

 </listitem>

1815

</varlistentry>'>

1816

1817

<!ENTITY dom.errors.compliant.wrong_document '<listitem xmlns="http://docbook.org/ns/docbook">

1818

 <simpara>

1819

  Throws a <exceptionname>Dom\DOMException</exceptionname> with code

1820

  <constant>Dom\WRONG_DOCUMENT_ERR</constant> if <parameter>node</parameter>

1821

  is from another document.

1822

 </simpara>

1823

</listitem>'>

1824

1825

<!ENTITY dom.errors.compliant.common '<listitem xmlns="http://docbook.org/ns/docbook">

1826

 <simpara>

1827

  Throws a <exceptionname>ValueError</exceptionname> if

1828

  <parameter>options</parameter> contains an invalid option.

1829

 </simpara>

1830

</listitem>

1831

<listitem>

1832

 <simpara>

1833

  Throws a <exceptionname>ValueError</exceptionname> if

1834

  <parameter>overrideEncoding</parameter> is an unknown encoding.

1835

 </simpara>

1836

</listitem>'>

1837

1838

<!ENTITY dom.changelog.previous_hierarchy_exception 'Previously this threw a

1839

 <classname xmlns="http://docbook.org/ns/docbook">DOMException</classname> with code

1840

 <constant xmlns="http://docbook.org/ns/docbook">DOM_HIERARCHY_REQUEST_ERR</constant>.'>

1841

1842

<!ENTITY dom.c14n.xpath_array '<listitem xmlns="http://docbook.org/ns/docbook">

1843

  <para>

1844

   An array of XPaths to filter the nodes by.

1845

   Each entry in this array is an associative array with:

1846

   <itemizedlist>

1847

    <listitem>

1848

     <simpara>

1849

      A required <literal>query</literal> key containing the XPath expression as a string.

1850

     </simpara>

1851

    </listitem>

1852

    <listitem>

1853

     <simpara>

1854

      An optional <literal>namespaces</literal> key containing an array that maps namespace prefixes (keys) to namespace URIs (values).

1855

     </simpara>

1856

    </listitem>

1857

   </itemizedlist>

1858

  </para>

1859

 </listitem>'>

1476

1860

1477

1861

<!-- FileSystem entities -->

1478

1862

<!ENTITY fs.emits.warning.on.failure '<para xmlns="http://docbook.org/ns/docbook">

...

@@ -1512,9 +1896,15 @@ that is typically created using <function>fopen</function>.</para>'>

1512

1896

<!ENTITY haru.error '<para xmlns="http://docbook.org/ns/docbook">Throws a <classname>HaruException</classname> on error.</para>'>

1513

1897

1514

1898

<!-- ODBC -->

1515

<!ENTITY odbc.connection.id '<para xmlns="http://docbook.org/ns/docbook">The ODBC connection identifier,

1899

<!ENTITY odbc.connection.id '<para xmlns="http://docbook.org/ns/docbook">The ODBC connection object,

1516

1900

see <function>odbc_connect</function> for details.</para>'>

1517

1901

1902

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

1903

1904

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

1905

1906

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

1907

1518

1908

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

1519

1909

1520

1910

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

...

@@ -1525,6 +1915,66 @@ and <literal xmlns="http://docbook.org/ns/docbook">_</literal> to match a single

1525

1915

1526

1916

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

1527

1917

1918

<!ENTITY odbc.changelog.connection-param '<row xmlns="http://docbook.org/ns/docbook">

1919

 <entry>8.4.0</entry>

1920

 <entry>

1921

  <parameter>odbc</parameter> expects an <classname>Odbc\Connection</classname>

1922

  instance now; previously, a <type>resource</type> was expected.

1923

 </entry>

1924

</row>'>

1925

1926

<!ENTITY odbc.changelog.connection-return '&odbc.changelog.connection-param;

1927

 <row xmlns="http://docbook.org/ns/docbook">

1928

  <entry>8.4.0</entry>

1929

  <entry>

1930

   This function returns a <classname>Odbc\Connection</classname> instance now;

1931

   previously, a <type>resource</type> was returned.

1932

  </entry>

1933

 </row>'>

1934

1935

<!ENTITY odbc.changelog.credential-params '<row xmlns="http://docbook.org/ns/docbook">

1936

  <entry>8.4.0</entry>

1937

  <entry>

1938

   <parameter>user</parameter> and <parameter>password</parameter> are now nullable,

1939

   they are now also optional and default to &null;.

1940

  </entry>

1941

 </row>

1942

 <row xmlns="http://docbook.org/ns/docbook">

1943

  <entry>8.4.0</entry>

1944

  <entry>

1945

   Previously, using an empty string for <parameter>password</parameter> would not include

1946

   <literal>pwd</literal> in the generated connection string for <parameter>dsn</parameter>.

1947

   It is now generated to include a <literal>pwd</literal> which has an empty string as its value.

1948

   To restore the previous behaviour <parameter>password</parameter> can now be set to &null;.

1949

  </entry>

1950

 </row>

1951

 <row xmlns="http://docbook.org/ns/docbook">

1952

  <entry>8.4.0</entry>

1953

  <entry>

1954

   Previously, if <parameter>dsn</parameter> contained <literal>uid</literal> or <literal>pwd</literal>

1955

   both <parameter>user</parameter> and <parameter>password</parameter> parameters were ignored.

1956

   Now <parameter>user</parameter> is only ignored if <parameter>dsn</parameter> contains

1957

   <literal>uid</literal>, and <parameter>password</parameter>  is only ignored if

1958

   <parameter>dsn</parameter> contains <literal>pwd</literal>.

1959

  </entry>

1960

 </row>'>

1961

1962

<!ENTITY odbc.changelog.result-param '<row xmlns="http://docbook.org/ns/docbook">

1963

 <entry>8.4.0</entry>

1964

 <entry>

1965

  <parameter>statement</parameter> expects an <classname>Odbc\Result</classname>

1966

  instance now; previously, a <type>resource</type> was expected.

1967

 </entry>

1968

</row>'>

1969

1970

<!ENTITY odbc.changelog.result-return '<row xmlns="http://docbook.org/ns/docbook">

1971

 <entry>8.4.0</entry>

1972

 <entry>

1973

  This function returns an <classname>Odbc\Result</classname>

1974

  instance now; previously, a <type>resource</type> was returned.

1975

 </entry>

1976

</row>'>

1977

1528

1978

<!-- OAUTH -->

1529

1979

<!ENTITY oauth.callback.error 'Emits an <constant xmlns="http://docbook.org/ns/docbook">E_ERROR</constant> level

1530

1980

error if the callback function cannot be called, or was not specified.'>

...

@@ -1657,23 +2107,6 @@ call to <function>pcntl_waitpid</function>.</para>'>

1657

2107

is printed or viewed but it will show up if the document is converted to

1658

2108

pdf by either Acrobat Distiller™ or Ghostview.</para>'>

1659

2109

1660

<!-- Notes for safe-mode limited functions: -->

1661

1662

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

1663

<!ENTITY note.sm.disabled '<note xmlns="http://docbook.org/ns/docbook"><simpara>&sm.disabled;</simpara></note>'>

1664

1665

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

1666

<!ENTITY note.sm.uidcheck '<note xmlns="http://docbook.org/ns/docbook"><simpara>When <link

1667

linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether

1668

the files or directories being operated upon have the same UID (owner) as the

1669

script that is being executed.</simpara></note>'>

1670

1671

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

1672

<!ENTITY note.sm.uidcheck.dir '<note xmlns="http://docbook.org/ns/docbook"><simpara>When <link

1673

linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether

1674

the directory in which the script is operating has the same UID (owner) as the

1675

script that is being executed.</simpara></note>'>

1676

1677

2110

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

1678

2111

linkend="ini.open-basedir">open_basedir</link>.</para></note>'>

1679

2112

...

@@ -1684,35 +2117,6 @@ language construct and not a function, it cannot be called using

1684

2117

or <link linkend="functions.named-arguments">named arguments</link>.</simpara>

1685

2118

</note>'>

1686

2119

1687

<!-- Common pieces in features/safe-mode.xml

1688

     Jade doesn't allow in-line entities, so I put them here... Though they

1689

     should have been inline in safe-mode.xml -->

1690

1691

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

1692

<!ENTITY sm.uidcheck 'Checks whether the files or directories being operated

1693

upon have the same UID (owner) as the script that is being executed.'>

1694

1695

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

1696

<!ENTITY warn.sm.exec '<warning xmlns="http://docbook.org/ns/docbook"><simpara>With <link linkend="features.safe-mode">safe mode</link> enabled,

1697

the command string is escaped with <function>escapeshellcmd</function>. Thus,

1698

<literal>echo y | echo x</literal> becomes <literal>echo y \| echo x</literal>.</simpara></warning>'>

1699

1700

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

1701

<!ENTITY note.exec-path '<note xmlns="http://docbook.org/ns/docbook"><simpara>When

1702

<link linkend="features.safe-mode">safe mode</link> is enabled, you can only

1703

execute files within the <link linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.

1704

For practical reasons, it is currently not allowed to have <literal>..</literal>

1705

components in the path to the executable.</simpara></note>'>

1706

1707

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

1708

<!ENTITY sm.uidcheck.dir 'Checks whether the directory in which

1709

the script is operating has the same UID (owner) as the script that is being

1710

executed.'>

1711

1712

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

1713

<!ENTITY sm.disabled 'This function is disabled when PHP is running in <link xmlns="http://docbook.org/ns/docbook"

1714

linkend="features.safe-mode">safe mode</link>.'>

1715

1716

2120

<!-- Common pieces in partintro-sections -->

1717

2121

<!ENTITY no.config '<para xmlns="http://docbook.org/ns/docbook">This extension has no configuration directives defined in &php.ini;.</para>'>

1718

2122

<!ENTITY no.resource '<para xmlns="http://docbook.org/ns/docbook">This extension has no resource types defined.</para>'>

...

@@ -1733,7 +2137,7 @@ The behaviour of these functions is affected by settings in &php.ini;.

1733

2137

</simpara>'>

1734

2138

1735

2139

<!ENTITY ini.php.constants 'For further details and definitions of the

1736

PHP_INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>

2140

INI_* modes, see the <xref xmlns="http://docbook.org/ns/docbook" linkend="configuration.changes.modes"/>.'>

1737

2141

1738

2142

<!-- Used in reference/$extname/constants.xml -->

1739

2143

<!ENTITY extension.constants '<simpara xmlns="http://docbook.org/ns/docbook">

...

@@ -1754,9 +2158,6 @@ will only be available when the extension has either

1754

2158

been compiled into PHP or dynamically loaded at runtime.

1755

2159

</simpara>'>

1756

2160

1757

<!ENTITY note.extension.php5 '<note xmlns="http://docbook.org/ns/docbook"><simpara>

1758

This extension requires PHP 5.</simpara></note>'>

1759

1760

2161

<!-- PDO entities -->

1761

2162

<!ENTITY pdo.driver-constants '<simpara xmlns="http://docbook.org/ns/docbook">The constants below are defined by

1762

2163

this driver, and will only be available when the extension has been either

...

@@ -1769,12 +2170,21 @@ driver, if your code can run against multiple drivers.</simpara>'>

1769

2170

1770

2171

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

1771

2172

2173

<!-- PDO errors -->

2174

2175

<!ENTITY pdo.errors '<para xmlns="http://docbook.org/ns/docbook">

2176

Emits an error with level <constant>E_WARNING</constant> if the attribute <constant>PDO::ATTR_ERRMODE</constant> is set

2177

to <constant>PDO::ERRMODE_WARNING</constant>.

2178

</para>

2179

<para xmlns="http://docbook.org/ns/docbook">

2180

Throws a <classname>PDOException</classname> if the attribute <constant>PDO::ATTR_ERRMODE</constant>

2181

is set to <constant>PDO::ERRMODE_EXCEPTION</constant>.

2182

</para>'>

2183

1772

2184

<!-- PECL entities -->

1773

<!ENTITY pecl.moved 'This <link xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> extension

1774

is not bundled with PHP.'>

2185

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

1775

2186

1776

<!ENTITY pecl.bundled 'This <link xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> extension

1777

is bundled with PHP.'>

2187

<!ENTITY pecl.bundled 'This &link.pecl; extension is bundled with PHP.'>

1778

2188

1779

2189

<!ENTITY pecl.info 'Information for installing this PECL extension may be

1780

2190

found in the manual chapter titled <link xmlns="http://docbook.org/ns/docbook" linkend="install.pecl">Installation

...

@@ -1800,9 +2210,12 @@ for this <acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension

1800

2210

1801

2211

<!ENTITY pecl.windows.download.unbundled '&pecl.windows.download;'>

1802

2212

1803

<!ENTITY pecl.moved-ver 'This extension has been moved to the

1804

<link xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> repository and is no longer bundled with

1805

PHP as of PHP '>

2213

<!ENTITY pecl.moved-ver 'This extension has been moved to the &link.pecl;

2214

repository and is no longer bundled with PHP as of PHP '>

2215

2216

<!ENTITY warn.pecl.unmaintained '<warning xmlns="http://docbook.org/ns/docbook">

2217

 <simpara>This extension is <emphasis>unmaintained</emphasis>.</simpara>

2218

</warning>'>

1806

2219

1807

2220

<!-- PGSQL entities -->

1808

2221

...

@@ -1877,22 +2290,6 @@ extensions in order to use these functions.</simpara>'>

1877

2290

1878

2291

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

1879

2292

1880

<!-- APD Notes -->

1881

<!ENTITY apd.debug-level.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

1882

<parameter>debug_level</parameter></term><listitem><para>An integer which is formed by adding

1883

together the <literal>XXX_TRACE</literal> constants.</para><para>It is not recommended

1884

to use <constant>MEMORY_TRACE</constant>. It is very slow and does not appear to be accurate.

1885

<constant>ASSIGNMENT_TRACE</constant> is not implemented yet.</para><para>To turn on all

1886

functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the value 99</para>

1887

</listitem></varlistentry>'>

1888

1889

<!-- BCMath Notes -->

1890

<!ENTITY bc.scale.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

1891

<parameter>scale</parameter></term><listitem><para>This optional parameter is used to set the number

1892

of digits after the decimal place in the result. If omitted, it will default to the scale set

1893

globally with the <function>bcscale</function> function, or fallback to <literal>0</literal> if

1894

this has not been set.</para></listitem></varlistentry>'>

1895

1896

2293

<!-- CTYPE Notes -->

1897

2294

<!ENTITY note.ctype.parameter.integer '<note xmlns="http://docbook.org/ns/docbook"><para>

1898

2295

If an <type>int</type> between -128 and 255 inclusive is provided, it is interpreted as

...

@@ -1920,7 +2317,12 @@ or an explicit call to <function>chr</function> should be made.</para></warning>

1920

2317

1921

2318

<!-- GMP Notes -->

1922

2319

<!ENTITY gmp.return 'A <classname xmlns="http://docbook.org/ns/docbook">GMP</classname> object.'>

1923

<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">A <classname>GMP</classname> object, an &integer; or a numeric &string;.</para>'>

2320

<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">

2321

 A <classname>GMP</classname> object, an &integer;,

2322

 or a &string; that can be interpreted as a number following the same logic

2323

 as if the string was used in <function>gmp_init</function> with automatic

2324

 base detection (i.e. when <parameter>base</parameter> is equal to 0).

2325

</para>'>

1924

2326

1925

2327

<!-- MySQLi Notes -->

1926

2328

<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

...

@@ -1951,6 +2353,10 @@ prepared statements</link> should be used instead. Alternatively, the

1951

2353

data must be properly formatted and all strings must be escaped using

1952

2354

the <function>mysqli_real_escape_string</function>

1953

2355

function.</para></warning>'>

2356

<!ENTITY mysqli.conditionalexception '<para xmlns="http://docbook.org/ns/docbook">

2357

If mysqli error reporting is enabled (<constant>MYSQLI_REPORT_ERROR</constant>) and the requested operation fails,

2358

a warning is generated. If, in addition, the mode is set to <constant>MYSQLI_REPORT_STRICT</constant>,

2359

a <classname>mysqli_sql_exception</classname> is thrown instead.</para>'>

1954

2360

1955

2361

<!-- Notes for PCRE -->

1956

2362

<!ENTITY pcre.pattern.warning '<para xmlns="http://docbook.org/ns/docbook">

...

@@ -2009,25 +2415,6 @@ are <emphasis>case-sensitive</emphasis>.</simpara></note>'>

2009

2415

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

2010

2416

the PHP &null; value.</simpara></note>'>

2011

2417

2012

<!-- MSQL Notes -->

2013

<!-- The msql.*.description entities are used in the parameters refsect1 -->

2014

<!ENTITY msql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

2015

<parameter>link_identifier</parameter></term><listitem><para>The mSQL connection.

2016

If not specified, the last link opened by <function>msql_connect</function>

2017

is assumed. If no such link is found, the function will try to establish a

2018

link as if <function>msql_connect</function> was called, and use it.

2019

</para></listitem></varlistentry>'>

2020

2021

<!ENTITY msql.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

2022

<parameter>result</parameter></term><listitem><para>The result <type>resource</type> that

2023

is being evaluated. This result comes from a call to

2024

<function>msql_query</function>.</para></listitem></varlistentry>'>

2025

2026

<!ENTITY msql.field-offset.req.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

2027

<parameter>field_offset</parameter></term><listitem><para>The numerical field offset. The

2028

<parameter>field_offset</parameter> starts at <literal>1</literal>.</para></listitem></varlistentry>'>

2029

2030

2031

2418

<!-- MySQL Notes -->

2032

2419

<!-- The mysql.*.description entities are used in the parameters refsect1 -->

2033

2420

<!ENTITY mysql.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

...

@@ -2095,40 +2482,6 @@ This will immediately return resources to PHP and MySQL, which can

2095

2482

improve performance. For related information, see

2096

2483

<link linkend="language.types.resource.self-destruct">freeing resources</link></para>'>

2097

2484

2098

<!-- Sybase Notes -->

2099

<!ENTITY sybase.ct.only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when

2100

using the CT library interface to Sybase, and not with the DB library.

2101

</simpara></note>'>

2102

2103

<!ENTITY sybase.db.only '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is only available when

2104

using the DB library interface to Sybase, and not with the CT library.</simpara></note>'>

2105

2106

<!ENTITY sybase.linkid.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

2107

<parameter>link_identifier</parameter></term><listitem><para>The Sybase connection. If the

2108

link identifier is not specified, the last link opened by

2109

<function>sybase_connect</function> is assumed. If no such link is found, it

2110

will try to create one as if <function>sybase_connect</function> was called

2111

with no arguments. If no connection is found or established, an

2112

<constant>E_WARNING</constant> level error is generated.</para></listitem>

2113

</varlistentry>'>

2114

2115

<!-- CPDF Notes -->

2116

<!ENTITY cpdf.ul '<para xmlns="http://docbook.org/ns/docbook">The optional parameter <parameter>mode</parameter>

2117

determines the unit length. If it is <literal>0</literal> or omitted, the

2118

default unit as specified for the page is used. In other cases, the coordinates

2119

are measured in postscript points, disregarding the current unit.</para>'>

2120

2121

<!ENTITY cpdf.mode.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

2122

<parameter>mode</parameter></term><listitem><para>The optional parameter <parameter>mode</parameter>

2123

determines the unit length. If it is <literal>0</literal> or omitted, the

2124

default unit as specified for the page is used. In other cases, the coordinates

2125

are measured in postscript points, disregarding the current unit.</para>

2126

</listitem></varlistentry>'>

2127

2128

<!ENTITY cpdf.pdf-document.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

2129

<parameter>pdf_document</parameter></term><listitem><para>The document handle, returned by

2130

<function>cpdf_open</function>.</para></listitem></varlistentry>'>

2131

2132

2485

<!-- Xattr entities -->

2133

2486

<!ENTITY xattr.namespace '<para xmlns="http://docbook.org/ns/docbook">Extended attributes have two different namespaces: user

2134

2487

and root. The user namespace is available to all users, while the root namespace

...

@@ -2141,9 +2494,6 @@ namespace  by default, but this can be changed with the

2141

2494

(e.g. <literal>fe80::1</literal>), you must enclose the IP in square

2142

2495

brackets—for example, <literal>tcp://[fe80::1]:80</literal>.</simpara></note>'>

2143

2496

2144

<!ENTITY ipv6.php5 '<note xmlns="http://docbook.org/ns/docbook"><simpara>IPv6 Support was added in PHP 5.0.0.

2145

</simpara></note>'>

2146

2147

2497

<!-- Notes for tidy -->

2148

2498

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

2149

2499

...

@@ -2168,6 +2518,15 @@ threaded MPM in production with Apache 2. Use the prefork MPM, which is

2168

2518

the default MPM with Apache 2.0 and 2.2.

2169

2519

For information on why, read the related FAQ entry on using

2170

2520

<link linkend="faq.installation.apache2">Apache2 with a threaded MPM</link></para></warning>'>

2521

<!ENTITY warn.install.third-party-support '<warning xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

2522

 <para>

2523

  Builds from third-parties are considered unofficial and not directly

2524

  supported by the PHP project. Any bugs encountered should be reported to the

2525

  provider of those unofficial builds unless they can be reproduced using the

2526

  builds from <link xlink:href="&url.php.downloads;">the official download

2527

  area</link>.

2528

 </para>

2529

</warning>'>

2171

2530

2172

2531

<!ENTITY note.apache.slashes '<note xmlns="http://docbook.org/ns/docbook"><simpara>Remember that when adding

2173

2532

path values in the Apache configuration files on Windows, all backslashes

...

@@ -2178,10 +2537,9 @@ slash may also be necessary for directories.</simpara></note>'>

2178

2537

<!-- Snippets and titles for the contributors section -->

2179

2538

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

2180

2539

2181

<!ENTITY Credit.Introduction '<para xmlns="http://docbook.org/ns/docbook"> We highlight the currently most active

2182

people on the front page of the manual, but there are many more contributors who

2540

<!ENTITY Credit.Introduction '<para xmlns="http://docbook.org/ns/docbook"> There is a large number of contributors who

2183

2541

currently help in our work or have provided a great amount of help to the project

2184

in the past. There are a lot of unnamed people who help out with user

2542

in the past. There are also a lot of unnamed people who help out with user

2185

2543

notes on manual pages, which continually get included in the references, the

2186

2544

work of whom we are also very thankful for. All of the lists provided below are in

2187

2545

alphabetical order.

...

@@ -2205,23 +2563,11 @@ into managing user notes:'>

2205

2563

2206

2564

<!ENTITY listendand ' and'>

2207

2565

2208

<!-- classkit and runkit entities -->

2209

<!ENTITY note.classkit.selfmanipulation '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function cannot

2210

be used to manipulate the currently running (or chained) method.</simpara>

2211

</note>'>

2212

2566

<!-- runkit entities -->

2213

2567

<!ENTITY note.runkit.selfmanipulation '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function cannot

2214

2568

be used to manipulate the currently running (or chained) method.</simpara>

2215

2569

</note>'>

2216

2570

2217

<!ENTITY note.runkit.sandbox '<note xmlns="http://docbook.org/ns/docbook"><simpara>Sandbox support (required for

2218

<function>runkit_lint</function>, <function>runkit_lint_file</function>,

2219

and the <classname>Runkit_Sandbox</classname> class) is only available as of

2220

PHP 5.1.0 or specially patched versions of PHP 5.0, and requires that thread

2221

safety be enabled.

2222

See the <filename>README</filename> file included in the runkit package for

2223

more information.</simpara></note>'>

2224

2225

2571

<!ENTITY note.runkit.internal-override '<note xmlns="http://docbook.org/ns/docbook"><simpara>By default, only

2226

2572

userspace functions may be removed, renamed, or modified.  In order to

2227

2573

override internal functions, you must enable the

...

@@ -2366,13 +2712,6 @@ The <classname>XMLWriter</classname> instance that is being modified. This objec

2366

2712

</para>

2367

2713

</note>

2368

2714

'>

2369

<!ENTITY com.use-oo-instead '<note xmlns="http://docbook.org/ns/docbook">

2370

 <simpara>

2371

  This function does not exist in PHP 5; instead, you should use the regular

2372

  and more natural OO syntax to access properties or call methods.

2373

 </simpara>

2374

</note>

2375

'>

2376

2715

2377

2716

<!-- phar -->

2378

2717

<!ENTITY phar.write '<note xmlns="http://docbook.org/ns/docbook"><para>This

...

@@ -2380,17 +2719,6 @@ method requires the &php.ini; setting <literal>phar.readonly</literal> to be

2380

2719

set to <literal>0</literal> in order to work for <classname>Phar</classname>

2381

2720

objects.  Otherwise, a <classname>PharException</classname> will be thrown.</para></note>'>

2382

2721

2383

<!ENTITY phar.removed.pharcompress '<note xmlns="http://docbook.org/ns/docbook"><para>This

2384

method has been removed from the phar extension as of version 2.0.0.  Alternative

2385

implementations are available using <function>Phar::compress</function>,

2386

<function>Phar::decompress</function>, <function>Phar::compressFiles</function> and

2387

<function>Phar::decompressFiles</function>.</para></note>'>

2388

2389

<!ENTITY phar.removed.pharfileinfocompress '<note xmlns="http://docbook.org/ns/docbook"><para>This

2390

method has been removed from the phar extension as of version 2.0.0.  Alternative

2391

implementations are available using <function>PharFileInfo::isCompressed</function>,

2392

<function>PharFileInfo::decompress</function>, and <function>PharFileInfo::compress</function>.</para></note>'>

2393

2394

2722

<!ENTITY phar.note.performance '<note xmlns="http://docbook.org/ns/docbook">

2395

2723

 <simpara>

2396

2724

  <function>Phar::addFile</function>, <function>Phar::addFromString</function> and <function>Phar::offsetSet</function>

...

@@ -2433,6 +2761,9 @@ implementations are available using <function>PharFileInfo::isCompressed</functi

2433

2761

<varname linkend="streamwrapper.props.context">streamWrapper::$context</varname>

2434

2762

property is updated if a valid context is passed to the caller function.</para></note>'>

2435

2763

2764

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

2765

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

2766

2436

2767

<!-- Gmagick -->

2437

2768

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

2438

2769

<!ENTITY gmagick.gmagickexception.throw 'Throws an

...

@@ -2451,24 +2782,33 @@ to be references, then they must be references in the passed argument list.'>

2451

2782

2452

2783

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

2453

2784

2454

<!-- SPL -->

2455

<!ENTITY spl.datastructures.intro.title '<title xmlns="http://docbook.org/ns/docbook">Datastructures</title>'>

2456

2457

<!ENTITY spl.exceptions.intro.title '<title xmlns="http://docbook.org/ns/docbook">Exceptions</title>'>

2458

<!ENTITY spl.exceptions.intro '<para xmlns="http://docbook.org/ns/docbook">SPL provides a set of standard Exceptions.</para><para xmlns="http://docbook.org/ns/docbook">See also the <xref linkend="reserved.exceptions" /></para>'>

2459

2460

<!ENTITY spl.files.intro.title '<title xmlns="http://docbook.org/ns/docbook">File Handling</title>'>

2461

<!ENTITY spl.files.intro '<partintro xmlns="http://docbook.org/ns/docbook"><para>SPL provides a number of classes to work with files.</para></partintro>'>

2462

2463

<!ENTITY spl.interfaces.intro.title '<title xmlns="http://docbook.org/ns/docbook">Interfaces</title>'>

2464

<!ENTITY spl.interfaces.intro '<para xmlns="http://docbook.org/ns/docbook">SPL provides a set of interfaces.</para><para xmlns="http://docbook.org/ns/docbook">See also the <xref linkend="reserved.interfaces" /></para>'>

2465

<!ENTITY spl.interfaces.list '<title xmlns="http://docbook.org/ns/docbook">Interface list</title>'>

2466

2467

<!ENTITY spl.iterators.intro.title '<title xmlns="http://docbook.org/ns/docbook">Iterators</title>'>

2468

<!ENTITY spl.iterators.intro '<para xmlns="http://docbook.org/ns/docbook">SPL provides a set of iterators to traverse over objects.</para>'>

2785

<!ENTITY reflection.getattributes.param.name '<varlistentry xmlns="http://docbook.org/ns/docbook">

2786

<term><parameter>name</parameter></term>

2787

<listitem>

2788

 <para>

2789

  Filter the results to include only <classname>ReflectionAttribute</classname>

2790

  instances for attributes matching this class name.

2791

 </para>

2792

</listitem>

2793

</varlistentry>'>

2469

2794

2470

<!ENTITY spl.misc.intro.title '<title xmlns="http://docbook.org/ns/docbook">Miscellaneous Classes and Interfaces</title>'>

2471

<!ENTITY spl.misc.intro '<partintro xmlns="http://docbook.org/ns/docbook"><para>Classes and interfaces which do not fit into the other SPL categories.</para></partintro>'>

2795

<!ENTITY reflection.getattributes.param.flags '<varlistentry xmlns="http://docbook.org/ns/docbook">

2796

<term><parameter>flags</parameter></term>

2797

<listitem>

2798

 <para>

2799

  Flags for determining how to filter the results, if <parameter>name</parameter>

2800

  is provided.

2801

 </para>

2802

 <para>

2803

  Default is <literal>0</literal> which will only return results for attributes that

2804

  are of the class <parameter>name</parameter>.

2805

 </para>

2806

 <para>

2807

  The only other option available, is to use <constant>ReflectionAttribute::IS_INSTANCEOF</constant>,

2808

  which will instead use <literal>instanceof</literal> for filtering.

2809

 </para>

2810

</listitem>

2811

</varlistentry>'>

2472

2812

2473

2813

<!-- ZIP -->

2474

2814

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

...

@@ -2575,7 +2915,7 @@ system call.</para></listitem>

2575

2915

</varlistentry>

2576

2916

<varlistentry xmlns="http://docbook.org/ns/docbook">

2577

2917

<term><parameter>req</parameter></term>

2578

<listitem><para>is optional request resource which can be used with functions like <function>eio_get_last_error</function></para></listitem>

2918

<listitem><para>is optional request resource which can be used with functions like <function>eio_get_last_error</function>.</para></listitem>

2579

2919

</varlistentry>

2580

2920

</variablelist>

2581

2921

</para>

...

@@ -2620,7 +2960,7 @@ paths</simpara></warning>

2620

2960

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

2621

2961

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

2622

2962

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

2623

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

2963

<!ENTITY trader.arg.fastk.ma.type 'Type of Moving Average for Fast-K. <link xmlns="http://docbook.org/ns/docbook" linkend="trader.constants">TRADER_MA_TYPE_*</link> series of constants should be used.'>

2624

2964

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

2625

2965

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

2626

2966

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

...

@@ -2629,70 +2969,46 @@ paths</simpara></warning>

2629

2969

<!ENTITY trader.arg.fast.limit 'Upper limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.'>

2630

2970

<!ENTITY trader.arg.slow.limit 'Lower limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.'>

2631

2971

2632

<!-- Mongo -->

2633

<!ENTITY mongo.setreadpreference.parameters '<variablelist xmlns="http://docbook.org/ns/docbook"><varlistentry><term><parameter>read_preference</parameter></term><listitem><para>The read preference mode: <constant>MongoClient::RP_PRIMARY</constant>, <constant>MongoClient::RP_PRIMARY_PREFERRED</constant>, <constant>MongoClient::RP_SECONDARY</constant>, <constant>MongoClient::RP_SECONDARY_PREFERRED</constant>, or <constant>MongoClient::RP_NEAREST</constant>.</para></listitem></varlistentry><varlistentry><term><parameter>tags</parameter></term><listitem><para>An array of zero or more tag sets, where each tag set is itself an array of criteria used to match tags on replica set members.</para></listitem></varlistentry></variablelist>'>

2634

<!ENTITY mongo.setreadpreference.returnvalues '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>

2635

<!ENTITY mongo.setreadpreference.errors '<para xmlns="http://docbook.org/ns/docbook">Emits <constant>E_WARNING</constant> if either parameter is invalid, or if one or more tag sets are provided with the <constant>MongoClient::RP_PRIMARY</constant> read preference mode.</para>'>

2636

<!ENTITY mongo.getreadpreference.returnvalues '<para xmlns="http://docbook.org/ns/docbook">This function returns an array describing the read preference. The array contains the values <literal>type</literal> for the string read preference mode (corresponding to the <classname>MongoClient</classname> constants), and <literal>tagsets</literal> containing a list of all tag set criteria. If no tag sets were specified, <literal>tagsets</literal> will not be present in the array.</para>'>

2637

<!ENTITY mongo.setwriteconcern.parameters '<variablelist xmlns="http://docbook.org/ns/docbook"><varlistentry><term><parameter>w</parameter></term><listitem><para>The write concern. This may be an integer denoting the number of servers required to acknowledge the write, or a string mode (e.g. "majority").</para></listitem></varlistentry><varlistentry><term><parameter>wtimeout</parameter></term><listitem><para>The maximum number of milliseconds to wait for the server to satisfy the write concern.</para></listitem></varlistentry></variablelist>'>

2638

<!ENTITY mongo.setwriteconcern.returnvalues '<para xmlns="http://docbook.org/ns/docbook">Returns &true; on success, or &false; otherwise.</para>'>

2639

<!ENTITY mongo.setwriteconcern.errors '<para xmlns="http://docbook.org/ns/docbook">Emits <constant>E_WARNING</constant> if the <literal>w</literal> parameter is not an integer or string value.</para>'>

2640

<!ENTITY mongo.getwriteconcern.returnvalues '<para xmlns="http://docbook.org/ns/docbook">This function returns an array describing the write concern. The array contains the values <literal>w</literal> for an integer acknowledgement level or string mode, and <literal>wtimeout</literal> denoting the maximum number of milliseconds to wait for the server to satisfy the write concern.</para>'>

2641

<!ENTITY mongo.command.parameters.maxtimems '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"maxTimeMS"</literal></para><para>Specifies a cumulative time limit in milliseconds for processing the operation on the server (does not include idle time). If the operation is not completed by the server within the timeout period, a <classname>MongoExecutionTimeoutException</classname> will be thrown.</para></listitem>'>

2642

<!ENTITY mongo.index.parameters.background '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"background"</literal></para><para>Builds the index in the background so that building an index does <emphasis>not</emphasis> block other database activities. Specify &true; to build in the background. The default value is &false;.</para><warning xmlns="http://docbook.org/ns/docbook"><para>Prior to MongoDB 2.6.0, index builds on secondaries were executed as foreground operations, irrespective of this option. See <link xlink:href="&url.mongodb.dochub.indexes.rs;" xmlns:xlink="http://www.w3.org/1999/xlink">Building Indexes with Replica Sets</link> for more information.</para></warning></listitem>'>

2643

<!ENTITY mongo.index.parameters.dropdups '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"dropDups"</literal></para><para>Specify &true; to force creation of a unique index where the collection may contain duplicate values for a key. MongoDB will index the first occurrence of a key and delete all subsequent documents from the collection that contain a duplicate value for that key. The default value is &false;.</para><warning xmlns="http://docbook.org/ns/docbook"><para><literal>"dropDups"</literal> may delete data from your database. Use with extreme caution.</para></warning><note xmlns="http://docbook.org/ns/docbook"><para>This option is not supported on MongoDB 2.8+. Index creation will fail if the collection contains duplicate values.</para></note></listitem>'>

2644

<!ENTITY mongo.index.parameters.expireafterseconds '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"expireAfterSeconds"</literal></para><para>The value of this option should specify the number of seconds after which a document should be considered expired and automatically removed from the collection. This option is only compatible with single-field indexes where the field will contain <classname>MongoDate</classname> values.</para><note xmlns="http://docbook.org/ns/docbook"><para>This feature is available in MongoDB 2.2+. See <link xlink:href="&url.mongodb.docs.expire_data;" xmlns:xlink="http://www.w3.org/1999/xlink">Expire Data from Collections by Setting TTL</link> for more information.</para></note></listitem>'>

2645

<!ENTITY mongo.index.parameters.name '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"name"</literal></para><para>A optional name that uniquely identifies the index.</para><note xmlns="http://docbook.org/ns/docbook"><para>By default, the driver will generate an index name based on the index&apos;s field(s) and ordering or type. For example, a compound index <literal>array("x" => 1, "y" => -1)</literal> would be named <literal>"x_1_y_-1"</literal> and a geospatial index <literal>array("loc" => "2dsphere")</literal> would be named <literal>"loc_2dsphere"</literal>. For indexes with many fields, it is possible that the generated name might exceed MongoDB&apos;s <link xlink:href="&url.mongodb.docs.limits;#Index-Name-Length" xmlns:xlink="http://www.w3.org/1999/xlink">limit for index names</link>. The <literal>"name"</literal> option may be used in that case to supply a shorter name.</para></note></listitem>'>

2646

<!ENTITY mongo.index.parameters.sparse '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"sparse"</literal></para><para>Specify &true; to create a sparse index, which only indexes documents containing a specified field. The default value is &false;.</para></listitem>'>

2647

<!ENTITY mongo.index.parameters.unique '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"unique"</literal></para><para>Specify &true; to create a unique index. The default value is &false;. This option applies only to ascending/descending indexes.</para><note xmlns="http://docbook.org/ns/docbook"><para>When MongoDB indexes a field, if a document does not have a value for the field, a &null; value is indexed. If multiple documents do not contain a field, a unique index will reject all but the first of those documents. The <literal>"sparse"</literal> option may be used to overcome this, since it will prevent documents without the field from being indexed.</para></note></listitem>'>

2648

<!ENTITY mongo.listcollections.note '<note xmlns="http://docbook.org/ns/docbook"><simpara>This method will use the <link xlink:href="&url.mongodb.docs.command;listCollections" xmlns:xlink="http://www.w3.org/1999/xlink">listCollections</link> database command when communicating with MongoDB 2.8+. For previous database versions, the method will query the special <literal>system.namespaces</literal> collection.</simpara></note>'>

2649

<!ENTITY mongo.listcollections.parameters.filter '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"filter"</literal></para><para>Optional query criteria. If provided, this criteria will be used to filter the collections included in the result.</para><para>Relevant fields that may be queried include <literal>"name"</literal> (collection name as a string, without the database name prefix) and <literal>"options" (object containing options used to create the collection).</literal>.</para><note><simpara>MongoDB 2.6 and earlier versions require the <literal>"name"</literal> criteria, if specified, to be a string value (i.e. equality match). This is because the driver must prefix the value with the database name in order to query the <literal>system.namespaces</literal> collection. Later versions of MongoDB do not have this limitation, as the driver will use the listCollections command.</simpara></note></listitem>'>

2650

<!ENTITY mongo.listcollections.parameters.includesystemcollections '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"includeSystemCollections"</literal></para><para>Boolean, defaults to &false;. Determines whether system collections should be included in the result.</para></listitem>'>

2651

<!ENTITY mongo.writes.parameters.writeconcern '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"w"</literal></para><para>See <link linkend="mongo.writeconcerns">Write Concerns</link>. The default value for <classname>MongoClient</classname> is <literal>1</literal>.</para></listitem>'>

2652

<!ENTITY mongo.writes.parameters.writeconcerntimeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"wtimeout"</literal></para><para>Deprecated alias for <literal>"wTimeoutMS"</literal>.</para></listitem>'>

2653

<!ENTITY mongo.writes.parameters.writeconcerntimeoutms '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"wTimeoutMS"</literal></para><para>This option specifies the time limit, in milliseconds, for <link linkend="mongo.writeconcerns">write concern</link> acknowledgement. It is only applicable when <literal>"w"</literal> is greater than <literal>1</literal>, as the timeout pertains to replication. If the write concern is not satisfied within the time limit, a <classname>MongoCursorException</classname> will be thrown. A value of <literal>0</literal> may be specified to block indefinitely. The default value for <classname>MongoClient</classname> is <literal>10000</literal> (ten seconds).</para></listitem>'>

2654

<!ENTITY mongo.writes.parameters.fsync '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"fsync"</literal></para><para>Boolean, defaults to &false;. If journaling is enabled, it works exactly like <literal>"j"</literal>. If journaling is not enabled, the write operation blocks until it is synced to database files on disk. If &true;, an acknowledged insert is implied and this option will override setting <literal>"w"</literal> to <literal>0</literal>.</para><note><simpara>If journaling is enabled, users are strongly encouraged to use the <literal>"j"</literal> option instead of <literal>"fsync"</literal>. Do not use <literal>"fsync"</literal> and <literal>"j"</literal> simultaneously, as that will result in an error.</simpara></note></listitem>'>

2655

<!ENTITY mongo.writes.parameters.sockettimeoutms '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"socketTimeoutMS"</literal></para><para>This option specifies the time limit, in milliseconds, for socket communication. If the server does not respond within the timeout period, a <classname>MongoCursorTimeoutException</classname> will be thrown and there will be no way to determine if the server actually handled the write or not. A value of <literal>-1</literal> may be specified to block indefinitely. The default value for <classname>MongoClient</classname> is <literal>30000</literal> (30 seconds).</para></listitem>'>

2656

<!ENTITY mongo.writes.parameters.journal '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"j"</literal></para><para>Boolean, defaults to &false;. Forces the write operation to block until it is synced to the journal on disk. If &true;, an acknowledged write is implied and this option will override setting <literal>"w"</literal> to <literal>0</literal>.</para><note><simpara>If this option is used and journaling is disabled, MongoDB 2.6+ will raise an error and the write will fail; older server versions will simply ignore the option.</simpara></note></listitem>'>

2657

<!ENTITY mongo.writes.parameters.safe '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"safe"</literal></para><para>Deprecated. Please use the <link linkend="mongo.writeconcerns">write concern</link> <literal>"w"</literal> option.</para></listitem>'>

2658

<!ENTITY mongo.writes.parameters.timeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"timeout"</literal></para><para>Deprecated alias for <literal>"socketTimeoutMS"</literal>.</para></listitem>'>

2659

<!ENTITY mongo.errors.exceptions.writeconcern '<para xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoCursorException</classname> if the <literal>"w"</literal> option is set and the write fails.</para><para xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoCursorTimeoutException</classname> if the <literal>"w"</literal> option is set to a value greater than one and the operation takes longer than <varname>MongoCursor::$timeout</varname> milliseconds to complete.  This does not kill the operation on the server, it is a client-side timeout. The operation in <varname>MongoCollection::$wtimeout</varname> is milliseconds.</para>'>

2660

<!ENTITY mongo.errors.deprecated '<para xmlns="http://docbook.org/ns/docbook">Issues <constant>E_DEPRECATED</constant> warning</para>'>

2661

<!ENTITY mongo.gridfs.store.metadata.note '<note xmlns="http://docbook.org/ns/docbook"><para>These fields may also overwrite those that would be created automatically by the driver, as described in the MongoDB core documentation for the <link xlink:href="&url.mongodb.docs.gridfs;#the-files-collection" xmlns:xlink="http://www.w3.org/1999/xlink">files collection</link>. Some practical use cases for this behavior would be to specify a custom <literal>chunkSize</literal> or <literal>_id</literal> for the file.</para></note>'>

2662

<!ENTITY mongo.gridfs.store.return '<para xmlns="http://docbook.org/ns/docbook">Returns the <literal>_id</literal> of the saved file document. This will be a generated <classname>MongoId</classname> unless an <literal>_id</literal> was explicitly specified in the <parameter>metadata</parameter> parameter.</para>'>

2663

<!ENTITY mongo.mongowritebatch.writeoptions.description '<listitem xmlns="http://docbook.org/ns/docbook"><para>An array of Write Options.<informaltable><thead><row><entry>key</entry><entry>value meaning</entry></row></thead><tbody><row><entry>w (int|string)</entry><entry><link linkend="mongo.writeconcerns">Write concern</link> value</entry></row><row><entry>wtimeout (int)</entry><entry><link linkend="mongo.writeconcerns">Maximum time to wait for replication</link></entry></row><row><entry>ordered</entry><entry>Determines if MongoDB must apply this batch in order. Ordered writes execute serially (i.e. one at a time) and execution will stop after the first error. Unordered writes may execute in parallel and execution will not stop after the first error. Defaults to &true;</entry></row><row><entry>j (bool)</entry><entry>Wait for journaling on the primary. This value is discouraged, use WriteConcern instead</entry></row><row><entry>fsync (bool)</entry><entry>Wait for fsync on the primary. This value is discouraged, use WriteConcern instead</entry></row></tbody></informaltable></para></listitem>'>

2664

<!ENTITY mongo.mongowritebatch.collection.description '<listitem xmlns="http://docbook.org/ns/docbook"><para>The <classname>MongoCollection</classname> to execute the batch on. Its <link linkend="mongo.writeconcerns">write concern</link> will be copied and used as the default write concern if none is given as <parameter>$write_options</parameter> or during <methodname>MongoWriteBatch::execute</methodname>.</para></listitem>'>

2665

<!ENTITY mongo.context.server ' <varlistentry xmlns="http://docbook.org/ns/docbook"> <term> <parameter>server</parameter> </term> <listitem> <para> An array containing the basic information about the server that was picked. <informaltable> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>hash</entry> <entry>server hash, example: <literal>localhost:27017;-;X;56052</literal></entry> </row> <row> <entry>type</entry> <entry>Node type (primary/secondary/mongos/arbiter): <literal>2</literal></entry> </row> <row> <entry>max_bson_size</entry> <entry>The maximum BSON Size over the wire this node accepts: <literal>16777216</literal></entry> </row> <row> <entry>max_message_size</entry> <entry>The maximum Message Size over the wire this node accepts: <literal>48000000</literal></entry> </row> <row> <entry>request_id</entry> <entry>The request identifier for this message: <literal>42</literal></entry> </row> </tbody> </tgroup> </informaltable> </para> </listitem> </varlistentry>'> 

2666

<!ENTITY mongo.context.writeoptions '<varlistentry xmlns="http://docbook.org/ns/docbook"> <term> <parameter>writeOptions</parameter> </term> <listitem> <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>ordered</entry> <entry>boolean, if the operation (in case of batch operation) must be executed sequentually (ordered=true)</entry> </row> <row> <entry>writeConcern</entry> <entry>An array of writeConcern options (see below)</entry> </row> </tbody> </tgroup> </informaltable> <table> <title>writeConcern array values</title> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>fsync</entry> <entry>boolean, force flushing to disk before returning</entry> </row> <row> <entry>j</entry> <entry>boolean, force journal write before returning</entry> </row> <row> <entry>wtimeout</entry> <entry>integer, milliseconds, maximum time the primary is allowed to wait to verify replication</entry> </row> <row> <entry>w</entry> <entry>integer=server count, or string=replication-tag</entry> </row> </tbody> </tgroup> </table> </para> </listitem> </varlistentry>'> 

2667

<!ENTITY mongo.context.protocoloptions ' <varlistentry xmlns="http://docbook.org/ns/docbook"> <term> <parameter>protocolOptions</parameter> </term> <listitem> <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> <entry>message_length</entry> <entry>The total size (in bytes) of the encoded message being sent over the wire</entry> </row> <row> <entry>request_id</entry> <entry>The request identifier for this message: <literal>42</literal></entry> </row> <row> <entry>namespace</entry> <entry>The MongoDB namespace used for the protocol message <literal>dbname.collectionname</literal></entry> </row> </tbody> </tgroup> </informaltable> </para> </listitem> </varlistentry>'> 

2668

<!ENTITY mongo.alternative.class.note '<para

2669

xmlns="http://docbook.org/ns/docbook">This extension that defines this class

2670

is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.

2671

Alternatives to this class include:</para>'>

2672

<!ENTITY mongo.noalternative.class.note '<para

2673

xmlns="http://docbook.org/ns/docbook">This extension that defines this class

2674

is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.

2675

There is no equivalent for this class in the new extension.</para>'>

2676

<!ENTITY mongo.alternative.method.note '<para

2677

xmlns="http://docbook.org/ns/docbook">This extension that defines this method

2678

is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.

2679

Alternatives to this method include:</para>'>

2680

<!ENTITY mongo.noalternative.method.note '<para

2681

xmlns="http://docbook.org/ns/docbook">This extension that defines this method

2682

is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.

2683

There is no equivalent for this method in the new extension.</para>'>

2684

<!ENTITY mongo.alternative.phplib.note '<para

2685

xmlns="http://docbook.org/ns/docbook">This extension that defines this method

2686

is deprecated. Instead, the <link linkend="set.mongodb">MongoDB</link> extension should be used.

2687

There is no equivalent for this method in the new extension, but there is an

2688

alternative in the <link linkend="mongodb.overview">PHP library</link>:</para>'>

2689

2690

<!ENTITY mongo.deprecated.note '<para

2691

xmlns="http://docbook.org/ns/docbook">This extension is deprecated. Instead,

2692

the <link linkend="set.mongodb">MongoDB</link> extension should be

2693

used.</para>'>

2694

2695

2972

<!-- mongodb -->

2973

<!ENTITY mongodb.changelog.class-removed '

2974

       <row xmlns="http://docbook.org/ns/docbook">

2975

        <entry>PECL mongodb 2.0.0</entry>

2976

        <entry>

2977

         This class was removed.

2978

        </entry>

2979

       </row>

2980

'>

2981

2982

<!ENTITY mongodb.changelog.function-removed '

2983

       <row xmlns="http://docbook.org/ns/docbook">

2984

        <entry>PECL mongodb 2.0.0</entry>

2985

        <entry>

2986

         This function was removed.

2987

        </entry>

2988

       </row>

2989

'>

2990

2991

<!ENTITY mongodb.changelog.method-removed '

2992

       <row xmlns="http://docbook.org/ns/docbook">

2993

        <entry>PECL mongodb 2.0.0</entry>

2994

        <entry>

2995

         This method was removed.

2996

        </entry>

2997

       </row>

2998

'>

2999

3000

<!ENTITY mongodb.changelog.serializable-interface-removed '

3001

       <row xmlns="http://docbook.org/ns/docbook">

3002

        <entry>PECL mongodb 2.0.0</entry>

3003

        <entry>

3004

         <para>

3005

          This class no longer implements the

3006

          <interfacename>Serializable</interfacename> interface.

3007

         </para>

3008

        </entry>

3009

       </row>

3010

'>

3011

2696

3012

<!ENTITY mongodb.changelog.tentative-return-types '

2697

3013

       <row xmlns="http://docbook.org/ns/docbook">

2698

3014

        <entry>PECL mongodb 1.15.0</entry>

...

@@ -2705,6 +3021,26 @@ used.</para>'>

2705

3021

       </row>

2706

3022

'>

2707

3023

3024

<!ENTITY mongodb.changelog.tentative-return-types-enforced '

3025

       <row xmlns="http://docbook.org/ns/docbook">

3026

        <entry>PECL mongodb 2.0.0</entry>

3027

        <entry>

3028

         Return types previously declared as tentative are now enforced.

3029

        </entry>

3030

       </row>

3031

'>

3032

3033

<!ENTITY mongodb.changelog.throw-unacknowledged-write '

3034

       <row xmlns="http://docbook.org/ns/docbook">

3035

        <entry>PECL mongodb 2.0.0</entry>

3036

        <entry>

3037

         <para>

3038

          This method now throws an exception when called for an unacknowledged write instead of returning &null;.

3039

         </para>

3040

        </entry>

3041

       </row>

3042

'>

3043

2708

3044

<!ENTITY mongodb.option.collation '

2709

3045

         <row xmlns="http://docbook.org/ns/docbook">

2710

3046

          <entry>collation</entry>

...

@@ -2747,17 +3083,23 @@ used.</para>'>

2747

3083

         <row xmlns="http://docbook.org/ns/docbook">

2748

3084

          <entry>keyVaultNamespace</entry>

2749

3085

          <entry><type>string</type></entry>

2750

          <entry>A fully qualified namespace (e.g. <literal>"databaseName.collectionName"</literal>) denoting the collection that contains all data keys used for encryption and decryption.</entry>

3086

          <entry>A fully qualified namespace (e.g. <literal>"databaseName.collectionName"</literal>) denoting the collection that contains all data keys used for encryption and decryption. This option is required.</entry>

2751

3087

         </row>

2752

3088

'>

2753

3089

<!ENTITY mongodb.option.encryption.kmsProviders '

2754

         <row xmlns="http://docbook.org/ns/docbook">

3090

         <row xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

2755

3091

          <entry>kmsProviders</entry>

2756

3092

          <entry><type>array</type></entry>

2757

3093

          <entry>

2758

3094

           <para>

2759

3095

            A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Supported providers include <literal>"aws"</literal>, <literal>"azure"</literal>, <literal>"gcp"</literal>, <literal>"kmip"</literal>, and <literal>"local"</literal> and at least one must be specified.

2760

3096

           </para>

3097

           <para>

3098

            If an empty document is specified for <literal>"aws"</literal>,

3099

            <literal>"azure"</literal>, or <literal>"gcp"</literal>, the driver

3100

            will attempt to configure the provider using

3101

            <link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#automatic-credentials">Automatic Credentials</link>.

3102

           </para>

2761

3103

           <para>

2762

3104

            The format for <literal>"aws"</literal> is as follows:

2763

3105

           </para>

...

@@ -2765,7 +3107,8 @@ used.</para>'>

2765

3107

<![CDATA[

2766

3108

aws: {

2767

3109

    accessKeyId: <string>,

2768

    secretAccessKey: <string>

3110

    secretAccessKey: <string>,

3111

    sessionToken: <optional string>

2769

3112

}

2770

3113

]]>

2771

3114

           </programlisting>

...

@@ -2818,6 +3161,147 @@ local: {

2818

3161

          </entry>

2819

3162

         </row>

2820

3163

'>

3164

<!ENTITY mongodb.option.encryption.masterKey-options-by-provider '

3165

  <para xmlns="http://docbook.org/ns/docbook">

3166

   <table>

3167

    <title><literal>"aws"</literal> provider options</title>

3168

    <tgroup cols="3">

3169

     <thead>

3170

      <row>

3171

       <entry>Option</entry>

3172

       <entry>Type</entry>

3173

       <entry>Description</entry>

3174

      </row>

3175

     </thead>

3176

     <tbody>

3177

      <row>

3178

       <entry>region</entry>

3179

       <entry>string</entry>

3180

       <entry>Required.</entry>

3181

      </row>

3182

      <row>

3183

       <entry>key</entry>

3184

       <entry>string</entry>

3185

       <entry>Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).</entry>

3186

      </row>

3187

      <row>

3188

       <entry>endpoint</entry>

3189

       <entry>string</entry>

3190

       <entry>Optional. An alternate host identifier to send KMS requests to. May include port number.</entry>

3191

      </row>

3192

     </tbody>

3193

    </tgroup>

3194

   </table>

3195

  </para>

3196

  <para xmlns="http://docbook.org/ns/docbook">

3197

   <table>

3198

    <title><literal>"azure"</literal> provider options</title>

3199

    <tgroup cols="3">

3200

     <thead>

3201

      <row>

3202

       <entry>Option</entry>

3203

       <entry>Type</entry>

3204

       <entry>Description</entry>

3205

      </row>

3206

     </thead>

3207

     <tbody>

3208

      <row>

3209

       <entry>keyVaultEndpoint</entry>

3210

       <entry>string</entry>

3211

       <entry>Required. Host with optional port (e.g. "example.vault.azure.net").</entry>

3212

      </row>

3213

      <row>

3214

       <entry>keyName</entry>

3215

       <entry>string</entry>

3216

       <entry>Required.</entry>

3217

      </row>

3218

      <row>

3219

       <entry>keyVersion</entry>

3220

       <entry>string</entry>

3221

       <entry>Optional. A specific version of the named key. Defaults to using the key&apos;s primary version.</entry>

3222

      </row>

3223

     </tbody>

3224

    </tgroup>

3225

   </table>

3226

  </para>

3227

  <para xmlns="http://docbook.org/ns/docbook">

3228

   <table>

3229

    <title><literal>"gcp"</literal> provider options</title>

3230

    <tgroup cols="3">

3231

     <thead>

3232

      <row>

3233

       <entry>Option</entry>

3234

       <entry>Type</entry>

3235

       <entry>Description</entry>

3236

      </row>

3237

     </thead>

3238

     <tbody>

3239

      <row>

3240

       <entry>projectId</entry>

3241

       <entry>string</entry>

3242

       <entry>Required.</entry>

3243

      </row>

3244

      <row>

3245

       <entry>location</entry>

3246

       <entry>string</entry>

3247

       <entry>Required.</entry>

3248

      </row>

3249

      <row>

3250

       <entry>keyRing</entry>

3251

       <entry>string</entry>

3252

       <entry>Required.</entry>

3253

      </row>

3254

      <row>

3255

       <entry>keyName</entry>

3256

       <entry>string</entry>

3257

       <entry>Required.</entry>

3258

      </row>

3259

      <row>

3260

       <entry>keyVersion</entry>

3261

       <entry>string</entry>

3262

       <entry>Optional. A specific version of the named key. Defaults to using the key&apos;s primary version.</entry>

3263

      </row>

3264

      <row>

3265

       <entry>endpoint</entry>

3266

       <entry>string</entry>

3267

       <entry>Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".</entry>

3268

      </row>

3269

     </tbody>

3270

    </tgroup>

3271

   </table>

3272

  </para>

3273

  <para xmlns="http://docbook.org/ns/docbook">

3274

   <table>

3275

    <title><literal>"kmip"</literal> provider options</title>

3276

    <tgroup cols="3">

3277

     <thead>

3278

      <row>

3279

       <entry>Option</entry>

3280

       <entry>Type</entry>

3281

       <entry>Description</entry>

3282

      </row>

3283

     </thead>

3284

     <tbody>

3285

      <row>

3286

       <entry>keyId</entry>

3287

       <entry>string</entry>

3288

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

3289

      </row>

3290

      <row>

3291

       <entry>endpoint</entry>

3292

       <entry>string</entry>

3293

       <entry>Optional. Host with optional port.</entry>

3294

      </row>

3295

      <row>

3296

       <entry>delegated</entry>

3297

       <entry>bool</entry>

3298

       <entry>Optional. If true, this key should be decrypted by the KMIP server.</entry>

3299

      </row>

3300

     </tbody>

3301

    </tgroup>

3302

   </table>

3303

  </para>

3304

'>

2821

3305

<!ENTITY mongodb.option.encryption.tlsOptions '

2822

3306

         <row xmlns="http://docbook.org/ns/docbook">

2823

3307

          <entry>tlsOptions</entry>

...

@@ -2831,7 +3315,8 @@ local: {

2831

3315

<provider>: {

2832

3316

    tlsCaFile: <optional string>,

2833

3317

    tlsCertificateKeyFile: <optional string>,

2834

    tlsCertificateKeyFilePassword: <optional string>

3318

    tlsCertificateKeyFilePassword: <optional string>,

3319

    tlsDisableOCSPEndpointCheck: <optional bool>

2835

3320

}

2836

3321

]]>

2837

3322

           </programlisting>

...

@@ -2946,6 +3431,16 @@ local: {

2946

3431

    </listitem>

2947

3432

   </varlistentry>

2948

3433

'>

3434

<!ENTITY mongodb.parameter.bulkwritecommand '

3435

   <varlistentry xmlns="http://docbook.org/ns/docbook">

3436

    <term><parameter>bulk</parameter> (<classname>MongoDB\Driver\BulkWriteCommand</classname>)</term>

3437

    <listitem>

3438

     <para>

3439

      The write(s) to execute.

3440

     </para>

3441

    </listitem>

3442

   </varlistentry>

3443

'>

2949

3444

<!ENTITY mongodb.parameter.command '

2950

3445

   <varlistentry xmlns="http://docbook.org/ns/docbook">

2951

3446

    <term><parameter>command</parameter> (<classname>MongoDB\Driver\Command</classname>)</term>

...

@@ -2956,6 +3451,172 @@ local: {

2956

3451

    </listitem>

2957

3452

   </varlistentry>

2958

3453

'>

3454

<!ENTITY mongodb.parameter.encryptOpts '

3455

   <varlistentry xmlns="http://docbook.org/ns/docbook">

3456

    <term><parameter>options</parameter></term>

3457

    <listitem>

3458

     <para>

3459

      <table>

3460

       <title>Encryption options</title>

3461

       <tgroup cols="3">

3462

        <thead>

3463

         <row>

3464

          <entry>Option</entry>

3465

          <entry>Type</entry>

3466

          <entry>Description</entry>

3467

         </row>

3468

        </thead>

3469

        <tbody>

3470

         <row>

3471

          <entry>algorithm</entry>

3472

          <entry><type>string</type></entry>

3473

          <entry>

3474

           <para>

3475

            The encryption algorithm to be used. This option is required.

3476

            Specify one of the following

3477

            <link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:

3478

           </para>

3479

           <simplelist>

3480

            <member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC</constant></member>

3481

            <member><constant>MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM</constant></member>

3482

            <member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant></member>

3483

            <member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED</constant></member>

3484

            <member><constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant></member>

3485

           </simplelist>

3486

          </entry>

3487

         </row>

3488

         <row>

3489

          <entry>contentionFactor</entry>

3490

          <entry><type>int</type></entry>

3491

          <entry>

3492

           <para>

3493

            The contention factor for evaluating queries with indexed, encrypted

3494

            payloads.

3495

           </para>

3496

           <para>

3497

            This option only applies and may only be specified when

3498

            <literal>algorithm</literal> is

3499

            <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>

3500

or

3501

            <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant>.

3502

           </para>

3503

          </entry>

3504

         </row>

3505

         <row>

3506

          <entry>keyAltName</entry>

3507

          <entry><type>string</type></entry>

3508

          <entry>

3509

           <para>

3510

            Identifies a key vault collection document by

3511

            <literal>keyAltName</literal>. This option is mutually exclusive

3512

            with <literal>keyId</literal> and exactly one is required.

3513

           </para>

3514

          </entry>

3515

         </row>

3516

         <row>

3517

          <entry>keyId</entry>

3518

          <entry><classname>MongoDB\BSON\Binary</classname></entry>

3519

          <entry>

3520

           <para>

3521

            Identifies a data key by <literal>_id</literal>. The value is a UUID

3522

            (binary subtype 4). This option is mutually exclusive with

3523

            <literal>keyAltName</literal> and exactly one is required.

3524

           </para>

3525

          </entry>

3526

         </row>

3527

         <row>

3528

          <entry>queryType</entry>

3529

          <entry><type>string</type></entry>

3530

          <entry>

3531

           <para>

3532

            The query type for evaluating queries with indexed, encrypted

3533

            payloads. Specify one of the following

3534

            <link linkend="mongodb-driver-clientencryption.constants">ClientEncryption constants</link>:

3535

           </para>

3536

           <simplelist>

3537

            <member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY</constant></member>

3538

            <member><constant>MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE</constant></member>

3539

           </simplelist>

3540

           <para>

3541

            This option only applies and may only be specified when

3542

            <literal>algorithm</literal> is

3543

            <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED</constant>

3544

            or <constant>MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE</constant>.

3545

           </para>

3546

          </entry>

3547

         </row>

3548

         <row>

3549

          <entry>rangeOpts</entry>

3550

          <entry><type>array</type></entry>

3551

          <entry>

3552

           <para>

3553

            Index options for a queryable encryption field supporting "range"

3554

            queries. The options below must match the values set in the

3555

            <literal>encryptedFields</literal> of the target collection. For

3556

            double and decimal128 BSON field types, <literal>min</literal>,

3557

            <literal>max</literal>, and <literal>precision</literal> must all be

3558

            set, or all be unset.

3559

           </para>

3560

           <para>

3561

            <table>

3562

             <title>Range index options</title>

3563

             <tgroup cols="3">

3564

              <thead>

3565

               <row>

3566

                <entry>Option</entry>

3567

                <entry>Type</entry>

3568

                <entry>Description</entry>

3569

               </row>

3570

              </thead>

3571

              <tbody>

3572

               <row>

3573

                <entry>min</entry>

3574

                <entry><type>mixed</type></entry>

3575

                <entry>

3576

                 Required if <literal>precision</literal> is set. The minimum

3577

                 BSON value of the range.

3578

                </entry>

3579

               </row>

3580

               <row>

3581

                <entry>max</entry>

3582

                <entry><type>mixed</type></entry>

3583

                <entry>

3584

                 Required if <literal>precision</literal> is set. The maximum

3585

                 BSON value of the range.

3586

                </entry>

3587

               </row>

3588

               <row>

3589

                <entry>sparsity</entry>

3590

                <entry><type>int</type></entry>

3591

                <entry>Optional. Positive 64-bit integer.</entry>

3592

               </row>

3593

               <row>

3594

                <entry>precision</entry>

3595

                <entry><type>int</type></entry>

3596

                <entry>

3597

                 Optional. Positive 32-bit integer specifying precision to use

3598

                 for explicit encryption. May only be set for double or

3599

                 decimal128 BSON field types.

3600

                </entry>

3601

               </row>

3602

               <row>

3603

                <entry>trimFactor</entry>

3604

                <entry><type>int</type></entry>

3605

                <entry>Optional. Positive 32-bit integer.</entry>

3606

               </row>

3607

              </tbody>

3608

             </tgroup>

3609

            </table>

3610

           </para>

3611

          </entry>

3612

         </row>

3613

        </tbody>

3614

       </tgroup>

3615

      </table>

3616

     </para>

3617

    </listitem>

3618

   </varlistentry>

3619

'>

2959

3620

<!ENTITY mongodb.parameter.query '

2960

3621

   <varlistentry xmlns="http://docbook.org/ns/docbook">

2961

3622

    <term><parameter>query</parameter> (<classname>MongoDB\Driver\Query</classname>)</term>

...

@@ -2986,7 +3647,7 @@ local: {

2986

3647

     </para>

2987

3648

     <note>

2988

3649

      <simpara>

2989

       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="book.bson">BSON class</link> (e.g. use <classname>MongoDB\BSON\ObjectId</classname> to match an <link xlink:href="&url.mongodb.docs.objectid;" xmlns:xlink="http://www.w3.org/1999/xlink">ObjectId</link>).

3650

       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>).

2990

3651

      </simpara>

2991

3652

     </note>

2992

3653

    </listitem>

...

@@ -2994,24 +3655,20 @@ local: {

2994

3655

'>

2995

3656

<!ENTITY mongodb.returns.cursor '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\Cursor</classname> on success.</para>'>

2996

3657

<!ENTITY mongodb.returns.writeresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\WriteResult</classname> on success.</para>'>

3658

<!ENTITY mongodb.returns.bulkwritecommandresult '<para xmlns="http://docbook.org/ns/docbook">Returns <classname>MongoDB\Driver\BulkWriteCommandResult</classname> on success.</para>'>

2997

3659

<!ENTITY mongodb.throws.std '&mongodb.throws.argumentparsing;&mongodb.throws.connection;&mongodb.throws.authentication;'>

2998

3660

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

2999

3661

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

3662

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

3000

3663

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

3001

3664

<!ENTITY mongodb.throws.argumentparsing '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> on argument parsing errors.</member>'>

3002

3665

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

3003

3666

<!ENTITY mongodb.throws.connection '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\ConnectionException</classname> if connection to the server fails (for reasons other than authentication).</member>'>

3004

3667

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

3668

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

3005

3669

3006

<!ENTITY mongodb.note.queryable-encryption-preview '

3007

   <note xmlns="http://docbook.org/ns/docbook">

3008

    <simpara>

3009

     Queryable Encryption is in public preview and available for evaluation

3010

     purposes. It is not yet recommended for production deployments as breaking

3011

     changes may be introduced. See the <link xlink:href="https://www.mongodb.com/blog/post/mongodb-releases-queryable-encryption-preview/" xmlns:xlink="http://www.w3.org/1999/xlink">Queryable Encryption Preview</link> blog post for more information.

3012

    </simpara>

3013

   </note>

3014

'>

3670

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

3671

<!ENTITY mongodb.note.queryable-encryption-preview ''>

3015

3672

3016

3673

<!ENTITY mongodb.note.decimal128 '

3017

3674

   <note xmlns="http://docbook.org/ns/docbook">

...

@@ -3039,7 +3696,7 @@ local: {

3039

3696

<!ENTITY mongodb.note.forking '

3040

3697

   <note xmlns="http://docbook.org/ns/docbook">

3041

3698

    <simpara>

3042

     On Unix platforms, the MongoDB driver is sensitive to scripts that use the

3699

     On Unix platforms, the extension is sensitive to scripts that use the

3043

3700

     fork() system call without also calling exec(). Users are advised not to

3044

3701

     re-use <classname>MongoDB\Driver\Manager</classname> instances in a forked

3045

3702

     child process.

...

@@ -3103,7 +3760,7 @@ local: {

3103

3760

3104

3761

<!-- posix snippets -->

3105

3762

<!ENTITY posix.parameter.fd '<varlistentry xmlns="http://docbook.org/ns/docbook">

3106

 <term><parameter>fd</parameter></term>

3763

 <term><parameter>file_descriptor</parameter></term>

3107

3764

 <listitem>

3108

3765

  <para>

3109

3766

   The file descriptor, which is expected to be either a file

...

@@ -3111,9 +3768,6 @@ local: {

3111

3768

   will be assumed to be a file descriptor that can be passed directly to

3112

3769

   the underlying system call.

3113

3770

  </para>

3114

  <para>

3115

   In almost all cases, you will want to provide a file <type>resource</type>.

3116

  </para>

3117

3771

 </listitem>

3118

3772

</varlistentry>'>

3119

3773

...

@@ -3128,18 +3782,216 @@ local: {

3128

3782

'>

3129

3783

3130

3784

<!-- strings snippets -->

3131

<!ENTITY strings.parameter.encoding '

3132

 <para xmlns="http://docbook.org/ns/docbook">

3133

  An optional argument defining the encoding used when converting characters.

3134

 </para>

3135

3136

 <para xmlns="http://docbook.org/ns/docbook">

3137

  If omitted, <parameter>encoding</parameter> defaults to the value of the

3138

  <link linkend="ini.default-charset">default_charset</link> configuration

3139

  option.

3140

 </para>

3785

<!ENTITY strings.stripped.characters '

3786

 <itemizedlist xmlns="http://docbook.org/ns/docbook">

3787

    <listitem>

3788

     <simpara>

3789

      <literal>" "</literal>: <acronym>ASCII</acronym> <acronym>SP</acronym> character

3790

      <literal>0x20</literal>, an ordinary space.

3791

     </simpara>

3792

    </listitem>

3793

    <listitem>

3794

     <simpara>

3795

      <literal>"\t"</literal>: <acronym>ASCII</acronym> <acronym>HT</acronym> character

3796

      <literal>0x09</literal>, a tab.

3797

     </simpara>

3798

    </listitem>

3799

    <listitem>

3800

     <simpara>

3801

      <literal>"\n"</literal>: <acronym>ASCII</acronym> <acronym>LF</acronym> character

3802

      <literal>0x0A</literal>, a new line (line feed).

3803

     </simpara>

3804

    </listitem>

3805

    <listitem>

3806

     <simpara>

3807

      <literal>"\r"</literal>: <acronym>ASCII</acronym> <acronym>CR</acronym> character

3808

      <literal>0x0D</literal>, a carriage return.

3809

     </simpara>

3810

    </listitem>

3811

    <listitem>

3812

     <simpara>

3813

      <literal>"\0"</literal>: <acronym>ASCII</acronym> <acronym>NUL</acronym> character

3814

      <literal>0x00</literal>, the NUL-byte.

3815

     </simpara>

3816

    </listitem>

3817

    <listitem>

3818

     <simpara>

3819

      <literal>"\v"</literal>: <acronym>ASCII</acronym> <acronym>VT</acronym>

3820

      character <literal>0x0B</literal>, a vertical tab.

3821

     </simpara>

3822

    </listitem>

3823

   </itemizedlist>

3824

'>

3141

3825

3142

 <para xmlns="http://docbook.org/ns/docbook">

3826

<!ENTITY strings.stripped.unicode '

3827

 <itemizedlist xmlns="http://docbook.org/ns/docbook">

3828

    <listitem>

3829

     <simpara>

3830

      <literal>" "</literal> (<acronym>Unicode</acronym> U+0020), an ordinary space.

3831

     </simpara>

3832

    </listitem>

3833

    <listitem>

3834

     <simpara>

3835

      <literal>"\t"</literal> (<acronym>Unicode</acronym> U+0009), a tab.

3836

     </simpara>

3837

    </listitem>

3838

    <listitem>

3839

     <simpara>

3840

      <literal>"\n"</literal> (<acronym>Unicode</acronym> U+000A), a new line (line feed).

3841

     </simpara>

3842

    </listitem>

3843

    <listitem>

3844

     <simpara>

3845

      <literal>"\r"</literal> (<acronym>Unicode</acronym> U+000D), a carriage return.

3846

     </simpara>

3847

    </listitem>

3848

    <listitem>

3849

     <simpara>

3850

      <literal>"\0"</literal> (<acronym>Unicode</acronym> U+0000), the NUL-byte.

3851

     </simpara>

3852

    </listitem>

3853

    <listitem>

3854

     <simpara>

3855

      <literal>"\v"</literal> (<acronym>Unicode</acronym> U+000B), a vertical tab.

3856

     </simpara>

3857

    </listitem>

3858

    <listitem>

3859

     <simpara>

3860

      <literal>"\f"</literal> (<acronym>Unicode</acronym> U+000C), a form feed.

3861

     </simpara>

3862

    </listitem>

3863

    <listitem>

3864

     <simpara>

3865

      <literal>"\u00A0"</literal> (<acronym>Unicode</acronym> U+00A0), a NO-BREAK SPACE.

3866

     </simpara>

3867

    </listitem>

3868

    <listitem>

3869

     <simpara>

3870

      <literal>"\u1680"</literal> (<acronym>Unicode</acronym> U+1680), a OGHAM SPACE MARK.

3871

     </simpara>

3872

    </listitem>

3873

    <listitem>

3874

     <simpara>

3875

      <literal>"\u2000"</literal> (<acronym>Unicode</acronym> U+2000), a EN QUAD.

3876

     </simpara>

3877

    </listitem>

3878

    <listitem>

3879

     <simpara>

3880

      <literal>"\u2001"</literal> (<acronym>Unicode</acronym> U+2001), a EM QUAD.

3881

     </simpara>

3882

    </listitem>

3883

    <listitem>

3884

     <simpara>

3885

      <literal>"\u2002"</literal> (<acronym>Unicode</acronym> U+2002), a EN SPACE.

3886

     </simpara>

3887

    </listitem>

3888

    <listitem>

3889

     <simpara>

3890

      <literal>"\u2003"</literal> (<acronym>Unicode</acronym> U+2003), a EM SPACE.

3891

     </simpara>

3892

    </listitem>

3893

    <listitem>

3894

     <simpara>

3895

      <literal>"\u2004"</literal> (<acronym>Unicode</acronym> U+2004), a THREE-PER-EM SPACE.

3896

     </simpara>

3897

    </listitem>

3898

    <listitem>

3899

     <simpara>

3900

      <literal>"\u2005"</literal> (<acronym>Unicode</acronym> U+2005), a FOUR-PER-EM SPACE.

3901

     </simpara>

3902

    </listitem>

3903

    <listitem>

3904

     <simpara>

3905

      <literal>"\u2006"</literal> (<acronym>Unicode</acronym> U+2006), a SIX-PER-EM SPACE.

3906

     </simpara>

3907

    </listitem>

3908

    <listitem>

3909

     <simpara>

3910

     <literal>"\u2007"</literal> (<acronym>Unicode</acronym> U+2007), a FIGURE SPACE.

3911

     </simpara>

3912

    </listitem>

3913

    <listitem>

3914

     <simpara>

3915

     <literal>"\u2008"</literal> (<acronym>Unicode</acronym> U+2008), a PUNCTUATION SPACE.

3916

     </simpara>

3917

    </listitem>

3918

    <listitem>

3919

     <simpara>

3920

     <literal>"\u2009"</literal> (<acronym>Unicode</acronym> U+2009), a THIN SPACE.

3921

     </simpara>

3922

    </listitem>

3923

    <listitem>

3924

     <simpara>

3925

     <literal>"\u200A"</literal> (<acronym>Unicode</acronym> U+200A), a HAIR SPACE.

3926

     </simpara>

3927

    </listitem>

3928

    <listitem>

3929

     <simpara>

3930

     <literal>"\u2028"</literal> (<acronym>Unicode</acronym> U+2028), a LINE SEPARATOR.

3931

     </simpara>

3932

    </listitem>

3933

    <listitem>

3934

     <simpara>

3935

     <literal>"\u2029"</literal> (<acronym>Unicode</acronym> U+2029), a PARAGRAPH SEPARATOR.

3936

     </simpara>

3937

    </listitem>

3938

    <listitem>

3939

     <simpara>

3940

     <literal>"\u202F"</literal> (<acronym>Unicode</acronym> U+202F), a NARROW NO-BREAK SPACE.

3941

     </simpara>

3942

    </listitem>

3943

    <listitem>

3944

     <simpara>

3945

     <literal>"\u205F"</literal> (<acronym>Unicode</acronym> U+205F), a MEDIUM MATHEMATICAL SPACE.

3946

     </simpara>

3947

    </listitem>

3948

    <listitem>

3949

     <simpara>

3950

     <literal>"\u3000"</literal> (<acronym>Unicode</acronym> U+3000), a IDEOGRAPHIC SPACE.

3951

     </simpara>

3952

    </listitem>

3953

    <listitem>

3954

     <simpara>

3955

     <literal>"\u0085"</literal> (<acronym>Unicode</acronym> U+0085), a NEXT LINE (NEL).

3956

     </simpara>

3957

    </listitem>

3958

    <listitem>

3959

     <simpara>

3960

     <literal>"\u180E"</literal> (<acronym>Unicode</acronym> U+180E), a MONGOLIAN VOWEL SEPARATOR.

3961

     </simpara>

3962

    </listitem>

3963

   </itemizedlist>

3964

'>

3965

3966

<!ENTITY strings.parameter.characters.optional '

3967

 <simpara xmlns="http://docbook.org/ns/docbook">

3968

  Optionally, the stripped characters can also be specified using

3969

  the <parameter>characters</parameter> parameter.

3970

  Simply list all characters that need to be stripped.

3971

  With <literal>..</literal> it is possible to specify an incrementing range of characters.

3972

 </simpara>

3973

'>

3974

3975

<!ENTITY strings.parameter.unicode.optional '

3976

 <simpara xmlns="http://docbook.org/ns/docbook">

3977

  Optionally, the stripped characters can also be specified using

3978

  the <parameter>characters</parameter> parameter.

3979

  Simply list all characters that need to be stripped.

3980

 </simpara>

3981

'>

3982

3983

<!ENTITY strings.parameter.encoding '

3984

 <para xmlns="http://docbook.org/ns/docbook">

3985

  An optional argument defining the encoding used when converting characters.

3986

 </para>

3987

3988

 <para xmlns="http://docbook.org/ns/docbook">

3989

  If omitted, <parameter>encoding</parameter> defaults to the value of the

3990

  <link linkend="ini.default-charset">default_charset</link> configuration

3991

  option.

3992

 </para>

3993

3994

 <para xmlns="http://docbook.org/ns/docbook">

3143

3995

  Although this argument is technically optional, you are highly encouraged to

3144

3996

  specify the correct value for your code

3145

3997

  if the <link linkend="ini.default-charset">default_charset</link>

...

@@ -3172,71 +4024,77 @@ local: {

3172

4024

   </para>

3173

4025

  </formalpara>

3174

4026

3175

  <para>

3176

   <table>

3177

    <title>Flags</title>

3178

    <tgroup cols="2">

3179

     <thead>

3180

      <row>

3181

       <entry>Flag</entry>

3182

       <entry>&Description;</entry>

3183

      </row>

3184

     </thead>

3185

     <tbody>

3186

      <row>

3187

       <entry><literal>-</literal></entry>

3188

       <entry>

3189

        Left-justify within the given field width;

3190

        Right justification is the default

3191

       </entry>

3192

      </row>

3193

      <row>

3194

       <entry><literal>+</literal></entry>

3195

       <entry>

3196

        Prefix positive numbers with a plus sign

3197

        <literal>+</literal>; Default only negative

3198

        are prefixed with a negative sign.

3199

       </entry>

3200

      </row>

3201

      <row>

3202

       <entry><literal> </literal>(space)</entry>

3203

       <entry>

3204

        Pads the result with spaces.

3205

        This is the default.

3206

       </entry>

3207

      </row>

3208

      <row>

3209

       <entry><literal>0</literal></entry>

3210

       <entry>

3211

        Only left-pads numbers with zeros.

3212

        With <literal>s</literal> specifiers this can

3213

        also right-pad with zeros.

3214

       </entry>

3215

      </row>

3216

      <row>

3217

       <entry><literal>&apos;</literal>(char)</entry>

3218

       <entry>

3219

        Pads the result with the character (char).

3220

       </entry>

3221

      </row>

3222

     </tbody>

3223

    </tgroup>

3224

   </table>

3225

  </para>

4027

  <formalpara>

4028

   <title>Flags</title>

4029

   <para>

4030

    <informaltable>

4031

     <tgroup cols="2">

4032

      <thead>

4033

       <row>

4034

        <entry>Flag</entry>

4035

        <entry>&Description;</entry>

4036

       </row>

4037

      </thead>

4038

      <tbody>

4039

       <row>

4040

        <entry><literal>-</literal></entry>

4041

        <entry>

4042

         Left-justify within the given field width;

4043

         Right justification is the default

4044

        </entry>

4045

       </row>

4046

       <row>

4047

        <entry><literal>+</literal></entry>

4048

        <entry>

4049

         Prefix positive numbers with a plus sign

4050

         <literal>+</literal>; Default only negative

4051

         are prefixed with a negative sign.

4052

        </entry>

4053

       </row>

4054

       <row>

4055

        <entry><literal> </literal>(space)</entry>

4056

        <entry>

4057

         Pads the result with spaces.

4058

         This is the default.

4059

        </entry>

4060

       </row>

4061

       <row>

4062

        <entry><literal>0</literal></entry>

4063

        <entry>

4064

         Only left-pads numbers with zeros.

4065

         With <literal>s</literal> specifiers this can

4066

         also right-pad with zeros.

4067

        </entry>

4068

       </row>

4069

       <row>

4070

        <entry><literal>&apos;</literal>(char)</entry>

4071

        <entry>

4072

         Pads the result with the character (char).

4073

        </entry>

4074

       </row>

4075

      </tbody>

4076

     </tgroup>

4077

    </informaltable>

4078

   </para>

4079

  </formalpara>

3226

4080

3227

4081

  <formalpara>

3228

4082

   <title>Width</title>

3229

4083

   <para>

3230

    An integer that says how many characters (minimum)

3231

    this conversion should result in.

4084

    Either an integer that says how many characters (minimum)

4085

    this conversion should result in, or <literal>*</literal>.

4086

    If <literal>*</literal> is used, then the width is supplied

4087

    as an additional integer value preceding the one formatted

4088

    by the specifier.

3232

4089

   </para>

3233

4090

  </formalpara>

3234

4091

3235

4092

  <formalpara>

3236

4093

   <title>Precision</title>

3237

4094

   <para>

3238

    A period <literal>.</literal> followed by an integer

3239

    who&apos;s meaning depends on the specifier:

4095

    A period <literal>.</literal> optionally followed by

4096

    either an integer or <literal>*</literal>,

4097

    whose meaning depends on the specifier:

3240

4098

    <itemizedlist>

3241

4099

     <listitem>

3242

4100

      <simpara>

...

@@ -3264,19 +4122,14 @@ local: {

3264

4122

    <note>

3265

4123

     <simpara>

3266

4124

      If the period is specified without an explicit value for precision,

3267

      0 is assumed.

4125

      0 is assumed. If <literal>*</literal> is used, the precision is

4126

      supplied as an additional integer value preceding the one formatted

4127

      by the specifier.

3268

4128

     </simpara>

3269

4129

    </note>

3270

4130

   </para>

3271

4131

  </formalpara>

3272

4132

3273

  <note>

3274

   <simpara>

3275

    Attempting to use a position specifier greater than

3276

    <constant>PHP_INT_MAX</constant> will generate warnings.

3277

   </simpara>

3278

  </note>

3279

3280

4133

  <para>

3281

4134

   <table>

3282

4135

    <title>Specifiers</title>

...

@@ -3421,13 +4274,13 @@ local: {

3421

4274

3422

4275

  <warning>

3423

4276

   <para>

3424

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

4277

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

3425

4278

   </para>

3426

4279

  </warning>

3427

4280

3428

4281

  <warning>

3429

4282

   <para>

3430

    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

4283

    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.

3431

4284

   </para>

3432

4285

  </warning>

3433

4286

...

@@ -3529,6 +4382,13 @@ local: {

3529

4382

 </para>

3530

4383

'>

3531

4384

4385

<!ENTITY strings.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">

4386

 <entry>8.0.0</entry>

4387

 <entry>

4388

  <parameter>needle</parameter> now accepts an empty string.

4389

 </entry>

4390

</row>'>

4391

3532

4392

<!ENTITY strings.changelog.encoding '

3533

4393

 <row xmlns="http://docbook.org/ns/docbook">

3534

4394

  <entry>5.6.0</entry>

...

@@ -3541,19 +4401,193 @@ local: {

3541

4401

 </row>

3542

4402

'>

3543

4403

4404

<!ENTITY strings.changelog.ascii-case-conversion '

4405

 <row xmlns="http://docbook.org/ns/docbook">

4406

  <entry>8.2.0</entry>

4407

  <entry>

4408

   Case conversion no longer depends on the locale set with

4409

   <function>setlocale</function>. Only ASCII characters will be converted.

4410

  </entry>

4411

 </row>

4412

'>

4413

4414

<!ENTITY strings.changelog.ascii-case-folding '

4415

 <row xmlns="http://docbook.org/ns/docbook">

4416

  <entry>8.2.0</entry>

4417

  <entry>

4418

   Case folding no longer depends on the locale set with

4419

   <function>setlocale</function>. Only ASCII case folding will be done.

4420

   Non-ASCII bytes will be compared by their byte value.

4421

  </entry>

4422

 </row>

4423

'>

4424

4425

<!ENTITY strings.changelog.sprintf '

4426

  <informaltable xmlns="http://docbook.org/ns/docbook">

4427

   <tgroup cols="2">

4428

    <thead>

4429

     <row>

4430

      <entry>&Version;</entry>

4431

      <entry>&Description;</entry>

4432

     </row>

4433

    </thead>

4434

    <tbody>

4435

     <row>

4436

      <entry>8.0.0</entry>

4437

      <entry>

4438

       This function no longer returns &false; on failure.

4439

      </entry>

4440

     </row>

4441

     <row>

4442

      <entry>8.0.0</entry>

4443

      <entry>

4444

       Throw a <classname>ValueError</classname> if the number of arguments is zero;

4445

       previously this function emitted a <constant>E_WARNING</constant> instead.

4446

      </entry>

4447

     </row>

4448

     <row>

4449

      <entry>8.0.0</entry>

4450

      <entry>

4451

       Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;

4452

       previously this function emitted a <constant>E_WARNING</constant> instead.

4453

      </entry>

4454

     </row>

4455

     <row>

4456

      <entry>8.0.0</entry>

4457

      <entry>

4458

       Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;

4459

       previously this function emitted a <constant>E_WARNING</constant> instead.

4460

      </entry>

4461

     </row>

4462

     <row>

4463

      <entry>8.0.0</entry>

4464

      <entry>

4465

       Throw a <classname>ArgumentCountError</classname> when less arguments are given than required;

4466

       previously this function emitted a <constant>E_WARNING</constant> instead.

4467

      </entry>

4468

     </row>

4469

    </tbody>

4470

   </tgroup>

4471

  </informaltable>

4472

'>

4473

4474

<!ENTITY strings.changelog.vsprintf '

4475

  <informaltable xmlns="http://docbook.org/ns/docbook">

4476

   <tgroup cols="2">

4477

    <thead>

4478

     <row>

4479

      <entry>&Version;</entry>

4480

      <entry>&Description;</entry>

4481

     </row>

4482

    </thead>

4483

    <tbody>

4484

     <row>

4485

      <entry>8.0.0</entry>

4486

      <entry>

4487

       This function no longer returns &false; on failure.

4488

      </entry>

4489

     </row>

4490

     <row>

4491

      <entry>8.0.0</entry>

4492

      <entry>

4493

       Throw a <classname>ValueError</classname> if the number of arguments is zero;

4494

       previously this function emitted a <constant>E_WARNING</constant> instead.

4495

      </entry>

4496

     </row>

4497

     <row>

4498

      <entry>8.0.0</entry>

4499

      <entry>

4500

       Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;

4501

       previously this function emitted a <constant>E_WARNING</constant> instead.

4502

      </entry>

4503

     </row>

4504

     <row>

4505

      <entry>8.0.0</entry>

4506

      <entry>

4507

       Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;

4508

       previously this function emitted a <constant>E_WARNING</constant> instead.

4509

      </entry>

4510

     </row>

4511

     <row>

4512

      <entry>8.0.0</entry>

4513

      <entry>

4514

       Throw a <classname>ValueError</classname> when less arguments are given than required;

4515

       previously this function emitted a <constant>E_WARNING</constant> instead.

4516

      </entry>

4517

     </row>

4518

    </tbody>

4519

   </tgroup>

4520

  </informaltable>

4521

'>

4522

4523

<!ENTITY strings.errors.sprintf '

4524

  <para xmlns="http://docbook.org/ns/docbook">

4525

   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.

4526

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4527

  </para>

4528

  <para xmlns="http://docbook.org/ns/docbook">

4529

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

4530

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4531

  </para>

4532

  <para xmlns="http://docbook.org/ns/docbook">

4533

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

4534

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4535

  </para>

4536

  <para xmlns="http://docbook.org/ns/docbook">

4537

   As of PHP 8.0.0, a <classname>ArgumentCountError</classname> is thrown when less arguments are given than required.

4538

   Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.

4539

  </para>

4540

'>

4541

4542

<!ENTITY strings.errors.vsprintf '

4543

  <para xmlns="http://docbook.org/ns/docbook">

4544

   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.

4545

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4546

  </para>

4547

  <para xmlns="http://docbook.org/ns/docbook">

4548

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

4549

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4550

  </para>

4551

  <para xmlns="http://docbook.org/ns/docbook">

4552

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

4553

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4554

  </para>

4555

  <para xmlns="http://docbook.org/ns/docbook">

4556

   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown when less arguments are given than required.

4557

   Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.

4558

  </para>

4559

'>

4560

4561

<!ENTITY strings.comparison.return '

4562

  <simpara xmlns="http://docbook.org/ns/docbook">

4563

   Returns a value less than 0 if <parameter>string1</parameter>

4564

   is less than <parameter>string2</parameter>; a value greater

4565

   than 0 if <parameter>string1</parameter> is greater than

4566

   <parameter>string2</parameter>, and <literal>0</literal> if they

4567

   are equal.

4568

   No particular meaning can be reliably inferred from the value aside

4569

   from its sign.

4570

  </simpara>

4571

'>

4572

3544

4573

<!-- filter snippets -->

4574

<!-- TODO: Remove -->

3545

4575

<!ENTITY filter.param.filter '

3546

4576

 <varlistentry xmlns="http://docbook.org/ns/docbook">

3547

4577

  <term><parameter>filter</parameter></term>

3548

4578

  <listitem>

3549

4579

   <para>

3550

    The ID of the filter to apply. The <xref linkend="filter.filters" />

3551

    manual page lists the available filters.

4580

    The filter to apply.

4581

    Can be a validation filter by using one of the

4582

    <constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>

4583

    constants, a sanitization filter by using one of the

4584

    <constant>FILTER_SANITIZE_<replaceable>*</replaceable></constant>

4585

    or <constant>FILTER_UNSAFE_RAW</constant>, or a custom filter by using

4586

    <constant>FILTER_CALLBACK</constant>.

3552

4587

   </para>

3553

4588

   <para>

3554

    If omitted, <constant>FILTER_DEFAULT</constant> will be used, which is

3555

    equivalent to

3556

    <link linkend="filter.filters.sanitize"><constant>FILTER_UNSAFE_RAW</constant></link>.

4589

    The default is <constant>FILTER_DEFAULT</constant>,

4590

    which is an alias of <constant>FILTER_UNSAFE_RAW</constant>.

3557

4591

    This will result in no filtering taking place by default.

3558

4592

   </para>

3559

4593

  </listitem>

...

@@ -3563,34 +4597,65 @@ local: {

3563

4597

<!-- csprng snippets -->

3564

4598

<!ENTITY csprng.sources '

3565

4599

<para xmlns="http://docbook.org/ns/docbook">

3566

 The sources of randomness used for this function are as follows:

4600

 The sources of randomness in the order of priority are as follows:

3567

4601

</para>

3568

4602

<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

3569

4603

 <listitem>

3570

  <simpara>

3571

   On Windows,

3572

   <link xlink:href="&url.csprng.crypt-gen-random;"><function>CryptGenRandom</function></link>

3573

   will always be used. As of PHP 7.2.0, the

3574

   <link xlink:href="&url.csprng.cng-api;">CNG-API</link>

3575

   will always be used instead.

3576

  </simpara>

4604

  <para>

4605

   Linux: <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>

4606

  </para>

3577

4607

 </listitem>

3578

4608

 <listitem>

3579

  <simpara>

3580

   On Linux, the

3581

   <link xlink:href="&url.csprng.get-random-2;">getrandom(2)</link>

3582

   syscall will be used if available.

3583

  </simpara>

4609

  <para>

4610

   FreeBSD &gt;= 12 (PHP &gt;= 7.3): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>

4611

  </para>

4612

 </listitem>

4613

 <listitem>

4614

  <para>

4615

   Windows (PHP &gt;= 7.2): <link xlink:href="&url.csprng.cng-api;">CNG-API</link>

4616

  </para>

4617

  <para>

4618

   Windows: <link xlink:href="&url.csprng.crypt-gen-random;">CryptGenRandom</link>

4619

  </para>

4620

 </listitem>

4621

 <listitem>

4622

  <para>

4623

   macOS (PHP &gt;= 8.2; &gt;= 8.1.9; &gt;= 8.0.22 if CCRandomGenerateBytes is available at compile time): CCRandomGenerateBytes()

4624

  </para>

4625

  <para>

4626

   macOS (PHP &gt;= 8.1; &gt;= 8.0.2): arc4random_buf(), <filename>/dev/urandom</filename>

4627

  </para>

4628

 </listitem>

4629

 <listitem>

4630

  <para>

4631

   NetBSD &gt;= 7 (PHP &gt;= 7.1; &gt;= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>

4632

  </para>

4633

 </listitem>

4634

 <listitem>

4635

  <para>

4636

   OpenBSD &gt;= 5.5 (PHP &gt;= 7.1; &gt;= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>

4637

  </para>

4638

 </listitem>

4639

 <listitem>

4640

  <para>

4641

   DragonflyBSD (PHP &gt;= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>

4642

  </para>

4643

 </listitem>

4644

 <listitem>

4645

  <para>

4646

   Solaris (PHP &gt;= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>

4647

  </para>

3584

4648

 </listitem>

3585

4649

 <listitem>

3586

4650

  <simpara>

3587

   On other platforms, <filename>/dev/urandom</filename> will be used.

4651

   Any combination of operating system and PHP version not previously mentioned: <filename>/dev/urandom</filename>

3588

4652

  </simpara>

3589

4653

 </listitem>

3590

4654

 <listitem>

3591

4655

  <simpara>

3592

   If none of the aforementioned sources are available, then a

3593

   <classname>\Random\RandomException</classname> will be thrown.

4656

   If none of the sources are available or they all fail to generate

4657

   randomness, then a <classname>Random\RandomException</classname>

4658

   will be thrown.

3594

4659

  </simpara>

3595

4660

 </listitem>

3596

4661

</itemizedlist>

...

@@ -3599,13 +4664,7 @@ local: {

3599

4664

 <listitem xmlns="http://docbook.org/ns/docbook">

3600

4665

  <simpara>

3601

4666

   If an appropriate source of randomness cannot be found,

3602

   a <classname>\Random\RandomException</classname> will be thrown.

3603

  </simpara>

3604

 </listitem>

3605

 <listitem xmlns="http://docbook.org/ns/docbook">

3606

  <simpara>

3607

    If invalid parameters are given, a <classname>TypeError</classname>

3608

    will be thrown.

4667

   a <classname>Random\RandomException</classname> will be thrown.

3609

4668

  </simpara>

3610

4669

 </listitem>

3611

4670

'>

...

@@ -3619,6 +4678,15 @@ local: {

3619

4678

 </note>

3620

4679

'>

3621

4680

4681

<!-- Random snippets -->

4682

<!ENTITY random.engineErrors '

4683

 <listitem xmlns="http://docbook.org/ns/docbook">

4684

  <simpara>

4685

   Any <classname>Throwable</classname>s thrown by the <methodname>Random\Engine::generate</methodname> method

4686

   of the underlying <link linkend="random-randomizer.props.engine"><literal>Random\Randomizer::$engine</literal></link>.

4687

  </simpara>

4688

 </listitem>

4689

'>

3622

4690

3623

4691

<!-- UOPZ snippets -->

3624

4692

...

@@ -3627,12 +4695,80 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been

3627

4695

<emphasis>REMOVED</emphasis> in PECL uopz 5.0.0.</simpara></warning>'>

3628

4696

3629

4697

<!-- XML snippets -->

4698

<!ENTITY xml.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">

4699

 <term><parameter>parser</parameter></term>

4700

 <listitem>

4701

  <para>

4702

   The XML parser.

4703

  </para>

4704

 </listitem>

4705

</varlistentry>'>

4706

4707

<!ENTITY xml.handler.description '<para xmlns="http://docbook.org/ns/docbook">

4708

 If &null; is passed, the handler is reset to its default state.

4709

 <warning>

4710

  <simpara>

4711

    An empty string will also reset the handler,

4712

    however this is deprecated as of PHP 8.4.0.

4713

  </simpara>

4714

 </warning>

4715

</para>

4716

<para xmlns="http://docbook.org/ns/docbook">

4717

 If <parameter>handler</parameter> is a <type>callable</type>,

4718

 the callable is set as the handler.

4719

</para>

4720

<para xmlns="http://docbook.org/ns/docbook">

4721

 If <parameter>handler</parameter> is a <type>string</type>,

4722

 it can be the name of a method of an object set with

4723

 <function>xml_set_object</function>.

4724

 <warning>

4725

  <simpara>

4726

   This is deprecated as of PHP 8.4.0.

4727

  </simpara>

4728

 </warning>

4729

</para>

4730

<warning xmlns="http://docbook.org/ns/docbook">

4731

 <simpara>

4732

  As of PHP 8.4.0, the callable is checked to be valid while setting the handler,

4733

  not when it is called.

4734

  This means that <function>xml_set_object</function> must be called prior to

4735

  setting a method string as the callback.

4736

  However, as this behaviour is also deprecated as of PHP 8.4.0,

4737

  using a proper <type>callable</type> for the method is recommended instead.

4738

 </simpara>

4739

</warning>

4740

'>

4741

4742

<!ENTITY xml.handler.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">

4743

 <term><parameter>parser</parameter></term>

4744

 <listitem>

4745

  <simpara>

4746

   The XML parser calling the handler.

4747

  </simpara>

4748

 </listitem>

4749

</varlistentry>'>

4750

4751

<!ENTITY xml.changelog.handler-param '<row xmlns="http://docbook.org/ns/docbook">

4752

 <entry>8.4.0</entry>

4753

 <entry>

4754

  Passing a non-<type>callable</type> <type>string</type> to

4755

  <parameter>handler</parameter> is now deprecated,

4756

  use a proper callable for methods, or &null; to reset the handler.

4757

 </entry>

4758

</row>

4759

<row xmlns="http://docbook.org/ns/docbook">

4760

 <entry>8.4.0</entry>

4761

 <entry>

4762

  The validity of <parameter>handler</parameter> as a <type>callable</type>

4763

  is now checked when setting the handler instead of checking when calling it.

4764

 </entry>

4765

</row>'>

3630

4766

3631

4767

<!ENTITY xml.changelog.parser-param '<row xmlns="http://docbook.org/ns/docbook">

3632

4768

 <entry>8.0.0</entry>

3633

4769

 <entry>

3634

4770

  <parameter>parser</parameter> expects an <classname>XMLParser</classname>

3635

  instance now; previously, a <type>resource</type> was expected.

4771

  instance now; previously, a valid <literal>xml</literal> <type>resource</type> was expected.

3636

4772

 </entry>

3637

4773

</row>'>

3638

4774

3639

4775

Generated: 30 Jun 2025 22:02:58

Translation status