[doc-en] master: dba: fix outdated types and behaviour on several pages (#6061)
| From: | Tiago Cruz via GitHub | Date: | Wed, 11 Nov 2026 20:48:06 +0000 |
| Subject: | [doc-en] master: dba: fix outdated types and behaviour on several pages (#6061) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23939@lists.php.net to get a copy of this message | ||
Author: Tiago Cruz (TiagoCruz1224)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-11-11T21:48:02+01:00
Commit: https://github.com/php/doc-en/commit/d67d84489b16d3fdf4cbe3815ed6f41340e333e0
Raw diff: https://github.com/php/doc-en/commit/d67d84489b16d3fdf4cbe3815ed6f41340e333e0.diff
dba: fix outdated types and behaviour on several pages (#6061)
* dba: fix outdated types and behaviour on several pages
- dba_popen(): handler became nullable in 8.2.0, not 8.1.0, as on
dba_open(). The php-8.1.0 stub has no type for it; php-8.2.0 has
?string.
- dba_fetch(): the deprecated signature takes a Dba\Connection and
returns string|false. Document that inifile also supports skip, and
what happens to unsupported or negative values.
- dba_list(): the keys are the object IDs of the Dba\Connection
instances (GH-16990), not resource IDs. Add the 8.4.0 changelog row.
- dba_insert(): inifile and cdb_make add another entry for an existing
key and return true. dba_replace(): cdb_make cannot replace, so it
always returns false.
- dba_insert(), dba_replace(), dba_delete() and dba_optimize(): add an
Errors section for a database opened read-only (DBA_WRITE_CHECK).
- dba_handlers(): refresh the example output, which still showed CVS
revisions.
- setup.xml: passing false to dba_key_split() is deprecated as of
8.4.0, so drop "without losing false" from the inifile row.
Checked against ext/dba in php-src (php-8.1.0, php-8.2.0, php-8.4.0
and php-8.5.0), and by running each case on PHP 8.1, 8.2, 8.4 and 8.5.
Fixes #6002
* dba: apply the review suggestions on dba_list() and dba_insert()
dba_list(): split the changelog into 8.4.0 (zero-based indexes instead
of resource IDs) and 8.4.2 (object IDs).
dba_insert(): only inifile can read a duplicate key back with skip,
because a cdb_make database is write-only.
Changed paths:
M reference/dba/functions/dba-delete.xml
M reference/dba/functions/dba-fetch.xml
M reference/dba/functions/dba-handlers.xml
M reference/dba/functions/dba-insert.xml
M reference/dba/functions/dba-list.xml
M reference/dba/functions/dba-optimize.xml
M reference/dba/functions/dba-popen.xml
M reference/dba/functions/dba-replace.xml
M reference/dba/setup.xml
Diff:
diff --git a/reference/dba/functions/dba-delete.xml b/reference/dba/functions/dba-delete.xml
index 576e553f23ea..d3c65a733b97 100644
--- a/reference/dba/functions/dba-delete.xml
+++ b/reference/dba/functions/dba-delete.xml
@@ -44,6 +44,14 @@
</simpara>
</refsect1>
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ If <parameter>dba</parameter> was opened read-only (mode
<literal>r</literal>),
+ an <constant>E_WARNING</constant> is raised and &false; is returned.
+ </simpara>
+ </refsect1>
+
<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
diff --git a/reference/dba/functions/dba-fetch.xml b/reference/dba/functions/dba-fetch.xml
index faec6b998fe6..7253d97b7722 100644
--- a/reference/dba/functions/dba-fetch.xml
+++ b/reference/dba/functions/dba-fetch.xml
@@ -17,10 +17,10 @@
Overloaded signature deprecated as of 8.3.0:
</simpara>
<methodsynopsis>
- <type>string</type><methodname>dba_fetch</methodname>
+ <type
class="union"><type>string</type><type>false</type></type><methodname>dba_fetch</methodname>
<methodparam><type
class="union"><type>string</type><type>array</type></type><parameter>key</parameter></methodparam>
<methodparam><type>int</type><parameter>skip</parameter></methodparam>
-
<methodparam><type>resource</type><parameter>dba</parameter></methodparam>
+
<methodparam><type>Dba\Connection</type><parameter>dba</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>dba_fetch</function> fetches the data specified by
@@ -58,9 +58,16 @@
<term><parameter>skip</parameter></term>
<listitem>
<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.
+ The number of entries with the same key to skip before the one that
+ is returned. Only the <literal>cdb</literal> and
<literal>inifile</literal>
+ handlers support it. With any other handler, a non-zero value is ignored
+ and an <constant>E_NOTICE</constant> is raised.
+ </simpara>
+ <simpara>
+ With <literal>cdb</literal>, a negative value is treated as
<literal>0</literal>.
+ With <literal>inifile</literal>, a value below <literal>-1</literal>
is
+ treated as <literal>0</literal>. In both cases, an
<constant>E_NOTICE</constant>
+ is raised.
</simpara>
</listitem>
</varlistentry>
diff --git a/reference/dba/functions/dba-handlers.xml b/reference/dba/functions/dba-handlers.xml
index 0e4411132770..da7c372f75d2 100644
--- a/reference/dba/functions/dba-handlers.xml
+++ b/reference/dba/functions/dba-handlers.xml
@@ -66,11 +66,10 @@ foreach (dba_handlers(true) as $handler_name => $handler_version) {
<screen>
<![CDATA[
Available DBA handlers:
- - cdb: 0.75, Revision: 1.3.2.3
- - cdb_make: 0.75, Revision: 1.2.2.4
- - db2: Sleepycat Software: Berkeley DB 2.7.7: (08/20/99)
- - inifile: 1.0, Revision: 1.6.2.3
- - flatfile: 1.0, Revision: 1.5.2.4
+ - cdb: 0.75, Id: e694d6a6eb12f2bbad27f8ec7ebf3788257532d9
+ - cdb_make: 0.75, Id: 570e3625b0cea5c29455cecf40fdfd491c0eb3c6
+ - inifile: 1.0, Id: 4dc687ea6681ffc42006a5fa64ac97f828c52ce1
+ - flatfile: 1.0, Id: a68fed7e38c4318d938b19f5644d9962fe0beb49
]]>
</screen>
</example>
diff --git a/reference/dba/functions/dba-insert.xml b/reference/dba/functions/dba-insert.xml
index 445fd2bebe9f..29d69965712b 100644
--- a/reference/dba/functions/dba-insert.xml
+++ b/reference/dba/functions/dba-insert.xml
@@ -26,9 +26,15 @@
<term><parameter>key</parameter></term>
<listitem>
<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.
+ The key of the entry to be inserted. If this key already exists in the
+ database, this function fails. Use <function>dba_replace</function>
+ if you need to replace an existing key.
+ </simpara>
+ <simpara>
+ The <literal>inifile</literal> and <literal>cdb_make</literal>
handlers
+ are the exception: they add another entry with the same key and return
+ &true;. With <literal>inifile</literal>, use the
<parameter>skip</parameter>
+ parameter of <function>dba_fetch</function> to read it.
</simpara>
</listitem>
</varlistentry>
@@ -57,6 +63,14 @@
</simpara>
</refsect1>
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ If <parameter>dba</parameter> was opened read-only (mode
<literal>r</literal>),
+ an <constant>E_WARNING</constant> is raised and &false; is returned.
+ </simpara>
+ </refsect1>
+
<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
diff --git a/reference/dba/functions/dba-list.xml b/reference/dba/functions/dba-list.xml
index f1afa8141d36..7eb91bf1fd9c 100644
--- a/reference/dba/functions/dba-list.xml
+++ b/reference/dba/functions/dba-list.xml
@@ -24,9 +24,42 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
- An associative array, in the form <literal>resourceid => filename</literal>.
+ An associative array, in the form <literal>id => filename</literal>,
+ where <literal>id</literal> is the object ID of the
+ <classname>Dba\Connection</classname> instance, as returned by
+ <function>spl_object_id</function>.
</simpara>
</refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.4.2</entry>
+ <entry>
+ The keys of the returned array are now object IDs of
+ <classname>Dba\Connection</classname> instances.
+ </entry>
+ </row>
+ <row>
+ <entry>8.4.0</entry>
+ <entry>
+ The keys of the returned array are now sequential, zero-based indexes
+ instead of resource IDs.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
diff --git a/reference/dba/functions/dba-optimize.xml b/reference/dba/functions/dba-optimize.xml
index 3ea6fdf34afe..43590bb410c3 100644
--- a/reference/dba/functions/dba-optimize.xml
+++ b/reference/dba/functions/dba-optimize.xml
@@ -35,6 +35,14 @@
</simpara>
</refsect1>
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ If <parameter>dba</parameter> was opened read-only (mode
<literal>r</literal>),
+ an <constant>E_WARNING</constant> is raised and &false; is returned.
+ </simpara>
+ </refsect1>
+
<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
diff --git a/reference/dba/functions/dba-popen.xml b/reference/dba/functions/dba-popen.xml
index 715750396902..b0c14aee82a6 100644
--- a/reference/dba/functions/dba-popen.xml
+++ b/reference/dba/functions/dba-popen.xml
@@ -137,7 +137,7 @@
</entry>
</row>
<row>
- <entry>8.1.0</entry>
+ <entry>8.2.0</entry>
<entry>
<parameter>handler</parameter> is now nullable.
</entry>
diff --git a/reference/dba/functions/dba-replace.xml b/reference/dba/functions/dba-replace.xml
index 509462290ca7..bbec3e390639 100644
--- a/reference/dba/functions/dba-replace.xml
+++ b/reference/dba/functions/dba-replace.xml
@@ -53,6 +53,18 @@
<simpara>
&return.success;
</simpara>
+ <simpara>
+ The <literal>cdb_make</literal> handler cannot replace entries, so with it
+ this function always returns &false;.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ If <parameter>dba</parameter> was opened read-only (mode
<literal>r</literal>),
+ an <constant>E_WARNING</constant> is raised and &false; is returned.
+ </simpara>
</refsect1>
<refsect1 role="changelog">
diff --git a/reference/dba/setup.xml b/reference/dba/setup.xml
index 9dc5593627c3..07e05149fcc2 100644
--- a/reference/dba/setup.xml
+++ b/reference/dba/setup.xml
@@ -116,7 +116,7 @@
<function>dba_firstkey</function> and
<function>dba_nextkey</function>
return string representations of the key there is the function
<function>dba_key_split</function> which allows
- to convert the string keys into array keys without losing &false;.
+ to convert the string keys into array keys.
</entry>
</row>