Book/dba-Phpdoc专题

Database (dbm-style) Abstraction Layer

简介
安装／配置
预定义常量
范例
- Basic usage
DBA 函数
- dba_close — Close a DBA database
- dba_delete — Delete DBA entry specified by key
- dba_exists — Check whether key exists
- dba_fetch — Fetch data specified by key
- dba_firstkey — Fetch first key
- dba_handlers — List all the handlers available
- dba_insert — Insert entry
- dba_key_split — Splits a key in string representation into array representation
- dba_list — List all open database files
- dba_nextkey — Fetch next key
- dba_open — Open database
- dba_optimize — Optimize database
- dba_popen — Open database persistently
- dba_replace — Replace or insert entry
- dba_sync — Synchronize database

These functions build the foundation for accessing Berkeley DB style databases.

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 » Oracle Berkeley DB.

安装／配置

需求

The behaviour of various aspects depends on the implementation of the underlying database. Functions such as dba_optimize and dba_sync will do what they promise for one database and will do nothing for others. You have to download and install supported dba-Handlers.

Handler	Notes
dbm	Dbm is the oldest (original) type of Berkeley DB style databases. You should avoid it, if possible. We do not support the compatibility functions built into DB2 and gdbm, because they are only compatible on the source code level, but cannot handle the original dbm format.
ndbm	Ndbm is a newer type and more flexible than dbm. It still has most of the arbitrary limits of dbm (therefore it is deprecated).
gdbm	Gdbm is the » GNU database manager.
db2	DB2 is for » Oracle Berkeley DB 2. It is described as "a programmatic toolkit that provides high-performance built-in database support for both standalone and client/server applications."
db3	DB3 is for » Oracle Berkeley DB 3.
db4	DB4 is for » Oracle Berkeley DB 4 or 5. This option can be used with BDB 5 as of PHP 5.3.3.
cdb	Cdb is "a fast, reliable, lightweight package for creating and reading constant databases." It is from the author of qmail and can be found at » http://cr.yp.to/cdb.html. Since it is constant, we support only reading operations. We support writing (not updating) through the internal cdb library.
cdb_make	We support creation (not updating) of cdb files when the bundled cdb library is used.
flatfile	This is available for compatibility with the deprecated dbm extension only and should be avoided. However you may use this where files were created in this format. That happens when configure could not find any external library.
inifile	This is available to be able to modify php.ini files from within PHP scripts. When working with ini files you can pass arrays of the form array(0=>group,1=>value_name) or strings of the form "[group]value_name" where group is optional. As the functions dba_firstkey and dba_nextkey return string representations of the key there is the function dba_key_split which allows to convert the string keys into array keys without loosing `false`.
qdbm	The qdbm library can be downloaded from » http://fallabs.com/qdbm/index.html.
tcadb	This is available since PHP 5.4.0. The Tokyo Cabinet library can be downloaded from » http://fallabs.com/tokyocabinet/.
lmdb	This is available since PHP 7.2.0. The Lightning Memory-Mapped Database library can be downloaded from » https://symas.com/lmdb/.

When invoking the dba_open or dba_popen functions, one of the handler names must be supplied as an argument. The actually available list of handlers is displayed by invoking phpinfo or dba_handlers.

安装

By using the --enable-dba=shared 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 --with-XXXX or --enable-XXXX configure switch to your PHP configure line.

Warning

After configuring and compiling PHP you must execute the following test from commandline: php run-tests.php ext/dba. This shows whether your combination of handlers works. Most problematic are dbm and ndbm which conflict with many installations. The reason for this is that on several systems these libraries are part of more than one other library. The configuration test only prevents you from configuring malfunctioning single handlers but not combinations.

**Supported DBA handlers**
Handler	Configure Switch
dbm	To enable support for dbm add --with-dbm[=DIR]. Note: 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.
ndbm	To enable support for ndbm add --with-ndbm[=DIR]. Note: 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.
gdbm	To enable support for gdbm add --with-gdbm[=DIR].
db2	To enable support for Oracle Berkeley DB 2 add --with-db2[=DIR]. Note: db2 conflicts with db3 and db4.
db3	To enable support for Oracle Berkeley DB 3 add --with-db3[=DIR]. Note: db3 conflicts with db2 and db4.
db4	To enable support for Oracle Berkeley DB 4 or 5 add --with-db4[=DIR]. Note: db4 conflicts with db2 and db3. Note: The db libraries with versions 4.1 through 4.1.24 cannot be used in any PHP version. Support for BDB 5 was added in PHP 5.3.3.
cdb	To enable support for cdb add --with-cdb[=DIR]. Note: 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.
flatfile	To enable support for flatfile add --enable-flatfile. Before PHP 5.2.1 the --with-flatfile had to be used instead. Note: This was added to add compatibility with deprecated dbm 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.
inifile	To enable support for inifile add --enable-inifile. Before PHP 5.2.1 the --with-inifile had to be used instead. Note: This was added to allow to read and set microsoft style `.ini` files (like the `php.ini` file).
qdbm	To enable support for qdbm add --with-qdbm[=DIR]. Note: qdbm conflicts with dbm and gdbm. Note: The qdbm library can be downloaded from » http://fallabs.com/qdbm/index.html.
tcadb	To enable support for Tokyo Cabinet add --with-tcadb[=DIR]. Note: This was added in PHP 5.4.0. The Tokyo Cabinet library can be downloaded from » http://fallabs.com/tokyocabinet/.
lmdb	To enable support for the Lightning Memory-Mapped Database add --with-lmdb[=DIR]. Note: This was added in PHP 7.2.0. The Lightning Memory-Mapped Database library can be downloaded from » https://symas.com/lmdb/.

运行时配置

这些函数的行为受 php.ini 中的设置影响。

名字	默认	可修改范围	更新日志
dba.default_handler	DBA_DEFAULT	PHP_INI_ALL

这是配置指令的简短说明。

dba.default_handler string
The name of the default handler

资源类型

The functions dba_open and dba_popen return a handle to the specified database file to access which is used by all other dba-function calls.

预定义常量

此扩展没有定义常量。

范例

Basic usage

Basic usage

示例 #1 DBA example

<?php

$id = dba_open("/tmp/test.db", "n", "db2");

if (!$id) {
    echo "dba_open failed\n";
    exit;
}

dba_replace("key", "This is an example!", $id);

if (dba_exists("key", $id)) {
    echo dba_fetch("key", $id);
    dba_delete("key", $id);
}

dba_close($id);
?>

DBA is binary safe and does not have any arbitrary limits. However, it inherits all limits set by the underlying database implementation.

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 dba_open or dba_popen.

You can access all entries of a database in a linear way by using the dba_firstkey and dba_nextkey functions. You may not change the database while traversing it.

示例 #2 Traversing a database

<?php

// ...open database...

$key = dba_firstkey($id);

while ($key !== false) {
    if (true) {          // remember the key to perform some action later
        $handle_later[] = $key;
    }
    $key = dba_nextkey($id);
}

foreach ($handle_later as $val) {
    dba_delete($val, $id);
}

?>

dba_close

Close a DBA database

说明

void dba_close ( resource $dba )

dba_close closes the established database and frees all resources of the specified database handle.

参数

dba
The database handler, returned by dba_open or dba_popen.

返回值

没有返回值。

参见

dba_open
dba_popen

dba_delete

Delete DBA entry specified by key

说明

bool dba_delete ( stringarray $key , resource $dba )

dba_delete deletes the specified entry from the database.

参数

key
The key of the entry which is deleted.

dba
The database handler, returned by dba_open or dba_popen.

返回值

成功时返回 true，或者在失败时返回 false。

参见

dba_exists
dba_fetch
dba_insert
dba_replace

dba_exists

Check whether key exists

说明

bool dba_exists ( stringarray $key , resource $dba )

dba_exists checks whether the specified key exists in the database.

参数

key
The key the check is performed for.

dba
The database handler, returned by dba_open or dba_popen.

返回值

Returns true if the key exists, false otherwise.

参见

dba_delete
dba_fetch
dba_insert
dba_replace

dba_fetch

Fetch data specified by key

说明

string dba_fetch ( string $key , resource $handle )

string dba_fetch ( string $key , int $skip , resource $handle )

dba_fetch fetches the data specified by key from the database specified with handle.

参数

key
The key the data is specified by.

Note:

When working with inifiles this function accepts arrays as keys where index 0 is the group and index 1 is the value name. See: dba_key_split.

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

handle
The database handler, returned by dba_open or dba_popen.

返回值

Returns the associated string if the key/data pair is found, false otherwise.

参见

dba_exists
dba_delete
dba_insert
dba_replace
dba_key_split

dba_firstkey

Fetch first key

说明

stringfalse dba_firstkey ( resource $dba )

dba_firstkey returns the first key of the database and resets the internal key pointer. This permits a linear search through the whole database.

参数

dba
The database handler, returned by dba_open or dba_popen.

返回值

Returns the key on success 或者在失败时返回 false.

参见

dba_nextkey
dba_key_split
Example 2 in the DBA examples

dba_handlers

List all the handlers available

说明

array dba_handlers ([ bool $full_info = false ] )

dba_handlers list all the handlers supported by this extension.

参数

full_info
Turns on/off full information display in the result.

返回值

Returns an array of database handlers. If full_info 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.

Note:

When the internal cdb library is used you will see cdb and cdb_make.

范例

示例 #1 dba_handlers Example

<?php

echo "Available DBA handlers:\n";
foreach (dba_handlers(true) as $handler_name => $handler_version) {
  // clean the versions
  $handler_version = str_replace('$', '', $handler_version);
  echo " - $handler_name: $handler_version\n";
}

?>

以上例程的输出类似于：

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

dba_insert

Insert entry

说明

bool dba_insert ( stringarray $key , string $value , resource $dba )

dba_insert inserts the entry described with key and value into the database.

参数

key
The key of the entry to be inserted. If this key already exist in the database, this function will fail. Use dba_replace if you need to replace an existent key.

value
The value to be inserted.

dba
The database handler, returned by dba_open or dba_popen.

返回值

成功时返回 true，或者在失败时返回 false。

参见

dba_exists
dba_delete
dba_fetch
dba_replace

dba_key_split

Splits a key in string representation into array representation

说明

arrayfalse dba_key_split ( stringfalsenull $key )

dba_key_split splits a key (string representation) into an array representation.

参数

key
The key in string representation.

返回值

Returns an array of the form array(0 => group, 1 => value_name). This function will return false if key is null or false.

参见

dba_firstkey
dba_nextkey
dba_fetch

dba_list

List all open database files

说明

array dba_list ( void )

dba_list list all open database files.

返回值

An associative array, in the form resourceid => filename.

dba_nextkey

Fetch next key

说明

stringfalse dba_nextkey ( resource $dba )

dba_nextkey returns the next key of the database and advances the internal key pointer.

参数

dba
The database handler, returned by dba_open or dba_popen.

返回值

Returns the key on success 或者在失败时返回 false.

参见

dba_firstkey
dba_key_split
Example 2 in the DBA examples

dba_open

Open database

说明

resourcefalse dba_open ( string $path , string $mode [, string $handler ], string $args )

dba_open establishes a database instance for path with mode using handler.

参数

path
Commonly a regular path in your filesystem.

mode
It is r for read access, w for read/write access to an already existing database, c for read/write access and database creation if it doesn't currently exist, and n for create, truncate and read/write access. The database is created in BTree mode, other modes (like Hash or Queue) are not supported.

Additionally you can set the database lock method with the next char. Use l to lock the database with a .lck file or d to lock the databasefile itself. It is important that all of your applications do this consistently.

If you want to test the access and do not want to wait for the lock you can add t as third character. When you are absolutely sure that you do not require database locking you can do so by using - instead of l or d. When none of d, l or - is used, dba will lock on the database file as it would with d.

Note:

There can only be one writer for one database file. When you use dba on a web server and more than one request requires write operations they can only be done one after another. Also read during write is not allowed. The dba extension uses locks to prevent this. See the following table:

already open mode = "rl" mode = "rlt" mode = "wl" mode = "wlt" mode = "rd" mode = "rdt" mode = "wd" mode = "wdt"

not open ok ok ok ok ok ok ok ok

mode = "rl" ok ok wait false illegal illegal illegal illegal

mode = "wl" wait false wait false illegal illegal illegal illegal

mode = "rd" illegal illegal illegal illegal ok ok wait false

mode = "wd" illegal illegal illegal illegal wait false wait false

ok: the second call will be successfull.

wait: the second call waits until dba_close is called for the first.

false: the second call returns false.

illegal: you must not mix "l" and "d" modifiers for mode parameter.

already open	`mode` = "rl"	`mode` = "rlt"	`mode` = "wl"	`mode` = "wlt"	`mode` = "rd"	`mode` = "rdt"	`mode` = "wd"	`mode` = "wdt"
not open	ok	ok	ok	ok	ok	ok	ok	ok
`mode` = "rl"	ok	ok	wait	false	illegal	illegal	illegal	illegal
`mode` = "wl"	wait	false	wait	false	illegal	illegal	illegal	illegal
`mode` = "rd"	illegal	illegal	illegal	illegal	ok	ok	wait	false
`mode` = "wd"	illegal	illegal	illegal	illegal	wait	false	wait	false

handler
The name of the handler which shall be used for accessing path. It is passed all optional parameters given to dba_open and can act on behalf of them.

args
Optional string parameters which are passed to the driver.

The cdb, cdb_make, flatfile, inifile, qdbm and tcadb drivers do not support additional parameters.

The db1, db2, db3, db4, dbm, gdbm, and ndbm drivers supports a single additional parameter $filemode, which has the same meaning as the $mode parameter of chmod, and defaults to 0644.

The lmdb driver accepts two additional parameters. The first allows to specify the $filemode (see description above), and the second to specify the $mapsize, where the value should be a multiple of the page size of the OS, or zero, to use the default mapsize. The $mapsize parameter is supported as of PHP 7.3.14 and 7.4.2, respectively.

返回值

Returns a positive handle on success 或者在失败时返回 false.

更新日志

版本	说明
7.3.14, 7.4.2	The lmdb driver now supports an additional $mapsize parameter.

参见

dba_popen
dba_close

dba_optimize

Optimize database

说明

bool dba_optimize ( resource $dba )

dba_optimize optimizes the underlying database.

参数

dba
The database handler, returned by dba_open or dba_popen.

返回值

成功时返回 true，或者在失败时返回 false。

参见

dba_sync

dba_popen

Open database persistently

说明

resourcefalse dba_popen ( string $path , string $mode [, string $handler ], mixed $args )

dba_popen establishes a persistent database instance for path with mode using handler.

参数

path
Commonly a regular path in your filesystem.

handler
The name of the handler which shall be used for accessing path. It is passed all optional parameters given to dba_popen and can act on behalf of them.

args
Optional string parameters which are passed to the driver.

The cdb, cdb_make, flatfile, inifile, qdbm and tcadb drivers do not support additional parameters.

返回值

Returns a positive handle on success 或者在失败时返回 false.

参见

dba_open
dba_close

dba_replace

Replace or insert entry

说明

bool dba_replace ( stringarray $key , string $value , resource $dba )

dba_replace replaces or inserts the entry described with key and value into the database specified by dba.

参数

key
The key of the entry to be replaced.

value
The value to be replaced.

dba
The database handler, returned by dba_open or dba_popen.

返回值

成功时返回 true，或者在失败时返回 false。

参见

dba_exists
dba_delete
dba_fetch
dba_insert

dba_sync

Synchronize database

说明

bool dba_sync ( resource $dba )

dba_sync synchronizes the database. This will probably trigger a physical write to the disk, if supported.

参数

dba
The database handler, returned by dba_open or dba_popen.

返回值

成功时返回 true，或者在失败时返回 false。

参见

dba_optimize

dba_close — Close a DBA database
dba_delete — Delete DBA entry specified by key
dba_exists — Check whether key exists
dba_fetch — Fetch data specified by key
dba_firstkey — Fetch first key
dba_handlers — List all the handlers available
dba_insert — Insert entry
dba_key_split — Splits a key in string representation into array representation
dba_list — List all open database files
dba_nextkey — Fetch next key
dba_open — Open database
dba_optimize — Optimize database
dba_popen — Open database persistently
dba_replace — Replace or insert entry
dba_sync — Synchronize database