php/archived-doc-en
1
0
Fork 0
mirror of https://github.com/php/doc-en.git synced 2026-03-23 23:32:18 +01:00
Code Issues Packages Projects Releases Wiki Activity

dba: fix XML by converting para to simpara tags via script (#5149)

Browse Source
This commit is contained in:
Gina Peter Banyard
2026-01-18 22:40:20 +00:00
committed by GitHub
parent a6b55f8de6
commit b5fce74a6c
20 changed files with 199 additions and 201 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
reference/dba/book.xml
View File

@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<book xml:id="book.dba" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="book.dba">
<?phpdoc extension-membership="bundled" ?>
<title>Database (dbm-style) Abstraction Layer</title>
<titleabbrev>DBA</titleabbrev>
@@ -8,16 +8,16 @@
<!-- {{{ preface -->
<preface xml:id="intro.dba">
&reftitle.intro;
<para>
<simpara>
These functions build the foundation for accessing Berkeley DB
style databases.
</para>
<para>
</simpara>
<simpara>
This is a general abstraction layer for several file-based databases.
As such, functionality is limited to a common subset of features
supported by modern databases such as
<link xlink:href="&url.berkeleydb;">Oracle Berkeley DB</link>.
</para>
</simpara>
</preface>
<!-- }}} -->
@@ -51,4 +51,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

64
reference/dba/configure.xml
View File

@@ -2,16 +2,16 @@
<!-- $Revision$ -->
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="dba.installation">
&reftitle.install;
<para>
<simpara>
By using the <option role="configure">--enable-dba=shared</option>
configuration option you can build a dynamic loadable module to enable PHP
for basic support of dbm-style databases. You also have to add support
for at least one of the following handlers by specifying the
<option role="configure">--with-XXXX</option> or <option role="configure">--enable-XXXX</option> configure switch to your PHP
configure line.
</para>
</simpara>
<warning>
<para>
<simpara>
After configuring and compiling PHP you must execute the following test
from commandline: <literal>php run-tests.php ext/dba</literal>. This shows
whether your combination of handlers works. Most problematic are
@@ -20,7 +20,7 @@
libraries are part of more than one other library. The configuration test
only prevents you from configuring malfunctioning single handlers but not
combinations.
</para>
</simpara>
</warning>
<table>
<title>Supported DBA handlers</title>
@@ -39,11 +39,11 @@
To enable support for dbm add
<option role="configure">--with-dbm[=DIR]</option>.
<note>
<para>
<simpara>
dbm normally is a wrapper which often results in failures.
This means you should only use dbm if you are sure it works
and if you really need this format.
</para>
</simpara>
</note>
</para>
</entry>
@@ -56,11 +56,11 @@
To enable support for ndbm add
<option role="configure">--with-ndbm[=DIR]</option>.
<note>
<para>
<simpara>
ndbm normally is a wrapper which often results in failures.
This means you should only use ndbm if you are sure it works
and if you really need this format.
</para>
</simpara>
</note>
</para>
</entry>
@@ -81,9 +81,9 @@
To enable support for Oracle Berkeley DB 2 add
<option role="configure">--with-db2[=DIR]</option>.
<note>
<para>
<simpara>
db2 conflicts with db3 and db4.
</para>
</simpara>
</note>
</para>
</entry>
@@ -96,9 +96,9 @@
To enable support for Oracle Berkeley DB 3 add
<option role="configure">--with-db3[=DIR]</option>.
<note>
<para>
<simpara>
db3 conflicts with db2 and db4.
</para>
</simpara>
</note>
</para>
</entry>
@@ -111,18 +111,18 @@
To enable support for Oracle Berkeley DB 4 or 5 add
<option role="configure">--with-db4[=DIR]</option>.
<note>
<para>
<simpara>
db4 conflicts with db2 and db3.
</para>
</simpara>
</note>
<note>
<para>
<simpara>
The db libraries with
versions 4.1 through 4.1.24 cannot be used in any PHP version.
</para>
<para>
</simpara>
<simpara>
Support for BDB 5 was added in PHP 5.3.3.
</para>
</simpara>
</note>
</para>
</entry>
@@ -135,11 +135,11 @@
To enable support for cdb add
<option role="configure">--with-cdb[=DIR]</option>.
<note>
<para>
<simpara>
You can omit DIR to use the bundled cdb library
that adds the cdb_make handler which allows creation of cdb files
and allows to access cdb files on the network using PHP's streams.
</para>
</simpara>
</note>
</para>
</entry>
@@ -154,12 +154,12 @@
Before PHP 5.2.1 the <option role="configure">--with-flatfile</option>
had to be used instead.
<note>
<para>
<simpara>
This was added to add compatibility with deprecated
<literal>dbm</literal> extension. Use this handler only
when you cannot install one of the libraries required by the other
handlers and when you cannot use bundled cdb handler.
</para>
</simpara>
</note>
</para>
</entry>
@@ -174,10 +174,10 @@
Before PHP 5.2.1 the <option role="configure">--with-inifile</option>
had to be used instead.
<note>
<para>
<simpara>
This was added to allow to read and set microsoft style
<filename>.ini</filename> files (like the &php.ini; file).
</para>
</simpara>
</note>
</para>
</entry>
@@ -190,15 +190,15 @@
To enable support for qdbm add
<option role="configure">--with-qdbm[=DIR]</option>.
<note>
<para>
<simpara>
qdbm conflicts with dbm and gdbm.
</para>
</simpara>
</note>
<note>
<para>
<simpara>
The qdbm library can be downloaded from
<link xlink:href="&url.qdbm;"/>.
</para>
</simpara>
</note>
</para>
</entry>
@@ -211,10 +211,10 @@
To enable support for Tokyo Cabinet add
<option role="configure">--with-tcadb[=DIR]</option>.
<note>
<para>
<simpara>
The Tokyo Cabinet library can be downloaded from
<link xlink:href="&url.tcadb;"/>.
</para>
</simpara>
</note>
</para>
</entry>
@@ -227,10 +227,10 @@
To enable support for the Lightning Memory-Mapped Database add
<option role="configure">--with-lmdb[=DIR]</option>.
<note>
<para>
<simpara>
This was added in PHP 7.2.0. The Lightning Memory-Mapped Database
library can be downloaded from <link xlink:href="&url.lmdb;"/>.
</para>
</simpara>
</note>
</para>
</entry>

11
reference/dba/constants.xml
View File

@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<appendix xml:id="dba.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="dba.constants">
&reftitle.constants;
&extension.constants;
<variablelist>
@@ -10,10 +10,10 @@
(<type>int</type>)
</term>
<listitem>
<para>
<simpara>
LMDB Driver flag to allow the creation of a subdirectory for the database files.
Available as of PHP 8.2.0.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.dba-lmdb-no-sub-dir">
@@ -22,10 +22,10 @@
(<type>int</type>)
</term>
<listitem>
<para>
<simpara>
LMDB Driver flag to disallow the creation of a subdirectory for the database files.
Available as of PHP 8.2.0.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -50,4 +50,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

12
reference/dba/examples.xml
View File

@@ -29,22 +29,22 @@ dba_close($id);
]]>
</programlisting>
</example>
<para>
<simpara>
DBA is binary safe and does not have any arbitrary limits.
However, it inherits all limits set by the underlying
database implementation.
</para>
<para>
</simpara>
<simpara>
All file-based databases must provide a way of setting the file
mode of a new created database, if that is possible at all. The
file mode is commonly passed as the fourth argument to
<function>dba_open</function> or <function>dba_popen</function>.
</para>
<para>
</simpara>
<simpara>
You can access all entries of a database in a linear way by using the
<function>dba_firstkey</function> and <function>dba_nextkey</function>
functions. You may not change the database while traversing it.
</para>
</simpara>
<example>
<title>Traversing a database</title>
<programlisting role="php">

12
reference/dba/functions/dba-close.xml
View File

@@ -11,10 +11,10 @@
<type>void</type><methodname>dba_close</methodname>
<methodparam><type>Dba\Connection</type><parameter>dba</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_close</function> closes the established database and frees
all resources of the specified database handle.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -22,18 +22,18 @@
<varlistentry>
<term><parameter>dba</parameter></term>
<listitem>
<para>
<simpara>
&dba.parameter.dba;
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.void;
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

16
reference/dba/functions/dba-delete.xml
View File

@@ -12,9 +12,9 @@
<methodparam><type class="union"><type>string</type><type>array</type></type><parameter>key</parameter></methodparam>
<methodparam><type>Dba\Connection</type><parameter>dba</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_delete</function> deletes the specified entry from the database.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -22,26 +22,26 @@
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
<simpara>
The key of the entry which is deleted.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dba</parameter></term>
<listitem>
<para>
<simpara>
&dba.parameter.dba;
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.success;
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

16
reference/dba/functions/dba-exists.xml
View File

@@ -12,10 +12,10 @@
<methodparam><type class="union"><type>string</type><type>array</type></type><parameter>key</parameter></methodparam>
<methodparam><type>Dba\Connection</type><parameter>dba</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_exists</function> checks whether the specified
<parameter>key</parameter> exists in the database.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -23,26 +23,26 @@
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
<simpara>
The key the check is performed for.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dba</parameter></term>
<listitem>
<para>
<simpara>
&dba.parameter.dba;
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Returns &true; if the key exists, &false; otherwise.
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

24
reference/dba/functions/dba-fetch.xml
View File

@@ -22,11 +22,11 @@
<methodparam><type>int</type><parameter>skip</parameter></methodparam>
<methodparam><type>resource</type><parameter>dba</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_fetch</function> fetches the data specified by
<parameter>key</parameter> from the database specified with
<parameter>dba</parameter>.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -34,34 +34,34 @@
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
<simpara>
The key the data is specified by.
</para>
</simpara>
<note>
<para>
<simpara>
When working with inifiles this function accepts arrays as keys
where index 0 is the group and index 1 is the value name. See:
<function>dba_key_split</function>.
</para>
</simpara>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dba</parameter></term>
<listitem>
<para>
<simpara>
&dba.parameter.dba;
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>skip</parameter></term>
<listitem>
<para>
<simpara>
The number of key-value pairs to ignore when using cdb databases.
This value is ignored for all other databases which do not support
multiple keys with the same name.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -69,10 +69,10 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Returns the associated string if the key/data pair is found, &false;
otherwise.
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

12
reference/dba/functions/dba-firstkey.xml
View File

@@ -11,11 +11,11 @@
<type class="union"><type>string</type><type>false</type></type><methodname>dba_firstkey</methodname>
<methodparam><type>Dba\Connection</type><parameter>dba</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_firstkey</function> returns the first key of the database
and resets the internal key pointer. This permits a linear search through
the whole database.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -23,18 +23,18 @@
<varlistentry>
<term><parameter>dba</parameter></term>
<listitem>
<para>
<simpara>
&dba.parameter.dba;
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Returns the key on success&return.falseforfailure;.
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

16
reference/dba/functions/dba-handlers.xml
View File

@@ -11,10 +11,10 @@
<type>array</type><methodname>dba_handlers</methodname>
<methodparam choice="opt"><type>bool</type><parameter>full_info</parameter><initializer>&false;</initializer></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_handlers</function> list all the handlers supported by this
extension.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -22,26 +22,26 @@
<varlistentry>
<term><parameter>full_info</parameter></term>
<listitem>
<para>
<simpara>
Turns on/off full information display in the result.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Returns an array of database handlers. If <parameter>full_info</parameter>
is set to &true;, the array will be associative with the handlers names as
keys, and their version information as value. Otherwise, the result will be
an indexed array of handlers names.
</para>
</simpara>
<note>
<para>
<simpara>
When the internal cdb library is used you will see
<literal>cdb</literal> and <literal>cdb_make</literal>.
</para>
</simpara>
</note>
</refsect1>
<refsect1 role="examples">

20
reference/dba/functions/dba-insert.xml
View File

@@ -13,11 +13,11 @@
<methodparam><type>string</type><parameter>value</parameter></methodparam>
<methodparam><type>Dba\Connection</type><parameter>dba</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_insert</function> inserts the entry described with
<parameter>key</parameter> and <parameter>value</parameter> into the
database.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -25,36 +25,36 @@
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
<simpara>
The key of the entry to be inserted. If this key already exist in the
database, this function will fail. Use <function>dba_replace</function>
if you need to replace an existent key.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
<simpara>
The value to be inserted.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dba</parameter></term>
<listitem>
<para>
<simpara>
&dba.parameter.dba;
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.success;
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

12
reference/dba/functions/dba-key-split.xml
View File

@@ -13,10 +13,10 @@
<type class="union"><type>array</type><type>false</type></type><methodname>dba_key_split</methodname>
<methodparam><type class="union"><type>string</type><type>false</type><type>null</type></type><parameter>key</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_key_split</function> splits a key (string representation)
into an array representation.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -24,20 +24,20 @@
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
<simpara>
The key in string representation.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Returns an array of the form <literal>array(0 =&gt; group, 1 =&gt;
value_name)</literal>. This function will return &false; if
<parameter>key</parameter> is &null; or &false;.
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

10
reference/dba/functions/dba-list.xml
View File

@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.dba-list" xmlns="http://docbook.org/ns/docbook">
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.dba-list">
<refnamediv>
<refname>dba_list</refname>
<refpurpose>List all open database files</refpurpose>
@@ -11,9 +11,9 @@
<type>array</type><methodname>dba_list</methodname>
<void/>
</methodsynopsis>
<para>
<simpara>
<function>dba_list</function> list all open database files.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -23,9 +23,9 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
An associative array, in the form <literal>resourceid =&gt; filename</literal>.
</para>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

12
reference/dba/functions/dba-nextkey.xml
View File

@@ -11,10 +11,10 @@
<type class="union"><type>string</type><type>false</type></type><methodname>dba_nextkey</methodname>
<methodparam><type>Dba\Connection</type><parameter>dba</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_nextkey</function> returns the next key of the database
and advances the internal key pointer.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -22,18 +22,18 @@
<varlistentry>
<term><parameter>dba</parameter></term>
<listitem>
<para>
<simpara>
&dba.parameter.dba;
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Returns the key on success&return.falseforfailure;.
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

52
reference/dba/functions/dba-open.xml
View File

@@ -16,11 +16,11 @@
<methodparam choice="opt"><type>int</type><parameter>map_size</parameter><initializer>0</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>flags</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_open</function> establishes a database instance for
<parameter>path</parameter> with <parameter>mode</parameter> using
<parameter>handler</parameter>.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -29,29 +29,29 @@
<varlistentry>
<term><parameter>path</parameter></term>
<listitem>
<para>
<simpara>
Commonly a regular path in your filesystem.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
<simpara>
It is <literal>r</literal> for read access, <literal>w</literal> for
read/write access to an already existing database, <literal>c</literal>
for read/write access and database creation if it doesn't currently exist,
and <literal>n</literal> for create, truncate and read/write access.
The database is created in BTree mode, other modes (like Hash or Queue)
are not supported.
</para>
<para>
</simpara>
<simpara>
Additionally you can set the database lock method with the next char.
Use <literal>l</literal> to lock the database with a <filename>.lck</filename>
file or <literal>d</literal> to lock the databasefile itself. It is
important that all of your applications do this consistently.
</para>
<para>
</simpara>
<simpara>
If you want to test the access and do not want to wait for the lock
you can add <literal>t</literal> as third character. When you are
absolutely sure that you do not require database locking you can do
@@ -59,7 +59,7 @@
<literal>d</literal>. When none of <literal>d</literal>,
<literal>l</literal> or <literal>-</literal> is used, dba will lock
on the database file as it would with <literal>d</literal>.
</para>
</simpara>
<note>
<para>
There can only be one writer for one database file. When you use dba on
@@ -154,52 +154,52 @@
<varlistentry>
<term><parameter>handler</parameter></term>
<listitem>
<para>
<simpara>
The name of the <link linkend="dba.requirements">handler</link> which
shall be used for accessing <parameter>path</parameter>. It is passed
all optional parameters given to <function>dba_open</function> and
can act on behalf of them. If <parameter>handler</parameter> is &null;,
then the default handler is invoked.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>permission</parameter></term>
<listitem>
<para>
<simpara>
Optional &integer; parameter which is passed to the driver. It has the same meaning as
the <parameter>permissions</parameter> parameter of <function>chmod</function>,
and defaults to <literal>0644</literal>.
</para>
<para>
</simpara>
<simpara>
The <literal>db1</literal>, <literal>db2</literal>, <literal>db3</literal>,
<literal>db4</literal>, <literal>dbm</literal>, <literal>gdbm</literal>,
<literal>ndbm</literal>, and <literal>lmdb</literal> drivers support the
<parameter>permission</parameter> parameter.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>map_size</parameter></term>
<listitem>
<para>
<simpara>
Optional &integer; parameter which is passed to the driver. Its value should be a multiple of the
page size of the OS, or zero, to use the default map size.
</para>
<para>
</simpara>
<simpara>
Only the <literal>lmdb</literal> driver accepts the <parameter>map_size</parameter> parameter.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
<simpara>
Flags to pass to the database drivers. If &null; the default flags will be provided.
Currently, only the LMDB driver supports the following flags
<constant>DBA_LMDB_USE_SUB_DIR</constant> and
<constant>DBA_LMDB_NO_SUB_DIR</constant>.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -207,17 +207,17 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Returns a <classname>Dba\Connection</classname> instance on success&return.falseforfailure;.
</para>
</simpara>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
<simpara>
&false; is returned and an <constant>E_WARNING</constant> level error is issued when
<parameter>handler</parameter> is &null;, but there is no default handler.
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

12
reference/dba/functions/dba-optimize.xml
View File

@@ -11,9 +11,9 @@
<type>bool</type><methodname>dba_optimize</methodname>
<methodparam><type>Dba\Connection</type><parameter>dba</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_optimize</function> optimizes the underlying database.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -21,18 +21,18 @@
<varlistentry>
<term><parameter>dba</parameter></term>
<listitem>
<para>
<simpara>
&dba.parameter.dba;
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.success;
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

44
reference/dba/functions/dba-popen.xml
View File

@@ -16,11 +16,11 @@
<methodparam choice="opt"><type>int</type><parameter>map_size</parameter><initializer>0</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>flags</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_popen</function> establishes a persistent database instance
for <parameter>path</parameter> with <parameter>mode</parameter> using
<parameter>handler</parameter>.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -29,69 +29,69 @@
<varlistentry>
<term><parameter>path</parameter></term>
<listitem>
<para>
<simpara>
Commonly a regular path in your filesystem.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
<simpara>
It is <literal>r</literal> for read access, <literal>w</literal> for
read/write access to an already existing database, <literal>c</literal>
for read/write access and database creation if it doesn't currently exist,
and <literal>n</literal> for create, truncate and read/write access.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>handler</parameter></term>
<listitem>
<para>
<simpara>
The name of the <link linkend="dba.requirements">handler</link> which
shall be used for accessing <parameter>path</parameter>. It is passed
all optional parameters given to <function>dba_popen</function> and
can act on behalf of them. If <parameter>handler</parameter> is &null;,
then the default handler is invoked.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>permission</parameter></term>
<listitem>
<para>
<simpara>
Optional &integer; parameter which is passed to the driver. It has the same meaning as
the <parameter>permissions</parameter> parameter of <function>chmod</function>,
and defaults to <literal>0644</literal>.
</para>
<para>
</simpara>
<simpara>
The <literal>db1</literal>, <literal>db2</literal>, <literal>db3</literal>,
<literal>db4</literal>, <literal>dbm</literal>, <literal>gdbm</literal>,
<literal>ndbm</literal>, and <literal>lmdb</literal> drivers support the
<parameter>permission</parameter> parameter.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>map_size</parameter></term>
<listitem>
<para>
<simpara>
Optional &integer; parameter which is passed to the driver. Its value should be a multiple of the
page size of the OS, or zero, to use the default mapsize.
</para>
<para>
</simpara>
<simpara>
The <literal>lmdb</literal> driver accepts the <parameter>map_size</parameter> parameter.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
<simpara>
Allows to pass flags to the DB drivers. Currently, only LMDB with
<constant>DBA_LMDB_USE_SUB_DIR</constant> and <constant>DBA_LMDB_NO_SUB_DIR</constant> are supported.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -99,17 +99,17 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Returns a <classname>Dba\Connection</classname> instance on success&return.falseforfailure;.
</para>
</simpara>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
<simpara>
&false; is returned and an <constant>E_WARNING</constant> level error is issued when
<parameter>handler</parameter> is &null;, but there is no default handler.
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

20
reference/dba/functions/dba-replace.xml
View File

@@ -13,11 +13,11 @@
<methodparam><type>string</type><parameter>value</parameter></methodparam>
<methodparam><type>Dba\Connection</type><parameter>dba</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_replace</function> replaces or inserts the entry described
with <parameter>key</parameter> and <parameter>value</parameter> into the
database specified by <parameter>dba</parameter>.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -25,34 +25,34 @@
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
<simpara>
The key of the entry to be replaced.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
<simpara>
The value to be replaced.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dba</parameter></term>
<listitem>
<para>
<simpara>
&dba.parameter.dba;
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.success;
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

12
reference/dba/functions/dba-sync.xml
View File

@@ -11,10 +11,10 @@
<type>bool</type><methodname>dba_sync</methodname>
<methodparam><type>Dba\Connection</type><parameter>dba</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>dba_sync</function> synchronizes the database. This will probably
trigger a physical write to the disk, if supported.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -22,18 +22,18 @@
<varlistentry>
<term><parameter>dba</parameter></term>
<listitem>
<para>
<simpara>
&dba.parameter.dba;
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.success;
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

12
reference/dba/setup.xml
View File

@@ -148,13 +148,13 @@
</tgroup>
</table>
</para>
<para>
<simpara>
When invoking the <function>dba_open</function> or
<function>dba_popen</function> functions, one of the
handler names must be supplied as an argument. The actually
available list of handlers is displayed by invoking
<function>phpinfo</function> or <function>dba_handlers</function>.
</para>
</simpara>
</section>
<!-- }}} -->
@@ -199,9 +199,9 @@
<type>string</type>
</term>
<listitem>
<para>
<simpara>
The name of the default handler
</para>
</simpara>
</listitem>
</varlistentry>
@@ -212,10 +212,10 @@
<!-- {{{ Resources -->
<section xml:id="dba.resources">
&reftitle.resources;
<para>
<simpara>
Prior to PHP 8.4.0, most DBA functions operate on or return resources (e.g. <function>dba_open</function>
returns a positive DBA link identifier required by most DBA functions).
</para>
</simpara>
</section>
<!-- }}} -->