PHP: Documentation Tools

language-snippets.ent
cb6d65ebe2412bbaef6d1edd076911539f1aceda

...

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

233

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

234

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

235

236

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

237

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

238

236

239

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

237

240

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

238

241

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

...

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

334

337

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

335

338

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

336

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

337

344

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

338

345

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

339

346

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

...

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

349

356

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

350

357

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

351

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

352

379

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

353

380

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

354

381

...

@@ -607,6 +634,14 @@ is highly discouraged.</simpara></warning>

607

634

608

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

609

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

610

645

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

611

646

612

647

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

...

@@ -706,6 +741,30 @@ use.</simpara></note>'>

706

741

 </para>

707

742

</caution>'>

708

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

709

768

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

710

769

value is measured in bytes. Shorthand notation, as described

711

770

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

...

@@ -740,14 +799,8 @@ files from the PHP folder into the Windows system directory also works

740

799

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

741

800

<!ENTITY style.procedural 'Procedural style'>

742

801

743

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

744

745

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

746

747

802

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

748

803

749

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

750

751

804

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

752

805

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

753

806

...

@@ -804,8 +857,10 @@ function.</simpara></warning>'>

804

857

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

805

858

 <entry>8.2.0</entry>

806

859

 <entry>

807

  This function now returns <literal>-1</literal> or <literal>1</literal>,

808

  where it previously returned a negative or positive number.

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.

809

864

 </entry>

810

865

</row>

811

866

'>

...

@@ -1018,6 +1073,16 @@ purposes.</simpara></warning>'>

1018

1073

 </entry>

1019

1074

</row>'>

1020

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

1021

1086

<!-- DBM notes -->

1022

1087

1023

1088

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

...

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

1073

1138

 </entry>

1074

1139

</row>'>

1075

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

1076

1151

<!-- dbase notes -->

1077

1152

1078

1153

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

...

@@ -1340,7 +1415,7 @@ encoding value will be used.</para>'>

1340

1415

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

1341

1416

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

1342

1417

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

1343

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

1418

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

1344

1419

   failed.

1345

1420

   </para>

1346

1421

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

...

@@ -1384,11 +1459,11 @@ encoding value will be used.</para>'>

1384

1459

1385

1460

<!-- RNP -->

1386

1461

1387

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

1462

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

1388

1463

1389

1464

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

1390

1465

1391

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

1466

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

1392

1467

1393

1468

<!-- socket entities -->

1394

1469

...

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

1426

1501

1427

1502

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

1428

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

1429

1547

<!-- Date and time entities -->

1430

1548

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

1431

1549

...

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

1518

1636

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

1519

1637

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

1520

1638

1521

<!-- DomXml Notes -->

1522

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

1523

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

1524

1525

1526

1639

<!-- Dom Notes -->

1527

1640

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

1528

1641

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

1529

1642

1530

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

1531

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

1532

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

1533

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

1534

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

1535

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

1536

1701

1537

1702

1538

1703

...

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

1570

1735

</books>

1571

1736

]]></programlisting>'>

1572

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

1573

1860

1574

1861

<!-- FileSystem entities -->

1575

1862

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

...

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

1609

1896

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

1610

1897

1611

1898

<!-- ODBC -->

1612

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

1613

1900

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

1614

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

1615

1908

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

1616

1909

1617

1910

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

...

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

1622

1915

1623

1916

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

1624

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

1625

1978

<!-- OAUTH -->

1626

1979

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

1627

1980

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

...

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

1754

2107

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

1755

2108

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

1756

2109

1757

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

1758

1759

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

1760

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

1761

1762

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

1763

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

1764

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

1765

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

1766

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

1767

1768

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

1769

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

1770

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

1771

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

1772

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

1773

1774

2110

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

1775

2111

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

1776

2112

...

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

1781

2117

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

1782

2118

</note>'>

1783

2119

1784

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

1785

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

1786

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

1787

1788

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

1789

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

1790

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

1791

1792

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

1793

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

1794

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

1795

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

1796

1797

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

1798

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

1799

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

1800

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

1801

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

1802

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

1803

1804

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

1805

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

1806

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

1807

executed.'>

1808

1809

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

1810

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

1811

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

1812

1813

2120

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

1814

2121

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

1815

2122

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

...

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

1830

2137

</simpara>'>

1831

2138

1832

2139

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

1833

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"/>.'>

1834

2141

1835

2142

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

1836

2143

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

...

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

1851

2158

been compiled into PHP or dynamically loaded at runtime.

1852

2159

</simpara>'>

1853

2160

1854

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

1855

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

1856

1857

2161

<!-- PDO entities -->

1858

2162

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

1859

2163

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

...

@@ -1878,11 +2182,9 @@ is set to <constant>PDO::ERRMODE_EXCEPTION</constant>.

1878

2182

</para>'>

1879

2183

1880

2184

<!-- PECL entities -->

1881

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

1882

is not bundled with PHP.'>

2185

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

1883

2186

1884

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

1885

is bundled with PHP.'>

2187

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

1886

2188

1887

2189

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

1888

2190

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

...

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

1908

2210

1909

2211

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

1910

2212

1911

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

1912

<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

1913

PHP as of PHP '>

2213

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

2214

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

2215

2216

<!ENTITY pecl.moving.to.pie '<note xmlns="http://docbook.org/ns/docbook">

2217

 <simpara>

2218

  PHP Installer for Extensions (<acronym>PIE</acronym>) is a new tool that will deprecate PECL.

2219

  We recommend using PIE to install extensions.

2220

  Find out more at <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/php/pie">https://github.com/php/pie</link>

2221

 </simpara>

2222

</note>'>

2223

2224

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

2225

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

2226

</warning>'>

1914

2227

1915

2228

<!-- PGSQL entities -->

1916

2229

...

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

1985

2298

1986

2299

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

1987

2300

1988

<!-- APD Notes -->

1989

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

1990

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

1991

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

1992

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

1993

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

1994

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

1995

</listitem></varlistentry>'>

1996

1997

<!-- BCMath Notes -->

1998

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

1999

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

2000

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

2001

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

2002

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

2003

2004

2301

<!-- CTYPE Notes -->

2005

2302

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

2006

2303

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

...

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

2028

2325

2029

2326

<!-- GMP Notes -->

2030

2327

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

2031

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

2328

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

2329

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

2330

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

2331

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

2332

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

2333

</para>'>

2032

2334

2033

2335

<!-- MySQLi Notes -->

2034

2336

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

...

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

2121

2423

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

2122

2424

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

2123

2425

2124

<!-- MSQL Notes -->

2125

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

2126

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

2127

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

2128

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

2129

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

2130

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

2131

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

2132

2133

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

2134

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

2135

is being evaluated. This result comes from a call to

2136

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

2137

2138

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

2139

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

2140

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

2141

2142

2143

2426

<!-- MySQL Notes -->

2144

2427

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

2145

2428

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

...

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

2207

2490

improve performance. For related information, see

2208

2491

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

2209

2492

2210

<!-- Sybase Notes -->

2211

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

2212

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

2213

</simpara></note>'>

2214

2215

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

2216

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

2217

2218

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

2219

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

2220

link identifier is not specified, the last link opened by

2221

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

2222

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

2223

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

2224

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

2225

</varlistentry>'>

2226

2227

<!-- CPDF Notes -->

2228

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

2229

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

2230

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

2231

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

2232

2233

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

2234

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

2235

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

2236

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

2237

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

2238

</listitem></varlistentry>'>

2239

2240

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

2241

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

2242

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

2243

2244

2493

<!-- Xattr entities -->

2245

2494

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

2246

2495

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

...

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

2253

2502

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

2254

2503

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

2255

2504

2256

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

2257

</simpara></note>'>

2258

2259

2505

<!-- Notes for tidy -->

2260

2506

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

2261

2507

...

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

2280

2526

the default MPM with Apache 2.0 and 2.2.

2281

2527

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

2282

2528

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

2529

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

2530

 <para>

2531

  Builds from third-parties are considered unofficial and not directly

2532

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

2533

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

2534

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

2535

  area</link>.

2536

 </para>

2537

</warning>'>

2283

2538

2284

2539

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

2285

2540

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

...

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

2290

2545

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

2291

2546

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

2292

2547

2293

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

2294

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

2548

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

2295

2549

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

2296

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

2550

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

2297

2551

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

2298

2552

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

2299

2553

alphabetical order.

...

@@ -2317,23 +2571,11 @@ into managing user notes:'>

2317

2571

2318

2572

<!ENTITY listendand ' and'>

2319

2573

2320

<!-- classkit and runkit entities -->

2321

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

2322

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

2323

</note>'>

2324

2574

<!-- runkit entities -->

2325

2575

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

2326

2576

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

2327

2577

</note>'>

2328

2578

2329

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

2330

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

2331

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

2332

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

2333

safety be enabled.

2334

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

2335

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

2336

2337

2579

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

2338

2580

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

2339

2581

override internal functions, you must enable the

...

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

2478

2720

</para>

2479

2721

</note>

2480

2722

'>

2481

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

2482

 <simpara>

2483

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

2484

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

2485

 </simpara>

2486

</note>

2487

'>

2488

2723

2489

2724

<!-- phar -->

2490

2725

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

...

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

2492

2727

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

2493

2728

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

2494

2729

2495

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

2496

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

2497

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

2498

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

2499

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

2500

2501

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

2502

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

2503

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

2504

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

2505

2506

2730

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

2507

2731

 <simpara>

2508

2732

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

...

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

2545

2769

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

2546

2770

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

2547

2771

2772

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

2773

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

2774

2548

2775

<!-- Gmagick -->

2549

2776

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

2550

2777

<!ENTITY gmagick.gmagickexception.throw 'Throws an

...

@@ -2591,25 +2818,6 @@ to be references, then they must be references in the passed argument list.'>

2591

2818

</listitem>

2592

2819

</varlistentry>'>

2593

2820

2594

<!-- SPL -->

2595

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

2596

2597

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

2598

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

2599

2600

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

2601

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

2602

2603

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

2604

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

2605

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

2606

2607

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

2608

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

2609

2610

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

2611

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

2612

2613

2821

<!-- ZIP -->

2614

2822

<!ENTITY zip.filename.separator '<note xmlns="http://docbook.org/ns/docbook"><simpara>For maximum portability, it is recommended to always use forward slashes (<literal>/</literal>) as directory separator in ZIP filenames.</simpara></note>'>

2615

2823

...

@@ -2715,7 +2923,7 @@ system call.</para></listitem>

2715

2923

</varlistentry>

2716

2924

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

2717

2925

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

2718

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

2926

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

2719

2927

</varlistentry>

2720

2928

</variablelist>

2721

2929

</para>

...

@@ -2760,7 +2968,7 @@ paths</simpara></warning>

2760

2968

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

2761

2969

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

2762

2970

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

2763

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

2971

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

2764

2972

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

2765

2973

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

2766

2974

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

...

@@ -2769,84 +2977,80 @@ paths</simpara></warning>

2769

2977

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

2770

2978

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

2771

2979

2772

<!-- Mongo -->

2773

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

2774

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

2775

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

2776

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

2777

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

2778

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

2779

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

2780

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

2781

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

2782

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

2783

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

2784

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

2785

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

2786

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

2787

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

2788

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

2789

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

2790

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

2791

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

2792

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

2793

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

2794

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

2795

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

2796

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

2797

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

2798

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

2799

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

2800

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

2801

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

2802

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

2803

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

2804

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

2805

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

2806

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

2807

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

2808

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

2809

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

2810

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

2811

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

2812

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

2813

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

2814

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

2815

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

2816

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

2817

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

2818

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

2819

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

2820

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

2821

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

2822

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

2823

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

2824

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

2825

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

2826

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

2827

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

2828

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

2829

2830

<!ENTITY mongo.deprecated.note '<para

2831

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

2832

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

2833

used.</para>'>

2834

2835

2980

<!-- mongodb -->

2836

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

2981

<!ENTITY mongodb.changelog.class-removed '

2837

2982

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

2838

        <entry>PECL mongodb 1.15.0</entry>

2983

        <entry>PECL mongodb 2.0.0</entry>

2839

2984

        <entry>

2840

         Return types for methods are declared as tentative on PHP 8.0 and newer,

2841

         triggering deprecation notices in code that implements this interface

2842

         without declaring the appropriate return types. The <code>#[ReturnTypeWillChange]</code>

2843

         attribute can be added to silence the deprecation notice.

2985

         This class was removed.

2844

2986

        </entry>

2845

2987

       </row>

2846

2988

'>

2847

2989

2848

<!ENTITY mongodb.option.collation '

2849

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

2990

<!ENTITY mongodb.changelog.function-removed '

2991

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

2992

        <entry>PECL mongodb 2.0.0</entry>

2993

        <entry>

2994

         This function was removed.

2995

        </entry>

2996

       </row>

2997

'>

2998

2999

<!ENTITY mongodb.changelog.method-removed '

3000

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

3001

        <entry>PECL mongodb 2.0.0</entry>

3002

        <entry>

3003

         This method was removed.

3004

        </entry>

3005

       </row>

3006

'>

3007

3008

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

3009

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

3010

        <entry>PECL mongodb 2.0.0</entry>

3011

        <entry>

3012

         <para>

3013

          This class no longer implements the

3014

          <interfacename>Serializable</interfacename> interface.

3015

         </para>

3016

        </entry>

3017

       </row>

3018

'>

3019

3020

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

3021

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

3022

        <entry>PECL mongodb 1.15.0</entry>

3023

        <entry>

3024

         Return types for methods are declared as tentative on PHP 8.0 and newer,

3025

         triggering deprecation notices in code that implements this interface

3026

         without declaring the appropriate return types. The <code>#[ReturnTypeWillChange]</code>

3027

         attribute can be added to silence the deprecation notice.

3028

        </entry>

3029

       </row>

3030

'>

3031

3032

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

3033

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

3034

        <entry>PECL mongodb 2.0.0</entry>

3035

        <entry>

3036

         Return types previously declared as tentative are now enforced.

3037

        </entry>

3038

       </row>

3039

'>

3040

3041

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

3042

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

3043

        <entry>PECL mongodb 2.0.0</entry>

3044

        <entry>

3045

         <para>

3046

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

3047

         </para>

3048

        </entry>

3049

       </row>

3050

'>

3051

3052

<!ENTITY mongodb.option.collation '

3053

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

2850

3054

          <entry>collation</entry>

2851

3055

          <entry><type class="union"><type>array</type><type>object</type></type></entry>

2852

3056

          <entry>

...

@@ -2891,13 +3095,19 @@ used.</para>'>

2891

3095

         </row>

2892

3096

'>

2893

3097

<!ENTITY mongodb.option.encryption.kmsProviders '

2894

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

3098

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

2895

3099

          <entry>kmsProviders</entry>

2896

3100

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

2897

3101

          <entry>

2898

3102

           <para>

2899

3103

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

2900

3104

           </para>

3105

           <para>

3106

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

3107

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

3108

            will attempt to configure the provider using

3109

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

3110

           </para>

2901

3111

           <para>

2902

3112

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

2903

3113

           </para>

...

@@ -3090,6 +3300,11 @@ local: {

3090

3300

       <entry>string</entry>

3091

3301

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

3092

3302

      </row>

3303

      <row>

3304

       <entry>delegated</entry>

3305

       <entry>bool</entry>

3306

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

3307

      </row>

3093

3308

     </tbody>

3094

3309

    </tgroup>

3095

3310

   </table>

...

@@ -3224,6 +3439,16 @@ local: {

3224

3439

    </listitem>

3225

3440

   </varlistentry>

3226

3441

'>

3442

<!ENTITY mongodb.parameter.bulkwritecommand '

3443

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

3444

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

3445

    <listitem>

3446

     <para>

3447

      The write(s) to execute.

3448

     </para>

3449

    </listitem>

3450

   </varlistentry>

3451

'>

3227

3452

<!ENTITY mongodb.parameter.command '

3228

3453

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

3229

3454

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

...

@@ -3234,6 +3459,172 @@ local: {

3234

3459

    </listitem>

3235

3460

   </varlistentry>

3236

3461

'>

3462

<!ENTITY mongodb.parameter.encryptOpts '

3463

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

3464

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

3465

    <listitem>

3466

     <para>

3467

      <table>

3468

       <title>Encryption options</title>

3469

       <tgroup cols="3">

3470

        <thead>

3471

         <row>

3472

          <entry>Option</entry>

3473

          <entry>Type</entry>

3474

          <entry>Description</entry>

3475

         </row>

3476

        </thead>

3477

        <tbody>

3478

         <row>

3479

          <entry>algorithm</entry>

3480

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

3481

          <entry>

3482

           <para>

3483

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

3484

            Specify one of the following

3485

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

3486

           </para>

3487

           <simplelist>

3488

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

3489

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

3490

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

3491

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

3492

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

3493

           </simplelist>

3494

          </entry>

3495

         </row>

3496

         <row>

3497

          <entry>contentionFactor</entry>

3498

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

3499

          <entry>

3500

           <para>

3501

            The contention factor for evaluating queries with indexed, encrypted

3502

            payloads.

3503

           </para>

3504

           <para>

3505

            This option only applies and may only be specified when

3506

            <literal>algorithm</literal> is

3507

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

3508

or

3509

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

3510

           </para>

3511

          </entry>

3512

         </row>

3513

         <row>

3514

          <entry>keyAltName</entry>

3515

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

3516

          <entry>

3517

           <para>

3518

            Identifies a key vault collection document by

3519

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

3520

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

3521

           </para>

3522

          </entry>

3523

         </row>

3524

         <row>

3525

          <entry>keyId</entry>

3526

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

3527

          <entry>

3528

           <para>

3529

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

3530

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

3531

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

3532

           </para>

3533

          </entry>

3534

         </row>

3535

         <row>

3536

          <entry>queryType</entry>

3537

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

3538

          <entry>

3539

           <para>

3540

            The query type for evaluating queries with indexed, encrypted

3541

            payloads. Specify one of the following

3542

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

3543

           </para>

3544

           <simplelist>

3545

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

3546

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

3547

           </simplelist>

3548

           <para>

3549

            This option only applies and may only be specified when

3550

            <literal>algorithm</literal> is

3551

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

3552

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

3553

           </para>

3554

          </entry>

3555

         </row>

3556

         <row>

3557

          <entry>rangeOpts</entry>

3558

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

3559

          <entry>

3560

           <para>

3561

            Index options for a queryable encryption field supporting "range"

3562

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

3563

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

3564

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

3565

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

3566

            set, or all be unset.

3567

           </para>

3568

           <para>

3569

            <table>

3570

             <title>Range index options</title>

3571

             <tgroup cols="3">

3572

              <thead>

3573

               <row>

3574

                <entry>Option</entry>

3575

                <entry>Type</entry>

3576

                <entry>Description</entry>

3577

               </row>

3578

              </thead>

3579

              <tbody>

3580

               <row>

3581

                <entry>min</entry>

3582

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

3583

                <entry>

3584

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

3585

                 BSON value of the range.

3586

                </entry>

3587

               </row>

3588

               <row>

3589

                <entry>max</entry>

3590

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

3591

                <entry>

3592

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

3593

                 BSON value of the range.

3594

                </entry>

3595

               </row>

3596

               <row>

3597

                <entry>sparsity</entry>

3598

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

3599

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

3600

               </row>

3601

               <row>

3602

                <entry>precision</entry>

3603

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

3604

                <entry>

3605

                 Optional. Positive 32-bit integer specifying precision to use

3606

                 for explicit encryption. May only be set for double or

3607

                 decimal128 BSON field types.

3608

                </entry>

3609

               </row>

3610

               <row>

3611

                <entry>trimFactor</entry>

3612

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

3613

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

3614

               </row>

3615

              </tbody>

3616

             </tgroup>

3617

            </table>

3618

           </para>

3619

          </entry>

3620

         </row>

3621

        </tbody>

3622

       </tgroup>

3623

      </table>

3624

     </para>

3625

    </listitem>

3626

   </varlistentry>

3627

'>

3237

3628

<!ENTITY mongodb.parameter.query '

3238

3629

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

3239

3630

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

...

@@ -3264,7 +3655,7 @@ local: {

3264

3655

     </para>

3265

3656

     <note>

3266

3657

      <simpara>

3267

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

3658

       When evaluating query criteria, MongoDB compares types and values according to its own <link xlink:href="&url.mongodb.docs;reference/bson-type-comparison-order/" xmlns:xlink="http://www.w3.org/1999/xlink">comparison rules for BSON types</link>, which differs from PHP&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>).

3268

3659

      </simpara>

3269

3660

     </note>

3270

3661

    </listitem>

...

@@ -3272,24 +3663,20 @@ local: {

3272

3663

'>

3273

3664

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

3274

3665

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

3666

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

3275

3667

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

3276

3668

<!ENTITY mongodb.throws.session-readwriteconcern '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if the <literal>"session"</literal> option is used with an associated transaction in combination with a <literal>"readConcern"</literal> or <literal>"writeConcern"</literal> option.</member>'>

3277

3669

<!ENTITY mongodb.throws.session-unacknowledged '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if the <literal>"session"</literal> option is used in combination with an unacknowledged write concern.</member>'>

3670

<!ENTITY mongodb.throws.bulkwritecommandexception '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\BulkWriteCommandException</classname> on any write failure (e.g. command failure, write or write concern error)</member>'>

3278

3671

<!ENTITY mongodb.throws.bulkwriteexception '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\BulkWriteException</classname> on any write failure (e.g. write error, failure to apply a write concern)</member>'>

3279

3672

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

3280

3673

<!ENTITY mongodb.throws.authentication '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\AuthenticationException</classname> if authentication is needed and fails.</member>'>

3281

3674

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

3282

3675

<!ENTITY mongodb.throws.bson.unexpected '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname> if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected <link xlink:href="&url.mongodb.libbson;" xmlns:xlink="http://www.w3.org/1999/xlink">libbson</link> error.</member>'>

3676

<!ENTITY mongodb.throws.unacknowledged '<member xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoDB\Driver\Exception\LogicException</classname> if the write was not acknowledged.</member>'>

3283

3677

3284

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

3285

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

3286

    <simpara>

3287

     Queryable Encryption is in public preview and available for evaluation

3288

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

3289

     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.

3290

    </simpara>

3291

   </note>

3292

'>

3678

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

3679

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

3293

3680

3294

3681

<!ENTITY mongodb.note.decimal128 '

3295

3682

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

...

@@ -3317,7 +3704,7 @@ local: {

3317

3704

<!ENTITY mongodb.note.forking '

3318

3705

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

3319

3706

    <simpara>

3320

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

3707

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

3321

3708

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

3322

3709

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

3323

3710

     child process.

...

@@ -3381,7 +3768,7 @@ local: {

3381

3768

3382

3769

<!-- posix snippets -->

3383

3770

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

3384

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

3771

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

3385

3772

 <listitem>

3386

3773

  <para>

3387

3774

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

...

@@ -3389,9 +3776,6 @@ local: {

3389

3776

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

3390

3777

   the underlying system call.

3391

3778

  </para>

3392

  <para>

3393

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

3394

  </para>

3395

3779

 </listitem>

3396

3780

</varlistentry>'>

3397

3781

...

@@ -3406,6 +3790,204 @@ local: {

3406

3790

'>

3407

3791

3408

3792

<!-- strings snippets -->

3793

<!ENTITY strings.stripped.characters '

3794

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

3795

    <listitem>

3796

     <simpara>

3797

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

3798

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

3799

     </simpara>

3800

    </listitem>

3801

    <listitem>

3802

     <simpara>

3803

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

3804

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

3805

     </simpara>

3806

    </listitem>

3807

    <listitem>

3808

     <simpara>

3809

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

3810

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

3811

     </simpara>

3812

    </listitem>

3813

    <listitem>

3814

     <simpara>

3815

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

3816

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

3817

     </simpara>

3818

    </listitem>

3819

    <listitem>

3820

     <simpara>

3821

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

3822

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

3823

     </simpara>

3824

    </listitem>

3825

    <listitem>

3826

     <simpara>

3827

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

3828

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

3829

     </simpara>

3830

    </listitem>

3831

   </itemizedlist>

3832

'>

3833

3834

<!ENTITY strings.stripped.unicode '

3835

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

3836

    <listitem>

3837

     <simpara>

3838

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

3839

     </simpara>

3840

    </listitem>

3841

    <listitem>

3842

     <simpara>

3843

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

3844

     </simpara>

3845

    </listitem>

3846

    <listitem>

3847

     <simpara>

3848

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

3849

     </simpara>

3850

    </listitem>

3851

    <listitem>

3852

     <simpara>

3853

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

3854

     </simpara>

3855

    </listitem>

3856

    <listitem>

3857

     <simpara>

3858

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

3859

     </simpara>

3860

    </listitem>

3861

    <listitem>

3862

     <simpara>

3863

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

3864

     </simpara>

3865

    </listitem>

3866

    <listitem>

3867

     <simpara>

3868

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

3869

     </simpara>

3870

    </listitem>

3871

    <listitem>

3872

     <simpara>

3873

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

3874

     </simpara>

3875

    </listitem>

3876

    <listitem>

3877

     <simpara>

3878

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

3879

     </simpara>

3880

    </listitem>

3881

    <listitem>

3882

     <simpara>

3883

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

3884

     </simpara>

3885

    </listitem>

3886

    <listitem>

3887

     <simpara>

3888

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

3889

     </simpara>

3890

    </listitem>

3891

    <listitem>

3892

     <simpara>

3893

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

3894

     </simpara>

3895

    </listitem>

3896

    <listitem>

3897

     <simpara>

3898

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

3899

     </simpara>

3900

    </listitem>

3901

    <listitem>

3902

     <simpara>

3903

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

3904

     </simpara>

3905

    </listitem>

3906

    <listitem>

3907

     <simpara>

3908

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

3909

     </simpara>

3910

    </listitem>

3911

    <listitem>

3912

     <simpara>

3913

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

3914

     </simpara>

3915

    </listitem>

3916

    <listitem>

3917

     <simpara>

3918

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

3919

     </simpara>

3920

    </listitem>

3921

    <listitem>

3922

     <simpara>

3923

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

3924

     </simpara>

3925

    </listitem>

3926

    <listitem>

3927

     <simpara>

3928

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

3929

     </simpara>

3930

    </listitem>

3931

    <listitem>

3932

     <simpara>

3933

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

3934

     </simpara>

3935

    </listitem>

3936

    <listitem>

3937

     <simpara>

3938

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

3939

     </simpara>

3940

    </listitem>

3941

    <listitem>

3942

     <simpara>

3943

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

3944

     </simpara>

3945

    </listitem>

3946

    <listitem>

3947

     <simpara>

3948

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

3949

     </simpara>

3950

    </listitem>

3951

    <listitem>

3952

     <simpara>

3953

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

3954

     </simpara>

3955

    </listitem>

3956

    <listitem>

3957

     <simpara>

3958

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

3959

     </simpara>

3960

    </listitem>

3961

    <listitem>

3962

     <simpara>

3963

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

3964

     </simpara>

3965

    </listitem>

3966

    <listitem>

3967

     <simpara>

3968

     <literal>"\u180E"</literal> (<acronym>Unicode</acronym> U+180E), a MONGOLIAN VOWEL SEPARATOR.

3969

     </simpara>

3970

    </listitem>

3971

   </itemizedlist>

3972

'>

3973

3974

<!ENTITY strings.parameter.characters.optional '

3975

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

3976

  Optionally, the stripped characters can also be specified using

3977

  the <parameter>characters</parameter> parameter.

3978

  Simply list all characters that need to be stripped.

3979

  With <literal>..</literal> it is possible to specify an incrementing range of characters.

3980

 </simpara>

3981

'>

3982

3983

<!ENTITY strings.parameter.unicode.optional '

3984

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

3985

  Optionally, the stripped characters can also be specified using

3986

  the <parameter>characters</parameter> parameter.

3987

  Simply list all characters that need to be stripped.

3988

 </simpara>

3989

'>

3990

3409

3991

<!ENTITY strings.parameter.encoding '

3410

3992

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

3411

3993

  An optional argument defining the encoding used when converting characters.

...

@@ -3450,57 +4032,59 @@ local: {

3450

4032

   </para>

3451

4033

  </formalpara>

3452

4034

3453

  <para>

3454

   <table>

3455

    <title>Flags</title>

3456

    <tgroup cols="2">

3457

     <thead>

3458

      <row>

3459

       <entry>Flag</entry>

3460

       <entry>&Description;</entry>

3461

      </row>

3462

     </thead>

3463

     <tbody>

3464

      <row>

3465

       <entry><literal>-</literal></entry>

3466

       <entry>

3467

        Left-justify within the given field width;

3468

        Right justification is the default

3469

       </entry>

3470

      </row>

3471

      <row>

3472

       <entry><literal>+</literal></entry>

3473

       <entry>

3474

        Prefix positive numbers with a plus sign

3475

        <literal>+</literal>; Default only negative

3476

        are prefixed with a negative sign.

3477

       </entry>

3478

      </row>

3479

      <row>

3480

       <entry><literal> </literal>(space)</entry>

3481

       <entry>

3482

        Pads the result with spaces.

3483

        This is the default.

3484

       </entry>

3485

      </row>

3486

      <row>

3487

       <entry><literal>0</literal></entry>

3488

       <entry>

3489

        Only left-pads numbers with zeros.

3490

        With <literal>s</literal> specifiers this can

3491

        also right-pad with zeros.

3492

       </entry>

3493

      </row>

3494

      <row>

3495

       <entry><literal>&apos;</literal>(char)</entry>

3496

       <entry>

3497

        Pads the result with the character (char).

3498

       </entry>

3499

      </row>

3500

     </tbody>

3501

    </tgroup>

3502

   </table>

3503

  </para>

4035

  <formalpara>

4036

   <title>Flags</title>

4037

   <para>

4038

    <informaltable>

4039

     <tgroup cols="2">

4040

      <thead>

4041

       <row>

4042

        <entry>Flag</entry>

4043

        <entry>&Description;</entry>

4044

       </row>

4045

      </thead>

4046

      <tbody>

4047

       <row>

4048

        <entry><literal>-</literal></entry>

4049

        <entry>

4050

         Left-justify within the given field width;

4051

         Right justification is the default

4052

        </entry>

4053

       </row>

4054

       <row>

4055

        <entry><literal>+</literal></entry>

4056

        <entry>

4057

         Prefix positive numbers with a plus sign

4058

         <literal>+</literal>; Default only negative

4059

         are prefixed with a negative sign.

4060

        </entry>

4061

       </row>

4062

       <row>

4063

        <entry><literal> </literal>(space)</entry>

4064

        <entry>

4065

         Pads the result with spaces.

4066

         This is the default.

4067

        </entry>

4068

       </row>

4069

       <row>

4070

        <entry><literal>0</literal></entry>

4071

        <entry>

4072

         Only left-pads numbers with zeros.

4073

         With <literal>s</literal> specifiers this can

4074

         also right-pad with zeros.

4075

        </entry>

4076

       </row>

4077

       <row>

4078

        <entry><literal>&apos;</literal>(char)</entry>

4079

        <entry>

4080

         Pads the result with the character (char).

4081

        </entry>

4082

       </row>

4083

      </tbody>

4084

     </tgroup>

4085

    </informaltable>

4086

   </para>

4087

  </formalpara>

3504

4088

3505

4089

  <formalpara>

3506

4090

   <title>Width</title>

...

@@ -3698,13 +4282,13 @@ local: {

3698

4282

3699

4283

  <warning>

3700

4284

   <para>

3701

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

4285

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

3702

4286

   </para>

3703

4287

  </warning>

3704

4288

3705

4289

  <warning>

3706

4290

   <para>

3707

    Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results

4291

    Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results.

3708

4292

   </para>

3709

4293

  </warning>

3710

4294

...

@@ -3806,6 +4390,13 @@ local: {

3806

4390

 </para>

3807

4391

'>

3808

4392

4393

<!ENTITY strings.changelog.needle-empty '<row xmlns="http://docbook.org/ns/docbook">

4394

 <entry>8.0.0</entry>

4395

 <entry>

4396

  <parameter>needle</parameter> now accepts an empty string.

4397

 </entry>

4398

</row>'>

4399

3809

4400

<!ENTITY strings.changelog.encoding '

3810

4401

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

3811

4402

  <entry>5.6.0</entry>

...

@@ -3975,19 +4566,36 @@ local: {

3975

4566

  </para>

3976

4567

'>

3977

4568

4569

<!ENTITY strings.comparison.return '

4570

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

4571

   Returns a value less than 0 if <parameter>string1</parameter>

4572

   is less than <parameter>string2</parameter>; a value greater

4573

   than 0 if <parameter>string1</parameter> is greater than

4574

   <parameter>string2</parameter>, and <literal>0</literal> if they

4575

   are equal.

4576

   No particular meaning can be reliably inferred from the value aside

4577

   from its sign.

4578

  </simpara>

4579

'>

4580

3978

4581

<!-- filter snippets -->

4582

<!-- TODO: Remove -->

3979

4583

<!ENTITY filter.param.filter '

3980

4584

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

3981

4585

  <term><parameter>filter</parameter></term>

3982

4586

  <listitem>

3983

4587

   <para>

3984

    The ID of the filter to apply. The <xref linkend="filter.filters" />

3985

    manual page lists the available filters.

4588

    The filter to apply.

4589

    Can be a validation filter by using one of the

4590

    <constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>

4591

    constants, a sanitization filter by using one of the

4592

    <constant>FILTER_SANITIZE_<replaceable>*</replaceable></constant>

4593

    or <constant>FILTER_UNSAFE_RAW</constant>, or a custom filter by using

4594

    <constant>FILTER_CALLBACK</constant>.

3986

4595

   </para>

3987

4596

   <para>

3988

    If omitted, <constant>FILTER_DEFAULT</constant> will be used, which is

3989

    equivalent to

3990

    <link linkend="filter.filters.sanitize"><constant>FILTER_UNSAFE_RAW</constant></link>.

4597

    The default is <constant>FILTER_DEFAULT</constant>,

4598

    which is an alias of <constant>FILTER_UNSAFE_RAW</constant>.

3991

4599

    This will result in no filtering taking place by default.

3992

4600

   </para>

3993

4601

  </listitem>

...

@@ -4095,6 +4703,74 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been

4095

4703

<emphasis>REMOVED</emphasis> in PECL uopz 5.0.0.</simpara></warning>'>

4096

4704

4097

4705

<!-- XML snippets -->

4706

<!ENTITY xml.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">

4707

 <term><parameter>parser</parameter></term>

4708

 <listitem>

4709

  <para>

4710

   The XML parser.

4711

  </para>

4712

 </listitem>

4713

</varlistentry>'>

4714

4715

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

4716

 If &null; is passed, the handler is reset to its default state.

4717

 <warning>

4718

  <simpara>

4719

    An empty string will also reset the handler,

4720

    however this is deprecated as of PHP 8.4.0.

4721

  </simpara>

4722

 </warning>

4723

</para>

4724

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

4725

 If <parameter>handler</parameter> is a <type>callable</type>,

4726

 the callable is set as the handler.

4727

</para>

4728

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

4729

 If <parameter>handler</parameter> is a <type>string</type>,

4730

 it can be the name of a method of an object set with

4731

 <function>xml_set_object</function>.

4732

 <warning>

4733

  <simpara>

4734

   This is deprecated as of PHP 8.4.0.

4735

  </simpara>

4736

 </warning>

4737

</para>

4738

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

4739

 <simpara>

4740

  As of PHP 8.4.0, the callable is checked to be valid while setting the handler,

4741

  not when it is called.

4742

  This means that <function>xml_set_object</function> must be called prior to

4743

  setting a method string as the callback.

4744

  However, as this behaviour is also deprecated as of PHP 8.4.0,

4745

  using a proper <type>callable</type> for the method is recommended instead.

4746

 </simpara>

4747

</warning>

4748

'>

4749

4750

<!ENTITY xml.handler.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">

4751

 <term><parameter>parser</parameter></term>

4752

 <listitem>

4753

  <simpara>

4754

   The XML parser calling the handler.

4755

  </simpara>

4756

 </listitem>

4757

</varlistentry>'>

4758

4759

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

4760

 <entry>8.4.0</entry>

4761

 <entry>

4762

  Passing a non-<type>callable</type> <type>string</type> to

4763

  <parameter>handler</parameter> is now deprecated,

4764

  use a proper callable for methods, or &null; to reset the handler.

4765

 </entry>

4766

</row>

4767

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

4768

 <entry>8.4.0</entry>

4769

 <entry>

4770

  The validity of <parameter>handler</parameter> as a <type>callable</type>

4771

  is now checked when setting the handler instead of checking when calling it.

4772

 </entry>

4773

</row>'>

4098

4774

4099

4775

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

4100

4776

 <entry>8.0.0</entry>

4101

4777

Generated: 04 Jul 2025 02:02:39

Translation status