PHP: Documentation Tools

language-snippets.ent
cb6d65ebe2412bbaef6d1edd076911539f1aceda

...

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

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

<!-- Cautions -->

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

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

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

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

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

 <para>

  This function does not generate cryptographically secure values, and <emphasis>must not</emphasis>

  be used for cryptographic purposes, or purposes that require returned values to be unguessable.

 </para>

 <para>

  If cryptographically secure randomness is required, the <classname>Random\Randomizer</classname> may be

  used with the <classname>Random\Engine\Secure</classname> engine. For simple use cases, the <function>random_int</function>

  and <function>random_bytes</function> functions provide a convenient and secure <acronym>API</acronym> that is backed by

  the operating system’s <acronym>CSPRNG</acronym>.

 </para>

</caution>'>

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

 <para>

  Because the Mt19937 (“Mersenne Twister”) engine accepts only a single 32 bit integer as the

  seed, the number of possible random sequences is limited to just 2<superscript>32</superscript>

  (i.e. 4,294,967,296), despite Mt19937’s huge period of 2<superscript>19937</superscript>-1.

 </para>

 <para>

  When relying on either implicit or explicit random seeding, duplications will appear

  much earlier. Duplicated seeds are expected with 50&#37; probability after less than

  80,000 randomly generated seeds according to the birthday problem. A 10&#37; probability

  of a duplicated seed happens after randomly generating roughly 30,000 seeds.

 </para>

 <para>

  This makes Mt19937 unsuitable for applications where duplicated sequences must not happen with

  more than a negligible probability. If reproducible seeding is required, both the

  <classname>Random\Engine\Xoshiro256StarStar</classname> and <classname>Random\Engine\PcgOneseq128XslRr64</classname>

  engines support much larger seeds that are unlikely to collide randomly. If reproducibility

  is not required, the <classname>Random\Engine\Secure</classname> engine provides cryptographically

  secure randomness.

 </para>

</caution>'>

<!-- Notes -->

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

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

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

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

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

<link linkend="book.mbstring">multibyte</link> or <link linkend="book.intl">intl</link> extensions instead.</simpara></note>'>

<!ENTITY note.clearstatcache '<note xmlns="http://docbook.org/ns/docbook"><simpara>The results of this

function are cached. See <function>clearstatcache</function> for

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

<!ENTITY note.context-support '<note xmlns="http://docbook.org/ns/docbook"><simpara>Context support was added

with PHP 5.0.0. For a description of <literal>contexts</literal>, refer to

<xref linkend="book.stream"/>.</simpara></note>'>

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

<type>resource</type>.</para>'>

<!ENTITY note.exec-bg '<note xmlns="http://docbook.org/ns/docbook"><para>If a program is started with this function,

in order for it to continue running in the background, the output of the

...

@@ -50,6 +74,11 @@ will cause PHP to hang until the execution of the program ends.</para></note>'>

will first start cmd.exe to launch the command. If you want to start an external program without starting cmd.exe

use <function>proc_open</function> with the <parameter>bypass_shell</parameter> option set.</para></note>'>

<!ENTITY note.extractto-windows '<note xmlns="http://docbook.org/ns/docbook"><para>Windows NTFS file systems

do not support some characters in filenames, namely <literal>&lt;|&gt;*?":</literal>. Filenames with a trailing dot

are not supported either. Contrary to some extraction tools, this method does not replace these characters with

an underscore, but instead fails to extract such files.</para></note>'>

<!ENTITY note.func-callback '<note xmlns="http://docbook.org/ns/docbook"><simpara>Instead of a function name, an

array containing an object reference and a method name can also be

supplied.</simpara></note>'>

...

@@ -67,6 +96,13 @@ current scope to determine parameter details, it cannot be used as a

function parameter in versions prior to 5.3.0. If this value must be passed, the results should be assigned

to a variable, and that variable should be passed.</para></note>'>

<!ENTITY note.func-named-params '<note xmlns="http://docbook.org/ns/docbook"><para>As of PHP 8.0.0, the func_*() family of

100

functions is intended to be mostly transparent with regard to named arguments,

101

by treating the arguments as if they were all passed positionally,

102

and missing arguments are replaced with their defaults.

103

This function ignores the collection of unknown named variadic arguments.

104

Unknown named arguments which are collected can only be accessed through the variadic parameter.</para></note>'>

105

106

<!ENTITY note.line-endings '<note xmlns="http://docbook.org/ns/docbook"><simpara>If PHP is not properly recognizing

107

the line endings when reading files either on or created by a Macintosh

108

computer, enabling the

...

@@ -99,12 +135,6 @@ to seed the random number generator with <function>srand</function> or

135

<function>mt_srand</function> as this is done automatically.

100

136

</simpara></note>'>

101

137

102

<!ENTITY note.registerglobals '<note xmlns="http://docbook.org/ns/docbook"><title>register_globals: important

103

note</title><para>As of PHP 4.2.0, the default value for the PHP directive

104

<link linkend="ini.register-globals">register_globals</link> is <emphasis>

105

off</emphasis>. The PHP community discourages developers from relying on this directive, and encourages the use

106

of other means, such as the &link.superglobals;.</para></note>'>

107

108

138

<!ENTITY note.is-superglobal "<note xmlns='http://docbook.org/ns/docbook'><para>This is a 'superglobal', or

109

139

automatic global, variable. This simply means that it is available in

110

140

all scopes throughout a script. There is no need to do

...

@@ -115,6 +145,10 @@ all scopes throughout a script. There is no need to do

115

145

is used, this function uses internal output buffering so it cannot be used inside an

116

146

<function>ob_start</function> callback function.</para></note>'>

117

147

148

<!ENTITY note.uses-ob-php70 '<note xmlns="http://docbook.org/ns/docbook"><para>When the <parameter>return</parameter> parameter

149

is used, this function uses internal output buffering prior to PHP 7.1.0, so it cannot be used inside an

150

<function>ob_start</function> callback function.</para></note>'>

151

118

152

<!ENTITY note.filesystem-time-res '<note xmlns="http://docbook.org/ns/docbook"><para>Note that time resolution may differ

119

153

from one file system to another.</para></note>'>

120

154

...

@@ -139,7 +173,22 @@ from one file system to another.</para></note>'>

139

173

140

174

<!ENTITY note.sort-unstable '<note xmlns="http://docbook.org/ns/docbook">

141

175

 <para>

142

  If two members compare as equal, their relative order in the sorted array is undefined.

176

  If two members compare as equal, they retain their original order.

177

  Prior to PHP 8.0.0, their relative order in the sorted array was undefined.

178

 </para>

179

</note>

180

'>

181

182

<!ENTITY note.reset-index "<note xmlns='http://docbook.org/ns/docbook'>

183

 <para>

184

    Resets array's internal pointer to the first element.

185

 </para>

186

</note>

187

">

188

189

<!ENTITY note.resource-migration-8.0-dead-function '<note xmlns="http://docbook.org/ns/docbook">

190

 <para>

191

  This function has no effect. Prior to PHP 8.0.0, this function was used to close the resource.

143

192

 </para>

144

193

</note>

145

194

'>

...

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

184

233

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

185

234

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

186

235

236

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

237

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

238

187

239

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

188

240

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

189

241

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

...

@@ -223,6 +275,12 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been

223

275

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

224

276

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

225

277

278

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

279

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

280

<emphasis>DEPRECATED</emphasis> as of PHP 7.0.0 and

281

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

282

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

283

226

284

<!ENTITY warn.deprecated.function-7-1-0.removed-7-2-0 '<warning

227

285

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

228

286

<emphasis>DEPRECATED</emphasis> as of PHP 7.1.0 and

...

@@ -234,11 +292,21 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been

234

292

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

235

293

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

236

294

295

<!ENTITY warn.deprecated.feature-7-2-0.removed-8-0-0 '<warning

296

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

297

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

298

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

299

237

300

<!ENTITY warn.deprecated.function-7-2-0 '<warning

238

301

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

239

302

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

240

303

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

241

304

305

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

306

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

307

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

308

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

309

242

310

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

243

311

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

244

312

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

...

@@ -249,6 +317,11 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been

249

317

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

250

318

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

251

319

320

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

321

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

322

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

323

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

324

252

325

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

253

326

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

254

327

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

...

@@ -259,6 +332,50 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been

259

332

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

260

333

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

261

334

335

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

336

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

337

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

338

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

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

344

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

345

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

346

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

347

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

348

349

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

350

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

351

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

352

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

353

354

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

355

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

356

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

357

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

358

359

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

360

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

361

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

362

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

363

364

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

365

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

366

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

367

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

368

369

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

370

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

371

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

372

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

373

374

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

375

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

376

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

377

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

378

262

379

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

263

380

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

264

381

...

@@ -318,9 +435,18 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function was

318

435

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

319

436

<emphasis>REMOVED</emphasis> in PHP 7.4.0.</simpara></warning>'>

320

437

438

<!ENTITY warn.deprecated.alias-7-2-0.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was

439

<emphasis>DEPRECATED</emphasis> in PHP 7.2.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>

440

321

441

<!ENTITY warn.deprecated.alias-7-4-0.removed-8-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was

322

442

<emphasis>DEPRECATED</emphasis> in PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>

323

443

444

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

445

<emphasis>DEPRECATED</emphasis> as of PHP 8.0.0.</simpara></warning>'>

446

447

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

448

<emphasis>REMOVED</emphasis> as of PHP 8.0.0.</simpara></warning>'>

449

324

450

<!ENTITY warn.experimental.func '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function is

325

451

<emphasis>EXPERIMENTAL</emphasis>. The behaviour of this function, its name, and

326

452

surrounding documentation may change without notice in a future release of PHP.

...

@@ -338,12 +464,6 @@ to several possible vulnerabilities. Please read our

338

464

<link linkend="security.cgi-bin">CGI security section</link> to learn how to

339

465

defend yourself from such attacks.</para></warning>'>

340

466

341

<!ENTITY note.magicquotes.gpc '<note xmlns="http://docbook.org/ns/docbook"><title>directive note: magic_quotes_gpc

342

</title><para>The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>

343

directive defaults to <literal>on</literal>. It essentially runs

344

<function>addslashes</function> on all GET, POST, and COOKIE data.

345

<function>stripslashes</function> may be used to remove them.</para></note>'>

346

347

467

<!ENTITY warn.passwordhashing '

348

468

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

349

469

 <para>

...

@@ -463,6 +583,15 @@ currently not documented; only its argument list is available.

463

583

</para>

464

584

'>

465

585

586

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

587

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

588

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

589

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

590

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

591

 Alternatives to this function include:

592

</para>

593

'>

594

466

595

<!-- Misc -->

467

596

468

597

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

...

@@ -489,8 +618,30 @@ currently not documented; only its argument list is available.

489

618

490

619

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

491

620

621

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

622

492

623

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

493

624

625

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

626

627

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

628

629

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

630

631

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

632

633

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

634

635

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

636

637

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

638

639

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

640

641

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

642

643

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

644

494

645

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

495

646

496

647

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

...

@@ -511,15 +662,110 @@ something similar to:</para>'>

511

662

<function>reset</function> the <type>array</type> pointer of the input array after

512

663

use.</simpara></note>'>

513

664

665

<!ENTITY array.changelog.by-ref '<row xmlns="http://docbook.org/ns/docbook">

666

 <entry>8.0.0</entry>

667

 <entry>

668

  If <parameter>callback</parameter> expects a parameter to be passed

669

  by reference, this function will now emit an <constant>E_WARNING</constant>.

670

 </entry>

671

</row>'>

672

673

<!ENTITY array.changelog.require-only-one '<row xmlns="http://docbook.org/ns/docbook">

674

  <entry>8.0.0</entry>

675

  <entry>

676

  This function can now be called with only one parameter.

677

  Formerly, at least two parameters have been required.

678

  </entry>

679

</row>'>

680

514

681

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

515

682

516

<!ENTITY avail.register-long-arrays 'As of PHP 5.0.0, the long PHP

517

<link xmlns="http://docbook.org/ns/docbook" linkend="language.variables.predefined">predefined variable</link>

518

arrays may be disabled with the

519

<link xmlns="http://docbook.org/ns/docbook" linkend="ini.register-long-arrays">register_long_arrays</link>

520

directive.'>

683

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

684

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

685

  <listitem>

686

   <para>

687

    The optional second parameter <parameter>flags</parameter>

688

    may be used to modify the sorting behavior using these values:

689

   </para>

690

   <para>

691

    Sorting type flags:

692

    <itemizedlist>

693

     <listitem>

694

      <simpara><constant>SORT_REGULAR</constant> - compare items normally;

695

      the details are described in the <link linkend="language.operators.comparison">comparison operators</link> section</simpara>

696

     </listitem>

697

     <listitem>

698

      <simpara><constant>SORT_NUMERIC</constant> - compare items numerically</simpara>

699

     </listitem>

700

     <listitem>

701

      <simpara><constant>SORT_STRING</constant> - compare items as strings</simpara>

702

     </listitem>

703

     <listitem>

704

      <simpara>

705

       <constant>SORT_LOCALE_STRING</constant> - compare items as

706

       strings, based on the current locale. It uses the locale,

707

       which can be changed using <function>setlocale</function>

708

      </simpara>

709

     </listitem>

710

     <listitem>

711

      <simpara>

712

       <constant>SORT_NATURAL</constant> - compare items as strings

713

       using "natural ordering" like <function>natsort</function>

714

      </simpara>

715

     </listitem>

716

     <listitem>

717

      <simpara>

718

       <constant>SORT_FLAG_CASE</constant> - can be combined

719

       (bitwise OR) with

720

       <constant>SORT_STRING</constant> or

721

       <constant>SORT_NATURAL</constant> to sort strings case-insensitively

722

      </simpara>

723

     </listitem>

724

    </itemizedlist>

725

   </para>

726

  </listitem>

727

 </varlistentry>

728

'>

729

730

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

731

 &return.callbacksort;

732

</para>

733

&callback.cmp;

734

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

735

 <para>

736

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

737

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

738

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

739

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

740

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

741

 </para>

742

</caution>'>

743

744

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

745

 <para>

746

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

747

  regardless of the order they were originally provided.

748

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

749

750

  For example:

751

  <programlisting role="php">

752

<![CDATA[

753

<?php

754

$arrayA = ["string", 1];

755

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

756

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

757

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

758

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

759

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

760

    return $value1 <=> $value2;

761

};

762

?>

763

]]>

764

  </programlisting>

765

 </para>

766

</caution>'>

521

767

522

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

768

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

523

769

value is measured in bytes. Shorthand notation, as described

524

770

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

525

771

</simpara>'>

...

@@ -550,14 +796,10 @@ files from the PHP folder into the Windows system directory also works

550

796

551

797

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

552

798

553

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

799

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

554

800

<!ENTITY style.procedural 'Procedural style'>

555

801

556

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

557

558

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

559

560

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

802

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

561

803

562

804

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

563

805

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

...

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

567

809

568

810

<!-- Returns -->

569

811

812

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

813

 <entry>8.2.0</entry>

814

 <entry>

815

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

816

 </entry>

817

</row>'>

818

570

819

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

571

820

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

572

821

...

@@ -576,8 +825,9 @@ searched for within the <link xmlns="http://docbook.org/ns/docbook" linkend="ini

576

825

577

826

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

578

827

579

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

580

Note that before PHP 7.0.0 this integer had to be in the range from -2147483648 to 2147483647.'>

828

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

829

830

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

581

831

582

832

<!ENTITY return.falseproblem '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function may

583

833

return Boolean &false;, but may also return a non-Boolean value which

...

@@ -587,6 +837,44 @@ information. Use <link linkend="language.operators.comparison">the ===

587

837

operator</link> for testing the return value of this

588

838

function.</simpara></warning>'>

589

839

840

<!-- Standard -->

841

<!ENTITY standard.changelog.calling-on-objects '<row xmlns="http://docbook.org/ns/docbook">

842

 <entry>8.1.0</entry>

843

 <entry>

844

  Calling this function on &object;s is deprecated.

845

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

846

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

847

 </entry>

848

</row>

849

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

850

 <entry>7.4.0</entry>

851

 <entry>

852

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

853

 </entry>

854

</row>

855

'>

856

857

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

858

 <entry>8.2.0</entry>

859

 <entry>

860

  This function is no longer guaranteed to return

861

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

862

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

863

  <literal>1</literal> instead.

864

 </entry>

865

</row>

866

'>

867

868

<!-- FileInfo -->

869

<!ENTITY fileinfo.parameters.finfo '<para xmlns="http://docbook.org/ns/docbook">An <classname>finfo</classname> instance, returned by <function>finfo_open</function>.</para>'>

870

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

871

 <entry>8.1.0</entry>

872

 <entry>

873

  The <parameter>finfo</parameter> parameter expects an <classname>finfo</classname>

874

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

875

 </entry>

876

</row>'>

877

590

878

<!-- OpenSSL -->

591

879

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

592

880

 <term><parameter>x509</parameter></term>

...

@@ -628,19 +916,22 @@ PHP is compiled with freetype support (<option role="configure">--with-freetype-

628

916

629

917

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

630

918

631

<!ENTITY gd.image.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>

632

image</parameter></term><listitem><para>An image resource, returned by one of the image creation functions,

919

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

920

<parameter>image</parameter></term><listitem><para>A <classname>GdImage</classname> object, returned by one of the image creation functions,

633

921

such as <function>imagecreatetruecolor</function>.</para></listitem></varlistentry>'>

634

922

635

<!ENTITY gd.font.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>

636

font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in

637

fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or any of your

638

own font identifiers registered with <function>imageloadfont</function>.

639

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

923

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

924

<parameter>font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in

925

fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or <classname>GdFont</classname> instance,

926

returned by <function>imageloadfont</function>.</para></listitem></varlistentry>'>

640

927

641

<!ENTITY gd.psfont.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>

642

font_index</parameter></term><listitem><para>A font resource, returned by <function>imagepsloadfont</function>.

643

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

928

<!ENTITY gd.changelog.gdfont-instance '<row xmlns="http://docbook.org/ns/docbook">

929

  <entry>8.1.0</entry>

930

  <entry>

931

  The <parameter>font</parameter> parameter now accepts both an <classname>GdFont</classname> instance

932

  and an &integer;; previously only &integer; was accepted.

933

  </entry>

934

</row>'>

644

935

645

936

<!ENTITY gd.ttf.fontfile "

646

937

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

...

@@ -688,7 +979,7 @@ $font = 'SomeFont';

688

979

    </varlistentry>

689

980

">

690

981

691

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

982

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

692

983

693

984

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

694

985

...

@@ -704,7 +995,7 @@ $font = 'SomeFont';

704

995

705

996

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

706

997

707

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

998

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

708

999

709

1000

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

710

1001

...

@@ -774,10 +1065,28 @@ and GD2 image formats are proprietary image formats of libgd. They have to be re

774

1065

<emphasis>obsolete</emphasis>, and should only be used for development and testing

775

1066

purposes.</simpara></warning>'>

776

1067

1068

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

1069

 <entry>8.0.0</entry>

1070

 <entry>

1071

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

1072

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

1073

 </entry>

1074

</row>'>

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

777

1086

<!-- DBM notes -->

778

1087

779

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

780

dbm_identifier</parameter></term><listitem><para>The DBM link identifier,

1088

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

1089

<parameter>dbm_identifier</parameter></term><listitem><para>The DBM link identifier,

781

1090

returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>

782

1091

783

1092

<!-- JSON notes -->

...

@@ -793,14 +1102,52 @@ returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>

793

1102

794

1103

<!-- cURL notes -->

795

1104

796

<!ENTITY curl.ch.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>ch</parameter>

1105

<!ENTITY curl.ch.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>handle</parameter>

797

1106

</term><listitem><para>A cURL handle returned by

798

1107

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

799

1108

800

<!ENTITY curl.mh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>mh</parameter>

1109

<!ENTITY curl.mh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>multi_handle</parameter>

801

1110

</term><listitem><para>A cURL multi handle returned by

802

1111

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

803

1112

1113

<!ENTITY curl.sh.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>share_handle</parameter>

1114

</term><listitem><para>A cURL share handle returned by

1115

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

1116

1117

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

1118

 <entry>8.0.0</entry>

1119

 <entry>

1120

  <parameter>handle</parameter> expects a <classname>CurlHandle</classname>

1121

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

1122

 </entry>

1123

</row>'>

1124

1125

<!ENTITY curl.changelog.multi-handle-param '<row xmlns="http://docbook.org/ns/docbook">

1126

 <entry>8.0.0</entry>

1127

 <entry>

1128

  <parameter>multi_handle</parameter> expects a <classname>CurlMultiHandle</classname>

1129

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

1130

 </entry>

1131

</row>'>

1132

1133

<!ENTITY curl.changelog.share-handle-param '<row xmlns="http://docbook.org/ns/docbook">

1134

 <entry>8.0.0</entry>

1135

 <entry>

1136

  <parameter>share_handle</parameter> expects a <classname>CurlShareHandle</classname>

1137

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

1138

 </entry>

1139

</row>'>

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

804

1151

<!-- dbase notes -->

805

1152

806

1153

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

...

@@ -832,10 +1179,59 @@ returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>

832

1179

   </itemizedlist>

833

1180

  </para>'>

834

1181

1182

<!-- enchant entities -->

1183

1184

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

1185

     <term><parameter>broker</parameter></term>

1186

     <listitem>

1187

      <para>

1188

       An Enchant broker returned by <function>enchant_broker_init</function>.

1189

      </para>

1190

     </listitem>

1191

    </varlistentry>'>

1192

1193

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

1194

     <term><parameter>dictionary</parameter></term>

1195

     <listitem>

1196

      <para>

1197

       An Enchant dictionary returned by <function>enchant_broker_request_dict</function>

1198

       or <function>enchant_broker_request_pwl_dict</function>.

1199

      </para>

1200

     </listitem>

1201

    </varlistentry>'>

1202

1203

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

1204

 <entry>8.0.0</entry>

1205

 <entry>

1206

  <parameter>broker</parameter> expects an <classname>EnchantBroker</classname> instance now;

1207

  previoulsy, a &resource; was expected.

1208

 </entry>

1209

</row>'>

1210

1211

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

1212

 <entry>8.0.0</entry>

1213

 <entry>

1214

  <parameter>dictionary</parameter> expects an <classname>EnchantDictionary</classname> instance now;

1215

  previoulsy, a &resource; was expected.

1216

 </entry>

1217

</row>'>

1218

835

1219

<!-- IMAP notes -->

836

1220

837

<!ENTITY imap.imap-stream.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>

838

imap_stream</parameter></term><listitem><para>An IMAP stream returned by

1221

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

1222

 <entry>8.1.0</entry>

1223

 <entry>

1224

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

1225

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

1226

 </entry>

1227

</row>'>

1228

1229

<!ENTITY imap.imap-parameter.imap '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

1230

<parameter>imap</parameter></term><listitem><para>An <classname>IMAP\Connection</classname> instance.</para></listitem></varlistentry>'>

1231

1232

<!-- Deprecated -->

1233

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

1234

<parameter>imap</parameter></term><listitem><para>An IMAP stream returned by

839

1235

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

840

1236

841

1237

<!ENTITY imap.pattern '<para xmlns="http://docbook.org/ns/docbook">Specifies where in the mailbox hierarchy

...

@@ -858,16 +1254,95 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles

858

1254

859

1255

<!-- intl notes -->

860

1256

861

<!ENTITY intl.codepoint.parameter '<para xmlns="http://docbook.org/ns/docbook">The <type>integer</type> codepoint value (e.g. <literal>0x2603</literal> for <emphasis>U+2603 SNOWMAN</emphasis>), or the character encoded as a UTF-8 <type>string</type> (e.g. <literal>"\u{2603}"</literal>)</para>'>

1257

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

1258

1259

<!ENTITY intl.error.intl-calendar '<para xmlns="http://docbook.org/ns/docbook">On failure &false; is also returned. To detect error conditions use <function>intl_get_error_code</function>, or set up Intl to throw <link linkend="ini.intl.use-exceptions">exceptions</link>.</para>'>

1260

1261

<!ENTITY intl.codepoint.parameter '<para xmlns="http://docbook.org/ns/docbook">The <type>int</type> codepoint value (e.g. <literal>0x2603</literal> for <emphasis>U+2603 SNOWMAN</emphasis>), or the character encoded as a UTF-8 <type>string</type> (e.g. <literal>"\u{2603}"</literal>)</para>'>

862

1262

863

<!ENTITY intl.codepoint.return '<para xmlns="http://docbook.org/ns/docbook">The return type will be <type>integer</type> unless the code point was passed as a UTF-8 <type>string</type>, in which case a <type>string</type> will be returned.</para>'>

1263

<!ENTITY intl.codepoint.return '<para xmlns="http://docbook.org/ns/docbook">The return type is <type>int</type> unless the code point was passed as a UTF-8 <type>string</type>, in which case a <type>string</type> is returned. Returns &null; on failure.</para>'>

864

1264

865

1265

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

866

1266

1267

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

1268

867

1269

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

868

1270

869

1271

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

870

1272

1273

<!-- LDAP notes -->

1274

1275

<!ENTITY ldap.parameter.ldap 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\Connection</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_connect</function>.'>

1276

1277

<!ENTITY ldap.parameter.result 'An <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance, returned by <function xmlns="http://docbook.org/ns/docbook">ldap_list</function> or <function xmlns="http://docbook.org/ns/docbook">ldap_search</function>.'>

1278

1279

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

1280

1281

<!ENTITY ldap.warn.control-paged '<warning xmlns="http://docbook.org/ns/docbook">

1282

 <simpara>

1283

  This function has been <emphasis>DEPRECATED</emphasis> as of PHP 7.4.0, and <emphasis>REMOVED</emphasis> as of PHP 8.0.0.

1284

  Instead the <parameter>controls</parameter> parameter of <function>ldap_search</function> should be used.

1285

  See also <link linkend="ldap.controls">LDAP Controls</link> for details.

1286

 </simpara>

1287

</warning>'>

1288

1289

<!ENTITY ldap.changelog.controls-nullable '<row xmlns="http://docbook.org/ns/docbook">

1290

 <entry>8.0.0</entry>

1291

 <entry>

1292

  <parameter>controls</parameter> is nullable now; previously, it defaulted to <literal>[]</literal>.

1293

 </entry>

1294

</row>'>

1295

1296

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

1297

 <entry>8.1.0</entry>

1298

 <entry>

1299

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

1300

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

1301

 </entry>

1302

</row>'>

1303

1304

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

1305

 <entry>8.1.0</entry>

1306

 <entry>

1307

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

1308

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

1309

 </entry>

1310

</row>'>

1311

1312

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

1313

 <entry>8.1.0</entry>

1314

 <entry>

1315

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

1316

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

1317

 </entry>

1318

</row>'>

1319

1320

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

1321

 <entry>8.1.0</entry>

1322

 <entry>

1323

  Returns an <classname>LDAP\Result</classname> instance now;

1324

  previously, a &resource; was returned.

1325

 </entry>

1326

</row>'>

1327

1328

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

1329

 <entry>8.1.0</entry>

1330

 <entry>

1331

  Returns an <classname>LDAP\ResultEntry</classname> instance now;

1332

  previously, a &resource; was returned.

1333

 </entry>

1334

</row>'>

1335

1336

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

1337

<!ENTITY ldap.return-result-array 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance, an array of <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instances,&return.falseforfailure;.'>

1338

1339

<!ENTITY ldap.return-result-array-info '<para xmlns="http://docbook.org/ns/docbook">It is also possible to perform parallel searches. In this case, the first argument should be an array of

1340

<classname>LDAP\Connection</classname> instances, rather than a single one.

1341

If the searches should not all use the same base DN and filter, an array of base DNs and/or an array of filters can be passed as arguments instead.

1342

These arrays must be of the same size as the <classname>LDAP\Connection</classname> instances array,

1343

since the first entries of the arrays are used for one search, the second entries are used for another, and so on.

1344

When doing parallel searches an array of <classname>LDAP\Result</classname> instances is returned, except in case of error, when the return value will be &false;.</para>'>

1345

871

1346

<!-- mbstring notes -->

872

1347

873

1348

<!ENTITY note.mbstring.encoding.internal '<note xmlns="http://docbook.org/ns/docbook"><para>The internal encoding or the

...

@@ -879,11 +1354,25 @@ character encoding specified by <function>mb_regex_encoding</function>

879

1354

will be used as the character encoding for this function by default.</para></note>'>

880

1355

881

1356

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

882

parameter is the character encoding. If it is omitted, the internal character

1357

parameter is the character encoding. If it is omitted or &null;, the internal character

883

1358

encoding value will be used.</para>'>

884

1359

885

1360

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

886

1361

1362

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

1363

 <entry>8.0.0</entry>

1364

 <entry>

1365

  <parameter>encoding</parameter> is nullable now.

1366

 </entry>

1367

</row>'>

1368

1369

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

1370

 <entry>8.0.0</entry>

1371

 <entry>

1372

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

1373

 </entry>

1374

</row>'>

1375

887

1376

<!-- mcrypt notes -->

888

1377

889

1378

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

...

@@ -896,12 +1385,20 @@ encoding value will be used.</para>'>

896

1385

897

1386

 <!-- MCVE notes -->

898

1387

899

<!ENTITY mcve.conn.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>

900

conn</parameter></term><listitem><para>An MCVE_CONN resource returned by

1388

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

1389

<parameter>conn</parameter></term><listitem><para>An MCVE_CONN resource returned by

901

1390

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

902

1391

903

1392

<!-- memcached notes -->

904

1393

1394

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

1395

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

1396

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

1397

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

1398

       will return <constant>MEMCACHED_INVALID_ARGUMENTS</constant>.

1399

      </simpara></note>

1400

'>

1401

905

1402

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

906

1403

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

907

1404

...

@@ -915,6 +1412,19 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by

915

1412

916

1413

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

917

1414

1415

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

1416

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

1417

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

1418

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

1419

   failed.

1420

   </para>

1421

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

1422

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

1423

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

1424

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

1425

  </para>

1426

'>

1427

918

1428

<!-- password notes -->

919

1429

920

1430

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

...

@@ -925,6 +1435,54 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by

925

1435

926

1436

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

927

1437

1438

<!-- pspell notes -->

1439

1440

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

1441

 <entry>8.1.0</entry>

1442

 <entry>

1443

  The <parameter>dictionary</parameter> parameter expects an <classname>PSpell\Dictionary</classname>

1444

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

1445

 </entry>

1446

</row>'>

1447

1448

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

1449

 <entry>8.1.0</entry>

1450

 <entry>

1451

  The <parameter>config</parameter> parameter expects an <classname>PSpell\Config</classname>

1452

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

1453

 </entry>

1454

</row>'>

1455

1456

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

1457

1458

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

1459

1460

<!-- RNP -->

1461

1462

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

1463

1464

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

1465

1466

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

1467

1468

<!-- socket entities -->

1469

1470

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

1471

  <entry>8.0.0</entry>

1472

  <entry>

1473

   <parameter>socket</parameter> is a <classname>Socket</classname> instance now;

1474

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

1475

  </entry>

1476

 </row>'>

1477

1478

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

1479

 <entry>8.0.0</entry>

1480

 <entry>

1481

  <parameter>address</parameter> is an <classname>AddressInfo</classname> instance now;

1482

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

1483

 </entry>

1484

</row>'>

1485

928

1486

<!-- geaman notes -->

929

1487

930

1488

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

...

@@ -943,6 +1501,49 @@ conn</parameter></term><listitem><para>An MCVE_CONN resource returned by

943

1501

944

1502

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

945

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

946

1547

<!-- Date and time entities -->

947

1548

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

948

1549

...

@@ -956,6 +1557,7 @@ installed via PECL's <link xlink:href='&url.pecl.package.get;timezonedb' xmlns:x

956

1557

957

1558

<!ENTITY date.timezone.bc '<simpara xmlns="http://docbook.org/ns/docbook">Please do not use any of the timezones

958

1559

listed here (besides UTC), they only exist for backward compatible reasons, and may expose erroneous behavior.

1560

Furthermore, these timezones may be removed from the IANA timezone database at any time.

959

1561

</simpara>'>

960

1562

961

1563

<!ENTITY date.timezone.posix-signs '<simpara xmlns="http://docbook.org/ns/docbook">

...

@@ -983,11 +1585,8 @@ It is strongly recommended to avoid timezone abbreviations.

983

1585

</simpara>'>

984

1586

985

1587

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

986

Every call to a date/time function will generate a <constant>E_NOTICE</constant>

987

if the time zone is not valid, and/or a <constant>E_STRICT</constant>

988

or <constant>E_WARNING</constant> message

989

if using the system settings or the <varname>TZ</varname> environment

990

variable. See also <function>date_default_timezone_set</function></para>'>

1588

Every call to a date/time function will generate a <constant>E_WARNING</constant>

1589

if the time zone is not valid. See also <function>date_default_timezone_set</function></para>'>

991

1590

992

1591

<!ENTITY date.timezone.errors.changelog '<row xmlns="http://docbook.org/ns/docbook"><entry>5.1.0</entry><entry><para>

993

1592

Now issues the <constant>E_STRICT</constant> and <constant>E_NOTICE</constant>

...

@@ -996,8 +1595,8 @@ time zone errors.</para></entry></row>'>

996

1595

<!ENTITY date.timestamp.description '

997

1596

<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>timestamp</parameter></term><listitem><para>

998

1597

The optional <parameter>timestamp</parameter> parameter is an

999

<type>integer</type> Unix timestamp that defaults to the current

1000

local time if a <parameter>timestamp</parameter> is not given. In other

1598

<type>int</type> Unix timestamp that defaults to the current

1599

local time if <parameter>timestamp</parameter> is omitted or &null;. In other

1001

1600

words, it defaults to the value of <function>time</function>.

1002

1601

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

1003

1602

...

@@ -1010,11 +1609,14 @@ returned by <function>date_create</function></para></listitem></varlistentry>'>

1010

1609

returned by <function>date_create</function>.

1011

1610

The function modifies this object.</para></listitem></varlistentry>'>

1012

1611

1013

<!ENTITY date.datetimezone.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>

1014

object</parameter></term><listitem><para>Procedural style only: A <classname>DateTimeZone</classname> object

1612

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

1613

<parameter>object</parameter></term><listitem><para>Procedural style only: A <classname>DateTimeZone</classname> object

1015

1614

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

1016

1615

1017

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

1616

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

1617

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

1618

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

1619

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

1018

1620

1019

1621

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

1020

1622

...

@@ -1034,22 +1636,71 @@ returned by <function>timezone_open</function></para></listitem></varlistentry>'

1034

1636

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

1035

1637

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

1036

1638

1037

<!-- DomXml Notes -->

1038

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

1039

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

1040

1041

1042

1639

<!-- Dom Notes -->

1043

1640

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

1044

1641

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

1045

1642

1046

<!ENTITY dom.allowstatic '<para xmlns="http://docbook.org/ns/docbook">This method <emphasis>may</emphasis> be called statically, but will issue an <constant>E_STRICT</constant> error.</para>'>

1047

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

1048

<!ENTITY dom.note.utf8 '<note xmlns="http://docbook.org/ns/docbook"><para>The DOM extension uses UTF-8 encoding. Use <function>utf8_encode</function> and <function>utf8_decode</function> to work with texts in ISO-8859-1 encoding or <link linkend="ref.iconv">iconv</link> for other encodings.</para></note>'>

1644

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

1645

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

1646

 <simpara>

1647

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

1648

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

1649

 </simpara>

1650

</note>'>

1049

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

1701

1050

1702

1051

1703

1052

1053

1704

<!-- Dom Examples -->

1054

1705

<!ENTITY dom.book.example '<para xmlns="http://docbook.org/ns/docbook">The following examples use <filename>book.xml</filename> which contains the following:</para>

1055

1706

<programlisting role="xml" xmlns="http://docbook.org/ns/docbook">

...

@@ -1084,6 +1735,128 @@ it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNo

1084

1735

</books>

1085

1736

]]></programlisting>'>

1086

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

1087

1860

1088

1861

<!-- FileSystem entities -->

1089

1862

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

...

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

1123

1896

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

1124

1897

1125

1898

<!-- ODBC -->

1126

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

1127

1900

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

1128

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

1129

1908

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

1130

1909

1131

1910

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

...

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

1136

1915

1137

1916

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

1138

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

1139

1978

<!-- OAUTH -->

1140

1979

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

1141

1980

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

...

@@ -1150,7 +1989,7 @@ string</link>, or a Connect Name from

1150

1989

the <filename>tnsnames.ora</filename> file, or the name of a local

1151

1990

Oracle instance.

1152

1991

</para>

1153

<para xmlns='http://docbook.org/ns/docbook'>If not specified, PHP uses

1992

<para xmlns='http://docbook.org/ns/docbook'>If not specified or &null;, PHP uses

1154

1993

environment variables such as <constant>TWO_TASK</constant> (on Linux)

1155

1994

or <constant>LOCAL</constant> (on Windows)

1156

1995

and <constant>ORACLE_SID</constant> to determine the

...

@@ -1163,18 +2002,18 @@ To use the Easy Connect naming method, PHP must be linked with Oracle

1163

2002

<emphasis>[//]host_name[:port][/service_name]</emphasis>. From Oracle

1164

2003

11<emphasis>g</emphasis>, the syntax is:

1165

2004

<emphasis>[//]host_name[:port][/service_name][:server_type][/instance_name]</emphasis>.

1166

Service names can be found by running the Oracle

1167

utility <literal>lsnrctl status</literal> on the database server

2005

Further options were introduced with Oracle 19c, including timeout and keep-alive

2006

settings.  Refer to Oracle documentation.  Service names can be found by running

2007

the Oracle utility <literal>lsnrctl status</literal> on the database server

1168

2008

machine.

1169

2009

</para>

1170

2010

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

1171

The <filename>tnsnames.ora</filename> file can be in the Oracle Net

1172

search path, which

1173

includes <filename>$ORACLE_HOME/network/admin</filename>

1174

and <filename>/etc</filename>.  Alternatively

1175

set <literal>TNS_ADMIN</literal> so

1176

that <filename>$TNS_ADMIN/tnsnames.ora</filename> is read.  Make sure

1177

the web daemon has read access to the file.

2011

The <filename>tnsnames.ora</filename> file can be in the Oracle Net search path,

2012

which

2013

includes <filename>/your/path/to/instantclient/network/admin</filename>, <filename>$ORACLE_HOME/network/admin</filename>

2014

and <filename>/etc</filename>.  Alternatively set <literal>TNS_ADMIN</literal>

2015

so that <filename>$TNS_ADMIN/tnsnames.ora</filename> is read.  Make sure the web

2016

daemon has read access to the file.

1178

2017

</para>">

1179

2018

1180

2019

<!ENTITY oci.charset "<para xmlns='http://docbook.org/ns/docbook'>Determines

...

@@ -1268,61 +2107,16 @@ call to <function>pcntl_waitpid</function>.</para>'>

1268

2107

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

1269

2108

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

1270

2109

1271

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

1272

1273

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

1274

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

1275

1276

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

1277

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

1278

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

1279

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

1280

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

1281

1282

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

1283

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

1284

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

1285

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

1286

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

1287

1288

2110

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

1289

2111

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

1290

2112

1291

2113

1292

2114

<!ENTITY note.language-construct '<note xmlns="http://docbook.org/ns/docbook"><simpara>Because this is a

1293

2115

language construct and not a function, it cannot be called using

1294

<link linkend="functions.variable-functions">variable functions</link>.</simpara>

2116

<link linkend="functions.variable-functions">variable functions</link>,

2117

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

1295

2118

</note>'>

1296

2119

1297

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

1298

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

1299

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

1300

1301

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

1302

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

1303

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

1304

1305

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

1306

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

1307

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

1308

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

1309

1310

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

1311

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

1312

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

1313

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

1314

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

1315

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

1316

1317

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

1318

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

1319

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

1320

executed.'>

1321

1322

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

1323

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

1324

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

1325

1326

2120

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

1327

2121

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

1328

2122

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

...

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

1343

2137

</simpara>'>

1344

2138

1345

2139

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

1346

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

1347

2141

1348

2142

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

1349

2143

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

...

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

1364

2158

been compiled into PHP or dynamically loaded at runtime.

1365

2159

</simpara>'>

1366

2160

1367

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

1368

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

1369

1370

2161

<!-- PDO entities -->

1371

2162

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

1372

2163

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

...

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

1379

2170

1380

2171

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

1381

2172

2173

<!-- PDO errors -->

2174

2175

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

2176

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

2177

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

2178

</para>

2179

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

2180

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

2181

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

2182

</para>'>

2183

1382

2184

<!-- PECL entities -->

1383

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

1384

is not bundled with PHP.'>

2185

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

1385

2186

1386

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

1387

is bundled with PHP.'>

2187

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

1388

2188

1389

2189

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

1390

2190

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

...

@@ -1402,7 +2202,7 @@ this extension is still available within <acronym xmlns="http://docbook.org/ns/d

1402

2202

1403

2203

<!ENTITY pecl.windows.download 'A <acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> for this

1404

2204

<acronym xmlns="http://docbook.org/ns/docbook">PECL</acronym> extension is currently unavailable. See also the

1405

<link xmlns="http://docbook.org/ns/docbook" linkend="install.windows.legacy.building">building on Windows</link>

2205

<link xmlns="http://docbook.org/ns/docbook" linkend="install.windows.building">building on Windows</link>

1406

2206

section.'>

1407

2207

1408

2208

<!ENTITY pecl.windows.download.avail 'Windows binaries (<acronym xmlns="http://docbook.org/ns/docbook">DLL</acronym> files)

...

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

1410

2210

1411

2211

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

1412

2212

1413

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

1414

<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

1415

PHP as of PHP '>

2213

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

2214

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

2215

2216

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

2217

 <simpara>

2218

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

2219

  We recommend using PIE to install extensions.

2220

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

2221

 </simpara>

2222

</note>'>

2223

2224

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

2225

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

2226

</warning>'>

2227

2228

<!-- PGSQL entities -->

2229

2230

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

2231

2232

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

2233

When <parameter>connection</parameter> is unspecified, the default connection is used.

2234

The default connection is the last connection made by <function>pg_connect</function>

2235

or <function>pg_pconnect</function>.

2236

<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>

2237

2238

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

2239

When <parameter>connection</parameter> is &null;, the default connection is used.

2240

The default connection is the last connection made by <function>pg_connect</function>

2241

or <function>pg_pconnect</function>.

2242

<warning><simpara>As of PHP 8.1.0, using the default connection is deprecated.</simpara></warning></para>'>

2243

2244

<!ENTITY pgsql.parameter.result '<para xmlns="http://docbook.org/ns/docbook">An <classname>PgSql\Result</classname> instance, returned by <function>pg_query</function>,

2245

<function>pg_query_params</function> or <function>pg_execute</function>(among others).</para>'>

2246

2247

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

2248

2249

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

2250

An optional parameter that controls how the returned <type>array</type> is indexed.

2251

<parameter>mode</parameter> is a constant and can take the following values:

2252

<constant>PGSQL_ASSOC</constant>, <constant>PGSQL_NUM</constant> and <constant>PGSQL_BOTH</constant>.

2253

Using <constant>PGSQL_NUM</constant>, the function will return an array with numerical indices,

2254

using <constant>PGSQL_ASSOC</constant> it will return only associative indices

2255

while <constant>PGSQL_BOTH</constant> will return both numerical and associative indices.</para>'>

2256

2257

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

2258

 <entry>8.1.0</entry>

2259

 <entry>

2260

  The <parameter>connection</parameter> parameter expects an <classname>PgSql\Connection</classname>

2261

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

2262

 </entry>

2263

</row>'>

2264

2265

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

2266

 <entry>8.1.0</entry>

2267

 <entry>

2268

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

2269

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

2270

 </entry>

2271

</row>'>

2272

2273

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

2274

 <entry>8.1.0</entry>

2275

 <entry>

2276

  The <parameter>lob</parameter> parameter expects an <classname>PgSql\Lob</classname>

2277

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

2278

 </entry>

2279

</row>'>

2280

2281

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

2282

 <entry>8.1.0</entry>

2283

 <entry>

2284

  Returns an <classname>PgSql\Result</classname> instance now;

2285

  previously, a &resource; was returned.

2286

 </entry>

2287

</row>'>

1416

2288

1417

2289

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

1418

2290

...

@@ -1426,59 +2298,51 @@ extensions in order to use these functions.</simpara>'>

1426

2298

1427

2299

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

1428

2300

1429

<!-- APD Notes -->

1430

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

1431

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

1432

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

1433

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

1434

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

1435

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

1436

</listitem></varlistentry>'>

1437

1438

<!-- BCMath Notes -->

1439

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

1440

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

1441

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

1442

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

1443

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

1444

1445

2301

<!-- CTYPE Notes -->

1446

2302

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

1447

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

2303

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

1448

2304

the ASCII value of a single character (negative values have 256 added in order to allow

1449

2305

characters in the Extended ASCII range). Any other integer is interpreted as a string

1450

2306

containing the decimal digits of the integer.</para></note>'>

1451

2307

1452

<!-- FBSQL Notes -->

1453

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

1454

link_identifier</parameter></term><listitem><para>A FrontBase link identifier

1455

returned by <function>fbsql_connect</function> or

1456

<function>fbsql_pconnect</function>.</para><para>If optional and not specified,

1457

the function will try to find an open link to the FrontBase server and if no

1458

such link is found it will try to create one as if

1459

<function>fbsql_connect</function> was called with no arguments.</para>

1460

</listitem></varlistentry>'>

1461

1462

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

1463

result</parameter></term><listitem><para>A result identifier

1464

returned by <function>fbsql_query</function> or

1465

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

2308

<!ENTITY note.ctype.parameter.non-string '<warning xmlns="http://docbook.org/ns/docbook"><para>

2309

As of PHP 8.1.0, passing a non-string argument is deprecated.

2310

In the future, the argument will be interpreted as a string instead of an ASCII codepoint.

2311

Depending on the intended behavior, the argument should either be cast to &string;

2312

or an explicit call to <function>chr</function> should be made.</para></warning>'>

2313

2314

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

2315

2316

<!-- FTP Notes -->

2317

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

2318

 <entry>8.1.0</entry>

2319

 <entry>

2320

  The <parameter>ftp</parameter> parameter expects an <classname>FTP\Connection</classname>

2321

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

2322

 </entry>

2323

</row>'>

2324

<!ENTITY ftp.parameter.ftp '<para xmlns="http://docbook.org/ns/docbook">An <classname>FTP\Connection</classname> instance.</para>'>

1466

2325

1467

2326

<!-- GMP Notes -->

1468

<!ENTITY gmp.return 'A GMP number <type xmlns="http://docbook.org/ns/docbook">resource</type> in PHP 5.5 and earlier, or a <classname xmlns="http://docbook.org/ns/docbook">GMP</classname> object in PHP 5.6 and later.'>

1469

<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">Either a GMP number <type>resource</type> in PHP 5.5 and earlier, a <classname>GMP</classname> object in PHP 5.6 and later, or a numeric string provided that it is possible to convert the latter to a number.</para>'>

2327

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

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

1470

2334

1471

2335

<!-- MySQLi Notes -->

1472

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

1473

result</parameter></term><listitem><para>Procedural style only: A result set

1474

identifier returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>

1475

or <function>mysqli_use_result</function>.</para></listitem></varlistentry>'>

1476

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

1477

link</parameter></term><listitem><para>Procedural style only: A link identifier

2336

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

2337

<parameter>result</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_result</classname>

2338

object returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>,

2339

<function>mysqli_use_result</function> or <function>mysqli_stmt_get_result</function>.</para></listitem></varlistentry>'>

2340

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

2341

<parameter>mysql</parameter></term><listitem><para>Procedural style only: A <classname>mysqli</classname> object

1478

2342

returned by <function>mysqli_connect</function> or <function>mysqli_init</function>

1479

2343

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

1480

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

1481

stmt</parameter></term><listitem><para>Procedural style only: A statement identifier

2344

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

2345

<parameter>statement</parameter></term><listitem><para>Procedural style only: A <classname>mysqli_stmt</classname> object

1482

2346

returned by <function>mysqli_stmt_init</function>.</para></listitem></varlistentry>'>

1483

2347

<!ENTITY mysqli.available.mysqlnd 'Available only with <link xmlns="http://docbook.org/ns/docbook"

1484

2348

linkend="book.mysqlnd">mysqlnd</link>.'>

...

@@ -1487,11 +2351,35 @@ linkend="book.mysqlnd">mysqlnd</link>.'>

1487

2351

hand-shake/authentication, which mysqlnd will use.</para><para>Libmysqlclient uses the default charset set in the

1488

2352

<filename>my.cnf</filename> or by an explicit call to <function>mysqli_options</function> prior to

1489

2353

calling <function>mysqli_real_connect</function>, but after <function>mysqli_init</function>.</para></note>'>

2354

<!ENTITY mysqli.integer.overflow.as.string.note '<note xmlns="http://docbook.org/ns/docbook">

2355

<para>If the number of rows is greater than <constant>PHP_INT_MAX</constant>,

2356

the number will be returned as a &string;.</para></note>'>

2357

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

2358

<title>Security warning: SQL injection</title><para>If the query contains any variable

2359

input then <link linkend="mysqli.quickstart.prepared-statements">parameterized

2360

prepared statements</link> should be used instead. Alternatively, the

2361

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

2362

the <function>mysqli_real_escape_string</function>

2363

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

2364

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

2365

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

2366

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

2367

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

2368

2369

<!-- Notes for PCRE -->

2370

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

2371

If the regex pattern passed does not compile to a valid regex, an <constant>E_WARNING</constant> is emitted.

2372

</para>'>

1490

2373

1491

2374

<!-- Notes for SAPI/Apache -->

1492

2375

<!ENTITY apache.req.module '<simpara xmlns="http://docbook.org/ns/docbook">This function is supported when PHP

1493

is installed as an Apache module or by the <link linkend="book.nsapi">NSAPI server module</link> in Netscape/iPlanet/SunONE

1494

webservers.</simpara>'>

2376

is installed as an Apache module webserver.

2377

</simpara>'>

2378

2379

<!-- Notes for SAPI/FPM -->

2380

<!ENTITY fpm.intro '<para xmlns="http://docbook.org/ns/docbook">FPM (FastCGI Process Manager) is

2381

a primary PHP FastCGI implementation containing some features (mostly) useful for heavy-loaded sites.

2382

</para>'>

1495

2383

1496

2384

<!-- SimpleXML Notes -->

1497

2385

<!ENTITY simplexml.iteration '<note xmlns="http://docbook.org/ns/docbook"><simpara>SimpleXML has made a rule of adding

...

@@ -1535,29 +2423,10 @@ are <emphasis>case-sensitive</emphasis>.</simpara></note>'>

1535

2423

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

1536

2424

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

1537

2425

1538

<!-- MSQL Notes -->

1539

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

1540

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

1541

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

1542

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

1543

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

1544

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

1545

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

1546

1547

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

1548

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

1549

is being evaluated. This result comes from a call to

1550

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

1551

1552

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

1553

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

1554

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

1555

1556

1557

2426

<!-- MySQL Notes -->

1558

2427

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

1559

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

1560

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

2428

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

2429

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

1561

2430

link identifier is not specified, the last link opened by

1562

2431

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

1563

2432

will try to create one as if <function>mysql_connect</function> had been called

...

@@ -1566,56 +2435,51 @@ with no arguments. If no connection is found or established, an

1566

2435

</varlistentry>'>

1567

2436

1568

2437

<!ENTITY mysql.linkid-noreopen.description '<varlistentry

1569

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

1570

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

2438

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

2439

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

1571

2440

link identifier is not specified, the last link opened by

1572

2441

<function>mysql_connect</function> is assumed. If no connection is found or

1573

2442

established, an <constant>E_WARNING</constant> level error is

1574

2443

generated.</para></listitem></varlistentry>'>

1575

2444

1576

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

1577

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

2445

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

2446

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

1578

2447

is being evaluated. This result comes from a call to

1579

2448

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

1580

2449

1581

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

1582

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

2450

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

2451

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

1583

2452

<parameter>field_offset</parameter> starts at <literal>0</literal>. If

1584

2453

<parameter>field_offset</parameter> does not exist, an error of level

1585

2454

<constant>E_WARNING</constant> is also issued.</para></listitem></varlistentry>'>

1586

2455

1587

2456

<!ENTITY mysql.alternative.note '<para xmlns="http://docbook.org/ns/docbook">This extension was deprecated in PHP 5.5.0, and it was removed in PHP 7.0.0.

1588

2457

Instead, the <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extension should be used.

1589

See also <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and

1590

<link linkend="faq.databases.mysql.deprecated">related FAQ</link> for more information.

2458

See also <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.

1591

2459

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

1592

2460

1593

2461

<!ENTITY mysql.alternative.note.4-3-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 4.3.0, and it

1594

2462

and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.

1595

2463

Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.

1596

See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its

1597

<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information. 

2464

See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.

1598

2465

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

1599

2466

1600

2467

<!ENTITY mysql.alternative.note.5-3-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 5.3.0, and it

1601

2468

and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.

1602

2469

Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.

1603

See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its

1604

<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information. 

2470

See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.

1605

2471

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

1606

2472

1607

2473

<!ENTITY mysql.alternative.note.5-4-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 5.4.0, and it

1608

2474

and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.

1609

2475

Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.

1610

See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its

1611

<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information. 

2476

See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.

1612

2477

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

1613

2478

1614

2479

<!ENTITY mysql.alternative.note.5-5-0 '<para xmlns="http://docbook.org/ns/docbook">This function was deprecated in PHP 5.5.0, and it

1615

2480

and the entire <link linkend="book.mysql">original MySQL extension</link> was removed in PHP 7.0.0.

1616

2481

Instead, use either the actively developed <link linkend="book.mysqli">MySQLi</link> or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.

1617

See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide and its

1618

<link linkend="faq.databases.mysql.deprecated">related FAQ entry</link> for additional information. 

2482

See also the <link linkend="mysqlinfo.api.choosing">MySQL: choosing an API</link> guide.

1619

2483

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

1620

2484

1621

2485

<!ENTITY mysql.close.connections.result.sets '<para xmlns="http://docbook.org/ns/docbook">

...

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

1626

2490

improve performance. For related information, see

1627

2491

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

1628

2492

1629

<!-- Sybase Notes -->

1630

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

1631

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

1632

</simpara></note>'>

1633

1634

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

1635

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

1636

1637

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

1638

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

1639

link identifier is not specified, the last link opened by

1640

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

1641

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

1642

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

1643

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

1644

</varlistentry>'>

1645

1646

<!-- CPDF Notes -->

1647

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

1648

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

1649

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

1650

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

1651

1652

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

1653

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

1654

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

1655

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

1656

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

1657

</listitem></varlistentry>'>

1658

1659

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

1660

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

1661

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

1662

1663

2493

<!-- Xattr entities -->

1664

2494

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

1665

2495

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

...

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

1672

2502

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

1673

2503

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

1674

2504

1675

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

1676

</simpara></note>'>

1677

1678

2505

<!-- Notes for tidy -->

1679

2506

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

1680

2507

...

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

1699

2526

the default MPM with Apache 2.0 and 2.2.

1700

2527

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

1701

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

1702

2538

1703

2539

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

1704

2540

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

...

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

1709

2545

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

1710

2546

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

1711

2547

1712

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

1713

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

2548

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

1714

2549

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

1715

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

1716

2551

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

1717

2552

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

1718

2553

alphabetical order.

...

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

1736

2571

1737

2572

<!ENTITY listendand ' and'>

1738

2573

1739

<!-- classkit and runkit entities -->

1740

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

1741

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

1742

</note>'>

1743

2574

<!-- runkit entities -->

1744

2575

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

1745

2576

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

1746

2577

</note>'>

1747

2578

1748

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

1749

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

1750

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

1751

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

1752

safety be enabled.

1753

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

1754

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

1755

1756

2579

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

1757

2580

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

1758

2581

override internal functions, you must enable the

...

@@ -1770,9 +2593,17 @@ using public key authentication, use the

1770

2593

<!ENTITY returns.session.storage.retval 'The return value (usually &true; on success, &false; on failure). Note this value is returned internally to PHP for processing.'>

1771

2594

1772

2595

<!-- XMLWriter Notes -->

1773

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

1774

xmlwriter</parameter></term><listitem><para>Only for procedural calls.

1775

The XMLWriter <type>resource</type> that is being modified. This resource comes from a call to <function>xmlwriter_open_uri</function> or <function>xmlwriter_open_memory</function>.</para></listitem></varlistentry>'>

2596

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

2597

<parameter>writer</parameter></term><listitem><para>Only for procedural calls.

2598

The <classname>XMLWriter</classname> instance that is being modified. This object is returned from a call to <function>xmlwriter_open_uri</function> or <function>xmlwriter_open_memory</function>.</para></listitem></varlistentry>'>

2599

2600

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

2601

 <entry>8.0.0</entry>

2602

 <entry>

2603

  <parameter>writer</parameter> expects an <classname>XMLWriter</classname>

2604

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

2605

 </entry>

2606

</row>'>

1776

2607

1777

2608

<!-- SOAP notes -->

1778

2609

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

...

@@ -1824,6 +2655,8 @@ The XMLWriter <type>resource</type> that is being modified. This resource comes

1824

2655

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

1825

2656

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

1826

2657

2658

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

2659

1827

2660

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

1828

2661

1829

2662

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

...

@@ -1887,13 +2720,6 @@ The XMLWriter <type>resource</type> that is being modified. This resource comes

1887

2720

</para>

1888

2721

</note>

1889

2722

'>

1890

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

1891

 <simpara>

1892

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

1893

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

1894

 </simpara>

1895

</note>

1896

'>

1897

2723

1898

2724

<!-- phar -->

1899

2725

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

...

@@ -1901,16 +2727,23 @@ method requires the &php.ini; setting <literal>phar.readonly</literal> to be

1901

2727

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

1902

2728

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

1903

2729

1904

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

1905

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

1906

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

1907

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

1908

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

2730

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

2731

 <simpara>

2732

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

2733

  save a new phar archive each time they are called. If performance is a concern,

2734

  <function>Phar::buildFromDirectory</function> or <function>Phar::buildFromIterator</function>

2735

  should be used instead.

2736

 </simpara>

2737

</note>'>

1909

2738

1910

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

1911

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

1912

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

1913

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

2739

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

2740

 <simpara>

2741

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

2742

  save a new phar archive each time they are called. If performance is a concern,

2743

  <function>PharData::buildFromDirectory</function> or <function>PharData::buildFromIterator</function>

2744

  should be used instead.

2745

 </simpara>

2746

</note>'>

1914

2747

1915

2748

<!-- XML -->

1916

2749

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

...

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

1936

2769

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

1937

2770

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

1938

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

1939

2775

<!-- Gmagick -->

1940

2776

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

1941

2777

<!ENTITY gmagick.gmagickexception.throw 'Throws an

...

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

1954

2790

1955

2791

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

1956

2792

1957

<!-- SPL -->

1958

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

1959

1960

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

1961

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

1962

1963

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

1964

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

1965

1966

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

1967

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

1968

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

1969

1970

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

1971

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

2793

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

2794

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

2795

<listitem>

2796

 <para>

2797

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

2798

  instances for attributes matching this class name.

2799

 </para>

2800

</listitem>

2801

</varlistentry>'>

1972

2802

1973

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

1974

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

2803

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

2804

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

2805

<listitem>

2806

 <para>

2807

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

2808

  is provided.

2809

 </para>

2810

 <para>

2811

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

2812

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

2813

 </para>

2814

 <para>

2815

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

2816

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

2817

 </para>

2818

</listitem>

2819

</varlistentry>'>

1975

2820

1976

2821

<!-- ZIP -->

1977

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

...

@@ -1979,7 +2824,7 @@ to be references, then they must be references in the passed argument list.'>

1979

2824

<!-- Win32Service -->

1980

2825

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

1981

2826

<!ENTITY win32service.success.false.error 'Returns &true; on success&win32service.false.error;'>

1982

<!ENTITY win32service.noerror.false.error 'Returns <constant xmlns="http://docbook.org/ns/docbook">WIN32_NO_ERROR</constant> on success&win32service.false.error;'>

2827

<!ENTITY win32service.noerror.false.error 'returned <constant xmlns="http://docbook.org/ns/docbook">WIN32_NO_ERROR</constant> on success&win32service.false.error;'>

1983

2828

1984

2829

<!-- SNMP -->

1985

2830

<!ENTITY snmp.set.type.values '<para xmlns="http://docbook.org/ns/docbook">

...

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

2078

2923

</varlistentry>

2079

2924

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

2080

2925

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

2081

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

2082

2927

</varlistentry>

2083

2928

</variablelist>

2084

2929

</para>

...

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

2123

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

2124

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

2125

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

2126

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

2127

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

2128

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

2129

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

...

@@ -2132,70 +2977,78 @@ paths</simpara></warning>

2132

2977

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

2133

2978

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

2134

2979

2135

<!-- Mongo -->

2136

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

2137

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

2138

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

2139

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

2140

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

2141

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

2142

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

2143

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

2144

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

2145

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

2146

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

2147

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

2148

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

2149

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

2150

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

2151

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

2152

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

2153

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

2154

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

2155

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

2156

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

2157

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

2158

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

2159

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

2160

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

2161

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

2162

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

2163

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

2164

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

2165

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

2166

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

2167

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

2168

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

2169

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

2170

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

2171

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

2172

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

2173

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

2174

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

2175

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

2176

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

2177

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

2178

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

2179

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

2180

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

2181

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

2182

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

2183

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

2184

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

2185

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

2186

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

2187

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

2188

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

2189

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

2190

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

2191

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

2192

2193

<!ENTITY mongo.deprecated.note '<para

2194

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

2195

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

2196

used.</para>'>

2197

2198

2980

<!-- mongodb -->

2981

<!ENTITY mongodb.changelog.class-removed '

2982

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

2983

        <entry>PECL mongodb 2.0.0</entry>

2984

        <entry>

2985

         This class was removed.

2986

        </entry>

2987

       </row>

2988

'>

2989

2990

<!ENTITY mongodb.changelog.function-removed '

2991

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

2992

        <entry>PECL mongodb 2.0.0</entry>

2993

        <entry>

2994

         This function was removed.

2995

        </entry>

2996

       </row>

2997

'>

2998

2999

<!ENTITY mongodb.changelog.method-removed '

3000

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

3001

        <entry>PECL mongodb 2.0.0</entry>

3002

        <entry>

3003

         This method was removed.

3004

        </entry>

3005

       </row>

3006

'>

3007

3008

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

3009

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

3010

        <entry>PECL mongodb 2.0.0</entry>

3011

        <entry>

3012

         <para>

3013

          This class no longer implements the

3014

          <interfacename>Serializable</interfacename> interface.

3015

         </para>

3016

        </entry>

3017

       </row>

3018

'>

3019

3020

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

3021

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

3022

        <entry>PECL mongodb 1.15.0</entry>

3023

        <entry>

3024

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

3025

         triggering deprecation notices in code that implements this interface

3026

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

3027

         attribute can be added to silence the deprecation notice.

3028

        </entry>

3029

       </row>

3030

'>

3031

3032

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

3033

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

3034

        <entry>PECL mongodb 2.0.0</entry>

3035

        <entry>

3036

         Return types previously declared as tentative are now enforced.

3037

        </entry>

3038

       </row>

3039

'>

3040

3041

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

3042

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

3043

        <entry>PECL mongodb 2.0.0</entry>

3044

        <entry>

3045

         <para>

3046

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

3047

         </para>

3048

        </entry>

3049

       </row>

3050

'>

3051

2199

3052

<!ENTITY mongodb.option.collation '

2200

3053

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

2201

3054

          <entry>collation</entry>

...

@@ -2213,6 +3066,20 @@ used.</para>'>

2213

3066

          </entry>

2214

3067

         </row>

2215

3068

'>

3069

<!ENTITY mongodb.option.let '

3070

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

3071

          <entry>let</entry>

3072

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

3073

          <entry>

3074

           <para>

3075

            Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an aggregate expression context (e.g. <literal>$$var</literal>).

3076

           </para>

3077

           <para>

3078

            This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.

3079

           </para>

3080

          </entry>

3081

         </row>

3082

'>

2216

3083

<!ENTITY mongodb.option.encryption.keyVaultClient '

2217

3084

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

2218

3085

          <entry>keyVaultClient</entry>

...

@@ -2224,54 +3091,258 @@ used.</para>'>

2224

3091

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

2225

3092

          <entry>keyVaultNamespace</entry>

2226

3093

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

2227

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

3094

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

2228

3095

         </row>

2229

3096

'>

2230

3097

<!ENTITY mongodb.option.encryption.kmsProviders '

2231

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

3098

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

2232

3099

          <entry>kmsProviders</entry>

2233

3100

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

2234

3101

          <entry>

2235

3102

           <para>

2236

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

3103

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

3104

           </para>

3105

           <para>

3106

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

3107

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

3108

            will attempt to configure the provider using

3109

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

2237

3110

           </para>

2238

3111

           <para>

2239

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

3112

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

2240

3113

           </para>

2241

3114

           <programlisting role="javascript">

2242

3115

<![CDATA[

2243

3116

aws: {

2244

3117

    accessKeyId: <string>,

2245

    secretAccessKey: <string>

3118

    secretAccessKey: <string>,

3119

    sessionToken: <optional string>

2246

3120

}

2247

3121

]]>

2248

3122

           </programlisting>

2249

3123

           <para>

2250

            The format for <literal>local</literal> is as follows:

3124

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

2251

3125

           </para>

2252

3126

           <programlisting role="javascript">

2253

3127

<![CDATA[

2254

local: {

2255

    // The master key used to encrypt/decrypt data keys

2256

    key: <96-byte MongoDB\BSON\Binary with subtype 0>

3128

azure: {

3129

    tenantId: <string>,

3130

    clientId: <string>,

3131

    clientSecret: <string>,

3132

    identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"

2257

3133

}

2258

3134

]]>

2259

3135

           </programlisting>

2260

          </entry>

2261

         </row>

2262

'>

2263

<!ENTITY mongodb.option.maxCommitTimeMS '

2264

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

2265

          <entry>maxCommitTimeMS</entry>

2266

          <entry>integer</entry>

2267

          <entry>

2268

3136

           <para>

2269

            The maximum amount of time in milliseconds to allow a single

2270

            <literal>commitTransaction</literal> command to run.

3137

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

3138

           </para>

3139

           <programlisting role="javascript">

3140

<![CDATA[

3141

gcp: {

3142

    email: <string>,

3143

    privateKey: <base64 string>|<MongoDB\BSON\Binary>,

3144

    endpoint: <optional string> // Defaults to "oauth2.googleapis.com"

3145

}

3146

]]>

3147

           </programlisting>

3148

           <para>

3149

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

2271

3150

           </para>

3151

           <programlisting role="javascript">

3152

<![CDATA[

3153

kmip: {

3154

    endpoint: <string>

3155

}

3156

]]>

3157

           </programlisting>

2272

3158

           <para>

2273

            If specified, <literal>maxCommitTimeMS</literal> must be a signed

2274

            32-bit integer greater than or equal to zero.

3159

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

3160

           </para>

3161

           <programlisting role="javascript">

3162

<![CDATA[

3163

local: {

3164

    // 96-byte master key used to encrypt/decrypt data keys

3165

    key: <base64 string>|<MongoDB\BSON\Binary>

3166

}

3167

]]>

3168

           </programlisting>

3169

          </entry>

3170

         </row>

3171

'>

3172

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

3173

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

3174

   <table>

3175

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

3176

    <tgroup cols="3">

3177

     <thead>

3178

      <row>

3179

       <entry>Option</entry>

3180

       <entry>Type</entry>

3181

       <entry>Description</entry>

3182

      </row>

3183

     </thead>

3184

     <tbody>

3185

      <row>

3186

       <entry>region</entry>

3187

       <entry>string</entry>

3188

       <entry>Required.</entry>

3189

      </row>

3190

      <row>

3191

       <entry>key</entry>

3192

       <entry>string</entry>

3193

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

3194

      </row>

3195

      <row>

3196

       <entry>endpoint</entry>

3197

       <entry>string</entry>

3198

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

3199

      </row>

3200

     </tbody>

3201

    </tgroup>

3202

   </table>

3203

  </para>

3204

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

3205

   <table>

3206

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

3207

    <tgroup cols="3">

3208

     <thead>

3209

      <row>

3210

       <entry>Option</entry>

3211

       <entry>Type</entry>

3212

       <entry>Description</entry>

3213

      </row>

3214

     </thead>

3215

     <tbody>

3216

      <row>

3217

       <entry>keyVaultEndpoint</entry>

3218

       <entry>string</entry>

3219

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

3220

      </row>

3221

      <row>

3222

       <entry>keyName</entry>

3223

       <entry>string</entry>

3224

       <entry>Required.</entry>

3225

      </row>

3226

      <row>

3227

       <entry>keyVersion</entry>

3228

       <entry>string</entry>

3229

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

3230

      </row>

3231

     </tbody>

3232

    </tgroup>

3233

   </table>

3234

  </para>

3235

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

3236

   <table>

3237

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

3238

    <tgroup cols="3">

3239

     <thead>

3240

      <row>

3241

       <entry>Option</entry>

3242

       <entry>Type</entry>

3243

       <entry>Description</entry>

3244

      </row>

3245

     </thead>

3246

     <tbody>

3247

      <row>

3248

       <entry>projectId</entry>

3249

       <entry>string</entry>

3250

       <entry>Required.</entry>

3251

      </row>

3252

      <row>

3253

       <entry>location</entry>

3254

       <entry>string</entry>

3255

       <entry>Required.</entry>

3256

      </row>

3257

      <row>

3258

       <entry>keyRing</entry>

3259

       <entry>string</entry>

3260

       <entry>Required.</entry>

3261

      </row>

3262

      <row>

3263

       <entry>keyName</entry>

3264

       <entry>string</entry>

3265

       <entry>Required.</entry>

3266

      </row>

3267

      <row>

3268

       <entry>keyVersion</entry>

3269

       <entry>string</entry>

3270

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

3271

      </row>

3272

      <row>

3273

       <entry>endpoint</entry>

3274

       <entry>string</entry>

3275

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

3276

      </row>

3277

     </tbody>

3278

    </tgroup>

3279

   </table>

3280

  </para>

3281

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

3282

   <table>

3283

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

3284

    <tgroup cols="3">

3285

     <thead>

3286

      <row>

3287

       <entry>Option</entry>

3288

       <entry>Type</entry>

3289

       <entry>Description</entry>

3290

      </row>

3291

     </thead>

3292

     <tbody>

3293

      <row>

3294

       <entry>keyId</entry>

3295

       <entry>string</entry>

3296

       <entry>Optional. Unique identifier to a 96-byte KMIP secret data managed object. If unspecified, the driver creates a random 96-byte KMIP secret data managed object.</entry>

3297

      </row>

3298

      <row>

3299

       <entry>endpoint</entry>

3300

       <entry>string</entry>

3301

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

3302

      </row>

3303

      <row>

3304

       <entry>delegated</entry>

3305

       <entry>bool</entry>

3306

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

3307

      </row>

3308

     </tbody>

3309

    </tgroup>

3310

   </table>

3311

  </para>

3312

'>

3313

<!ENTITY mongodb.option.encryption.tlsOptions '

3314

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

3315

          <entry>tlsOptions</entry>

3316

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

3317

          <entry>

3318

           <para>

3319

            A document containing the TLS configuration for one or more KMS providers. Supported providers include <literal>"aws"</literal>, <literal>"azure"</literal>, <literal>"gcp"</literal>, and <literal>"kmip"</literal>. All providers support the following options:

3320

           </para>

3321

           <programlisting role="javascript">

3322

<![CDATA[

3323

<provider>: {

3324

    tlsCaFile: <optional string>,

3325

    tlsCertificateKeyFile: <optional string>,

3326

    tlsCertificateKeyFilePassword: <optional string>,

3327

    tlsDisableOCSPEndpointCheck: <optional bool>

3328

}

3329

]]>

3330

           </programlisting>

3331

          </entry>

3332

         </row>

3333

'>

3334

<!ENTITY mongodb.option.maxCommitTimeMS '

3335

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

3336

          <entry>maxCommitTimeMS</entry>

3337

          <entry>integer</entry>

3338

          <entry>

3339

           <para>

3340

            The maximum amount of time in milliseconds to allow a single

3341

            <literal>commitTransaction</literal> command to run.

3342

           </para>

3343

           <para>

3344

            If specified, <literal>maxCommitTimeMS</literal> must be a signed

3345

            32-bit integer greater than or equal to zero.

2275

3346

           </para>

2276

3347

          </entry>

2277

3348

         </row>

...

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

2368

3439

    </listitem>

2369

3440

   </varlistentry>

2370

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

'>

2371

3452

<!ENTITY mongodb.parameter.command '

2372

3453

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

2373

3454

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

...

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

2378

3459

    </listitem>

2379

3460

   </varlistentry>

2380

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

'>

2381

3628

<!ENTITY mongodb.parameter.query '

2382

3629

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

2383

3630

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

...

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

2408

3655

     </para>

2409

3656

     <note>

2410

3657

      <simpara>

2411

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

2412

3659

      </simpara>

2413

3660

     </note>

2414

3661

    </listitem>

...

@@ -2416,14 +3663,20 @@ local: {

2416

3663

'>

2417

3664

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

2418

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

2419

3667

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

2420

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

2421

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

2422

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

2423

3672

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

2424

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

2425

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

2426

3675

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

3676

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

3677

3678

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

3679

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

2427

3680

2428

3681

<!ENTITY mongodb.note.decimal128 '

2429

3682

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

...

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

2451

3704

<!ENTITY mongodb.note.forking '

2452

3705

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

2453

3706

    <simpara>

2454

     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

2455

3708

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

2456

3709

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

2457

3710

     child process.

...

@@ -2493,6 +3746,18 @@ local: {

2493

3746

  </note>

2494

3747

'>

2495

3748

3749

<!ENTITY mongodb.warning.duplicate-keys '

3750

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

3751

    <simpara>

3752

     BSON documents can technically contain duplicate keys because documents are

3753

     stored as a list of key-value pairs; however, applications should refrain

3754

     from generating documents with duplicate keys as server and driver behavior

3755

     may be undefined. Since PHP objects and arrays cannot have duplicate keys,

3756

     data could also be lost when decoding a BSON document with duplicate keys.

3757

    </simpara>

3758

   </warning>

3759

'>

3760

2496

3761

<!-- Radius -->

2497

3762

<!ENTITY radius.request.required '<note xmlns="http://docbook.org/ns/docbook"><para>A request must be created via <function>radius_create_request</function> before this function can be called.</para></note>'>

2498

3763

<!ENTITY radius.parameter.attribute-type '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>type</parameter></term><listitem><para>The attribute type.</para></listitem></varlistentry>'>

...

@@ -2503,17 +3768,14 @@ local: {

2503

3768

2504

3769

<!-- posix snippets -->

2505

3770

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

2506

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

3771

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

2507

3772

 <listitem>

2508

3773

  <para>

2509

3774

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

2510

   <type>resource</type> or an <type>integer</type>. An <type>integer</type>

3775

   <type>resource</type> or an <type>int</type>. An <type>int</type>

2511

3776

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

2512

3777

   the underlying system call.

2513

3778

  </para>

2514

  <para>

2515

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

2516

  </para>

2517

3779

 </listitem>

2518

3780

</varlistentry>'>

2519

3781

...

@@ -2528,24 +3790,219 @@ local: {

2528

3790

'>

2529

3791

2530

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

2531

3991

<!ENTITY strings.parameter.encoding '

2532

3992

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

2533

3993

  An optional argument defining the encoding used when converting characters.

2534

3994

 </para>

2535

3995

2536

3996

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

2537

  If omitted, the default value of the <parameter>encoding</parameter> varies

2538

  depending on the PHP version in use. In PHP 5.6 and later, the

3997

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

2539

3998

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

2540

  option is used as the default value. PHP 5.4 and 5.5 will use

2541

  <literal>UTF-8</literal> as the default. Earlier versions of PHP use

2542

  <literal>ISO-8859-1</literal>.

3999

  option.

2543

4000

 </para>

2544

4001

2545

4002

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

2546

4003

  Although this argument is technically optional, you are highly encouraged to

2547

  specify the correct value for your code if you are using PHP 5.5 or earlier,

2548

  or if your <link linkend="ini.default-charset">default_charset</link>

4004

  specify the correct value for your code

4005

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

2549

4006

  configuration option may be set incorrectly for the given input.

2550

4007

 </para>

2551

4008

'>

...

@@ -2575,71 +4032,77 @@ local: {

2575

4032

   </para>

2576

4033

  </formalpara>

2577

4034

2578

  <para>

2579

   <table>

2580

    <title>Flags</title>

2581

    <tgroup cols="2">

2582

     <thead>

2583

      <row>

2584

       <entry>Flag</entry>

2585

       <entry>&Description;</entry>

2586

      </row>

2587

     </thead>

2588

     <tbody>

2589

      <row>

2590

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

2591

       <entry>

2592

        Left-justify within the given field width;

2593

        Right justification is the default

2594

       </entry>

2595

      </row>

2596

      <row>

2597

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

2598

       <entry>

2599

        Prefix positive numbers with a plus sign

2600

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

2601

        are prefixed with a negative sign.

2602

       </entry>

2603

      </row>

2604

      <row>

2605

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

2606

       <entry>

2607

        Pads the result with spaces.

2608

        This is the default.

2609

       </entry>

2610

      </row>

2611

      <row>

2612

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

2613

       <entry>

2614

        Only left-pads numbers with zeros.

2615

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

2616

        also right-pad with zeros.

2617

       </entry>

2618

      </row>

2619

      <row>

2620

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

2621

       <entry>

2622

        Pads the result with the character (char).

2623

       </entry>

2624

      </row>

2625

     </tbody>

2626

    </tgroup>

2627

   </table>

2628

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

2629

4088

2630

4089

  <formalpara>

2631

4090

   <title>Width</title>

2632

4091

   <para>

2633

    An integer that says how many characters (minimum)

2634

    this conversion should result in.

4092

    Either an integer that says how many characters (minimum)

4093

    this conversion should result in, or <literal>*</literal>.

4094

    If <literal>*</literal> is used, then the width is supplied

4095

    as an additional integer value preceding the one formatted

4096

    by the specifier.

2635

4097

   </para>

2636

4098

  </formalpara>

2637

4099

2638

4100

  <formalpara>

2639

4101

   <title>Precision</title>

2640

4102

   <para>

2641

    A period <literal>.</literal> followed by an integer

2642

    who&apos;s meaning depends on the specifier:

4103

    A period <literal>.</literal> optionally followed by

4104

    either an integer or <literal>*</literal>,

4105

    whose meaning depends on the specifier:

2643

4106

    <itemizedlist>

2644

4107

     <listitem>

2645

4108

      <simpara>

...

@@ -2651,7 +4114,8 @@ local: {

2651

4114

     </listitem>

2652

4115

     <listitem>

2653

4116

      <simpara>

2654

       For <literal>g</literal> and <literal>G</literal>

4117

       For <literal>g</literal>, <literal>G</literal>,

4118

       <literal>h</literal> and <literal>H</literal>

2655

4119

       specifiers: this is the maximum number of significant

2656

4120

       digits to be printed.

2657

4121

      </simpara>

...

@@ -2666,19 +4130,14 @@ local: {

2666

4130

    <note>

2667

4131

     <simpara>

2668

4132

      If the period is specified without an explicit value for precision,

2669

      0 is assumed.

4133

      0 is assumed. If <literal>*</literal> is used, the precision is

4134

      supplied as an additional integer value preceding the one formatted

4135

      by the specifier.

2670

4136

     </simpara>

2671

4137

    </note>

2672

4138

   </para>

2673

4139

  </formalpara>

2674

4140

2675

  <note>

2676

   <simpara>

2677

    Attempting to use a position specifier greater than

2678

    <constant>PHP_INT_MAX</constant> will generate warnings.

2679

   </simpara>

2680

  </note>

2681

2682

4141

  <para>

2683

4142

   <table>

2684

4143

    <title>Specifiers</title>

...

@@ -2721,9 +4180,6 @@ local: {

2721

4180

       <entry><literal>e</literal></entry>

2722

4181

       <entry>

2723

4182

        The argument is treated as scientific notation (e.g. 1.2e+2).

2724

        The precision specifier stands for the number of digits after the

2725

        decimal point since PHP 5.2.1. In earlier versions, it was taken as

2726

        number of significant digits (one less).

2727

4183

       </entry>

2728

4184

      </row>

2729

4185

      <row>

...

@@ -2745,7 +4201,6 @@ local: {

2745

4201

       <entry>

2746

4202

        The argument is treated as a float and presented

2747

4203

        as a floating-point number (non-locale aware).

2748

        Available as of PHP 5.0.3.

2749

4204

       </entry>

2750

4205

      </row>

2751

4206

      <row>

...

@@ -2772,6 +4227,20 @@ local: {

2772

4227

        <literal>E</literal> and <literal>f</literal>.

2773

4228

       </entry>

2774

4229

      </row>

4230

      <row>

4231

       <entry><literal>h</literal></entry>

4232

       <entry>

4233

        Like the <literal>g</literal> specifier but uses <literal>F</literal>.

4234

        Available as of PHP 8.0.0.

4235

       </entry>

4236

      </row>

4237

      <row>

4238

       <entry><literal>H</literal></entry>

4239

       <entry>

4240

        Like the <literal>g</literal> specifier but uses

4241

        <literal>E</literal> and <literal>F</literal>. Available as of PHP 8.0.0.

4242

       </entry>

4243

      </row>

2775

4244

      <row>

2776

4245

       <entry><literal>o</literal></entry>

2777

4246

       <entry>

...

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

2813

4282

2814

4283

  <warning>

2815

4284

   <para>

2816

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

4285

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

2817

4286

   </para>

2818

4287

  </warning>

2819

4288

2820

4289

  <warning>

2821

4290

   <para>

2822

    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.

2823

4292

   </para>

2824

4293

  </warning>

2825

4294

...

@@ -2836,11 +4305,11 @@ local: {

2836

4305

     </thead>

2837

4306

     <tbody>

2838

4307

      <row>

2839

       <entry><literal>string</literal></entry>

4308

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

2840

4309

       <entry><literal>s</literal></entry>

2841

4310

      </row>

2842

4311

      <row>

2843

       <entry><literal>integer</literal></entry>

4312

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

2844

4313

       <entry>

2845

4314

        <literal>d</literal>,

2846

4315

        <literal>u</literal>,

...

@@ -2852,14 +4321,16 @@ local: {

2852

4321

       </entry>

2853

4322

      </row>

2854

4323

      <row>

2855

       <entry><literal>double</literal></entry>

4324

       <entry><type>float</type></entry>

2856

4325

       <entry>

2857

        <literal>g</literal>,

2858

        <literal>G</literal>,

2859

4326

        <literal>e</literal>,

2860

4327

        <literal>E</literal>,

2861

4328

        <literal>f</literal>,

2862

        <literal>F</literal>

4329

        <literal>F</literal>,

4330

        <literal>g</literal>,

4331

        <literal>G</literal>,

4332

        <literal>h</literal>,

4333

        <literal>H</literal>

2863

4334

       </entry>

2864

4335

      </row>

2865

4336

     </tbody>

...

@@ -2870,9 +4341,47 @@ local: {

2870

4341

</varlistentry>

2871

4342

'>

2872

4343

4344

<!ENTITY strings.scanf.parameter.format '

4345

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

4346

     <term><parameter>format</parameter></term>

4347

     <listitem>

4348

      <para>

4349

       The interpreted format for <parameter>string</parameter>, which is

4350

       described in the documentation for <function>sprintf</function> with

4351

       following differences:

4352

       <simplelist>

4353

        <member>

4354

         Function is not locale-aware.

4355

        </member>

4356

        <member>

4357

         <literal>F</literal>, <literal>g</literal>, <literal>G</literal> and

4358

         <literal>b</literal> are not supported.

4359

        </member>

4360

        <member>

4361

         <literal>D</literal> stands for decimal number.

4362

        </member>

4363

        <member>

4364

         <literal>i</literal> stands for integer with base detection.

4365

        </member>

4366

        <member>

4367

         <literal>n</literal> stands for number of characters processed so far.

4368

        </member>

4369

        <member>

4370

         <literal>s</literal> stops reading at any whitespace character.

4371

        </member>

4372

        <member>

4373

         <literal>*</literal> instead of <literal>argnum$</literal> suppresses

4374

         the assignment of this conversion specification.

4375

        </member>

4376

       </simplelist>

4377

      </para>

4378

     </listitem>

4379

    </varlistentry>

4380

'>

4381

2873

4382

<!ENTITY strings.parameter.needle.non-string '

2874

4383

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

2875

  If <parameter>needle</parameter> is not a string, it is converted

4384

  Prior to PHP 8.0.0, if <parameter>needle</parameter> is not a string, it is converted

2876

4385

  to an integer and applied as the ordinal value of a character.

2877

4386

  This behavior is deprecated as of PHP 7.3.0, and relying on it is highly

2878

4387

  discouraged. Depending on the intended behavior, the

...

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

2881

4390

 </para>

2882

4391

'>

2883

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

2884

4400

<!ENTITY strings.changelog.encoding '

2885

4401

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

2886

4402

  <entry>5.6.0</entry>

...

@@ -2893,19 +4409,193 @@ local: {

2893

4409

 </row>

2894

4410

'>

2895

4411

4412

<!ENTITY strings.changelog.ascii-case-conversion '

4413

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

4414

  <entry>8.2.0</entry>

4415

  <entry>

4416

   Case conversion no longer depends on the locale set with

4417

   <function>setlocale</function>. Only ASCII characters will be converted.

4418

  </entry>

4419

 </row>

4420

'>

4421

4422

<!ENTITY strings.changelog.ascii-case-folding '

4423

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

4424

  <entry>8.2.0</entry>

4425

  <entry>

4426

   Case folding no longer depends on the locale set with

4427

   <function>setlocale</function>. Only ASCII case folding will be done.

4428

   Non-ASCII bytes will be compared by their byte value.

4429

  </entry>

4430

 </row>

4431

'>

4432

4433

<!ENTITY strings.changelog.sprintf '

4434

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

4435

   <tgroup cols="2">

4436

    <thead>

4437

     <row>

4438

      <entry>&Version;</entry>

4439

      <entry>&Description;</entry>

4440

     </row>

4441

    </thead>

4442

    <tbody>

4443

     <row>

4444

      <entry>8.0.0</entry>

4445

      <entry>

4446

       This function no longer returns &false; on failure.

4447

      </entry>

4448

     </row>

4449

     <row>

4450

      <entry>8.0.0</entry>

4451

      <entry>

4452

       Throw a <classname>ValueError</classname> if the number of arguments is zero;

4453

       previously this function emitted a <constant>E_WARNING</constant> instead.

4454

      </entry>

4455

     </row>

4456

     <row>

4457

      <entry>8.0.0</entry>

4458

      <entry>

4459

       Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;

4460

       previously this function emitted a <constant>E_WARNING</constant> instead.

4461

      </entry>

4462

     </row>

4463

     <row>

4464

      <entry>8.0.0</entry>

4465

      <entry>

4466

       Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;

4467

       previously this function emitted a <constant>E_WARNING</constant> instead.

4468

      </entry>

4469

     </row>

4470

     <row>

4471

      <entry>8.0.0</entry>

4472

      <entry>

4473

       Throw a <classname>ArgumentCountError</classname> when less arguments are given than required;

4474

       previously this function emitted a <constant>E_WARNING</constant> instead.

4475

      </entry>

4476

     </row>

4477

    </tbody>

4478

   </tgroup>

4479

  </informaltable>

4480

'>

4481

4482

<!ENTITY strings.changelog.vsprintf '

4483

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

4484

   <tgroup cols="2">

4485

    <thead>

4486

     <row>

4487

      <entry>&Version;</entry>

4488

      <entry>&Description;</entry>

4489

     </row>

4490

    </thead>

4491

    <tbody>

4492

     <row>

4493

      <entry>8.0.0</entry>

4494

      <entry>

4495

       This function no longer returns &false; on failure.

4496

      </entry>

4497

     </row>

4498

     <row>

4499

      <entry>8.0.0</entry>

4500

      <entry>

4501

       Throw a <classname>ValueError</classname> if the number of arguments is zero;

4502

       previously this function emitted a <constant>E_WARNING</constant> instead.

4503

      </entry>

4504

     </row>

4505

     <row>

4506

      <entry>8.0.0</entry>

4507

      <entry>

4508

       Throw a <classname>ValueError</classname> if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;

4509

       previously this function emitted a <constant>E_WARNING</constant> instead.

4510

      </entry>

4511

     </row>

4512

     <row>

4513

      <entry>8.0.0</entry>

4514

      <entry>

4515

       Throw a <classname>ValueError</classname> if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>;

4516

       previously this function emitted a <constant>E_WARNING</constant> instead.

4517

      </entry>

4518

     </row>

4519

     <row>

4520

      <entry>8.0.0</entry>

4521

      <entry>

4522

       Throw a <classname>ValueError</classname> when less arguments are given than required;

4523

       previously this function emitted a <constant>E_WARNING</constant> instead.

4524

      </entry>

4525

     </row>

4526

    </tbody>

4527

   </tgroup>

4528

  </informaltable>

4529

'>

4530

4531

<!ENTITY strings.errors.sprintf '

4532

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

4533

   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.

4534

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4535

  </para>

4536

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

4537

   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.

4538

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4539

  </para>

4540

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

4541

   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.

4542

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4543

  </para>

4544

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

4545

   As of PHP 8.0.0, a <classname>ArgumentCountError</classname> is thrown when less arguments are given than required.

4546

   Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.

4547

  </para>

4548

'>

4549

4550

<!ENTITY strings.errors.vsprintf '

4551

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

4552

   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the number of arguments is zero.

4553

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4554

  </para>

4555

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

4556

   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[width]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.

4557

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4558

  </para>

4559

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

4560

   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if <literal>[precision]</literal> is less than zero or bigger than <constant>PHP_INT_MAX</constant>.

4561

   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.

4562

  </para>

4563

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

4564

   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown when less arguments are given than required.

4565

   Prior to PHP 8.0.0, &false; was returned and a <constant>E_WARNING</constant> emitted instead.

4566

  </para>

4567

'>

4568

4569

<!ENTITY strings.comparison.return '

4570

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

4571

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

4572

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

4573

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

4574

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

4575

   are equal.

4576

   No particular meaning can be reliably inferred from the value aside

4577

   from its sign.

4578

  </simpara>

4579

'>

4580

2896

4581

<!-- filter snippets -->

4582

<!-- TODO: Remove -->

2897

4583

<!ENTITY filter.param.filter '

2898

4584

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

2899

4585

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

2900

4586

  <listitem>

2901

4587

   <para>

2902

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

2903

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

2904

4595

   </para>

2905

4596

   <para>

2906

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

2907

    equivalent to

2908

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

2909

4599

    This will result in no filtering taking place by default.

2910

4600

   </para>

2911

4601

  </listitem>

...

@@ -2915,34 +4605,65 @@ local: {

2915

4605

<!-- csprng snippets -->

2916

4606

<!ENTITY csprng.sources '

2917

4607

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

2918

 The sources of randomness used for this function are as follows:

4608

 The sources of randomness in the order of priority are as follows:

2919

4609

</para>

2920

4610

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

2921

4611

 <listitem>

2922

  <simpara>

2923

   On Windows,

2924

   <link xlink:href="&url.csprng.crypt-gen-random;"><function>CryptGenRandom</function></link>

2925

   will always be used. As of PHP 7.2.0, the

2926

   <link xlink:href="&url.csprng.cng-api;">CNG-API</link>

2927

   will always be used instead.

2928

  </simpara>

4612

  <para>

4613

   Linux: <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>

4614

  </para>

2929

4615

 </listitem>

2930

4616

 <listitem>

2931

  <simpara>

2932

   On Linux, the

2933

   <link xlink:href="&url.csprng.get-random-2;">getrandom(2)</link>

2934

   syscall will be used if available.

2935

  </simpara>

4617

  <para>

4618

   FreeBSD &gt;= 12 (PHP &gt;= 7.3): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>

4619

  </para>

4620

 </listitem>

4621

 <listitem>

4622

  <para>

4623

   Windows (PHP &gt;= 7.2): <link xlink:href="&url.csprng.cng-api;">CNG-API</link>

4624

  </para>

4625

  <para>

4626

   Windows: <link xlink:href="&url.csprng.crypt-gen-random;">CryptGenRandom</link>

4627

  </para>

4628

 </listitem>

4629

 <listitem>

4630

  <para>

4631

   macOS (PHP &gt;= 8.2; &gt;= 8.1.9; &gt;= 8.0.22 if CCRandomGenerateBytes is available at compile time): CCRandomGenerateBytes()

4632

  </para>

4633

  <para>

4634

   macOS (PHP &gt;= 8.1; &gt;= 8.0.2): arc4random_buf(), <filename>/dev/urandom</filename>

4635

  </para>

4636

 </listitem>

4637

 <listitem>

4638

  <para>

4639

   NetBSD &gt;= 7 (PHP &gt;= 7.1; &gt;= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>

4640

  </para>

4641

 </listitem>

4642

 <listitem>

4643

  <para>

4644

   OpenBSD &gt;= 5.5 (PHP &gt;= 7.1; &gt;= 7.0.1): arc4random_buf(), <filename>/dev/urandom</filename>

4645

  </para>

4646

 </listitem>

4647

 <listitem>

4648

  <para>

4649

   DragonflyBSD (PHP &gt;= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>

4650

  </para>

4651

 </listitem>

4652

 <listitem>

4653

  <para>

4654

   Solaris (PHP &gt;= 8.1): <link xlink:href="&url.csprng.get-random-2;">getrandom()</link>, <filename>/dev/urandom</filename>

4655

  </para>

2936

4656

 </listitem>

2937

4657

 <listitem>

2938

4658

  <simpara>

2939

   On other platforms, <filename>/dev/urandom</filename> will be used.

4659

   Any combination of operating system and PHP version not previously mentioned: <filename>/dev/urandom</filename>

2940

4660

  </simpara>

2941

4661

 </listitem>

2942

4662

 <listitem>

2943

4663

  <simpara>

2944

   If none of the aforementioned sources are available, then an

2945

   <classname>Exception</classname> will be thrown.

4664

   If none of the sources are available or they all fail to generate

4665

   randomness, then a <classname>Random\RandomException</classname>

4666

   will be thrown.

2946

4667

  </simpara>

2947

4668

 </listitem>

2948

4669

</itemizedlist>

...

@@ -2951,13 +4672,7 @@ local: {

2951

4672

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

2952

4673

  <simpara>

2953

4674

   If an appropriate source of randomness cannot be found,

2954

   an <classname>Exception</classname> will be thrown.

2955

  </simpara>

2956

 </listitem>

2957

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

2958

  <simpara>

2959

    If invalid parameters are given, a <classname>TypeError</classname>

2960

    will be thrown.

4675

   a <classname>Random\RandomException</classname> will be thrown.

2961

4676

  </simpara>

2962

4677

 </listitem>

2963

4678

'>

...

@@ -2971,6 +4686,15 @@ local: {

2971

4686

 </note>

2972

4687

'>

2973

4688

4689

<!-- Random snippets -->

4690

<!ENTITY random.engineErrors '

4691

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

4692

  <simpara>

4693

   Any <classname>Throwable</classname>s thrown by the <methodname>Random\Engine::generate</methodname> method

4694

   of the underlying <link linkend="random-randomizer.props.engine"><literal>Random\Randomizer::$engine</literal></link>.

4695

  </simpara>

4696

 </listitem>

4697

'>

2974

4698

2975

4699

<!-- UOPZ snippets -->

2976

4700

...

@@ -2978,6 +4702,83 @@ local: {

2978

4702

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

2979

4703

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

2980

4704

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

4774

4775

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

4776

 <entry>8.0.0</entry>

4777

 <entry>

4778

  <parameter>parser</parameter> expects an <classname>XMLParser</classname>

4779

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

4780

 </entry>

4781

</row>'>

2981

4782

2982

4783

<!-- Migration Guide snippets -->

2983

4784

<!ENTITY migration56.openssl.peer-verification '

2984

4785

Generated: 10 Jul 2025 22:02:34

Translation status