[doc-en] master: dba: fix outdated types and behaviour on several pages (#6061)

From: 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 =&gt; filename</literal>. + An associative array, in the form <literal>id =&gt; 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>

« previous php.doc.cvs (#23939) next »