Database (dbm-style) Abstraction Layer

目录

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.

HandlerNotes
dbmDbm 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.
ndbmNdbm is a newer type and more flexible than dbm. It still has most of the arbitrary limits of dbm (therefore it is deprecated).
gdbmGdbm is the » GNU database manager.
db2DB2 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."
db3DB3 is for » Oracle Berkeley DB 3.
db4DB4 is for » Oracle Berkeley DB 4 or 5. This option can be used with BDB 5 as of PHP 5.3.3.
cdbCdb 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_makeWe support creation (not updating) of cdb files when the bundled cdb library is used.
flatfileThis 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.
inifileThis 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.
qdbmThe qdbm library can be downloaded from » http://fallabs.com/qdbm/index.html.
tcadbThis is available since PHP 5.4.0. The Tokyo Cabinet library can be downloaded from » http://fallabs.com/tokyocabinet/.
lmdbThis 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_handlerDBA_DEFAULTPHP_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

示例 #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 $handle )

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

参数

handle
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 ( string $key , resource $handle )

dba_delete deletes the specified entry from the database.

参数

key
The key of the entry which is deleted.

handle
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 ( string $key , resource $handle )

dba_exists checks whether the specified key exists in the database.

参数

key
The key the check is performed for.

handle
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: class="function">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

说明

string dba_firstkey ( resource $handle )

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

参数

handle
The database handler, returned by dba_open or dba_popen.

返回值

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

参见

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 ( string $key , string $value , resource $handle )

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.

handle
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

说明

mixed dba_key_split ( mixed $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

说明

string dba_nextkey ( resource $handle )

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

参数

handle
The database handler, returned by dba_open or dba_popen.

返回值

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

参见

dba_open

Open database

说明

resource dba_open ( string $path , string $mode [, string $handler [, string $... ]] )

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 openmode = "rl"mode = "rlt"mode = "wl"mode = "wlt"mode = "rd"mode = "rdt"mode = "wd"mode = "wdt"
not openokokokokokokokok
mode = "rl"okokwaitfalseillegalillegalillegalillegal
mode = "wl"waitfalsewaitfalseillegalillegalillegalillegal
mode = "rd"illegalillegalillegalillegalokokwaitfalse
mode = "wd"illegalillegalillegalillegalwaitfalsewaitfalse
  • ok: the second call will be successfull.
  • wait: the second call waits until class="function">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.

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.

...
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.2The lmdb driver now supports an additional $mapsize parameter.

参见

  • dba_popen
  • dba_close

dba_optimize

Optimize database

说明

bool dba_optimize ( resource $handle )

dba_optimize optimizes the underlying database.

参数

handle
The database handler, returned by dba_open or dba_popen.

返回值

成功时返回 TRUE, 或者在失败时返回 FALSE

参见

  • dba_sync

dba_popen

Open database persistently

说明

resource dba_popen ( string $path , string $mode [, string $handler [, mixed $... ]] )

dba_popen establishes a persistent 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.

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.

返回值

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

参见

  • dba_open
  • dba_close

dba_replace

Replace or insert entry

说明

bool dba_replace ( string $key , string $value , resource $handle )

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

参数

key
The key of the entry to be replaced.

value
The value to be replaced.

handle
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 $handle )

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

参数

handle
The database handler, returned by dba_open or dba_popen.

返回值

成功时返回 TRUE, 或者在失败时返回 FALSE

参见

  • dba_optimize

目录