PHP can support a few different kinds of DBM backends: GDBM,
NDBM, DB2, DB3, DBM, and CDB. The DBA abstraction layer lets you use the same
functions on any DBM backend. All these backends store key/value pairs. You can
iterate through all the keys in a database, retrieve the value associated with a
particular key, and find if a particular key exists. Both the keys and the
values are strings.

The following program maintains a list of usernames and
passwords in a DBM database. The username is the first command-line argument,
and the password is the second argument. If the given username already exists in
the database, the password is changed to the given password; otherwise the user
and password combination are added to the database:

The dba_open() function returns a handle to a DBM
file (or false on error). It takes three arguments. The first is the
filename of the DBM file. The second argument is the mode for opening the file.
A mode of 'r' opens an existing database for read-only access, and 'w'
opens an existing database for read-write access. The 'c' mode opens a
database for read-write access and creates the database if it doesn't already
exist. Last, 'n' does the same thing as 'c', but if the
database already exists, 'n' empties it. The third argument to dba_open(
) is which DBM handler to use; this example uses 'gdbm'. To find
what DBM handlers are compiled into your PHP installation, look at the "DBA"
section of the output from phpinfo( ). The "Supported
handlers" line gives you your choices.

To find if a key has been set in a DBM database, use dba_exists().
It takes two arguments: a string key and a DBM file handle. It looks for the key
in the DBM file and returns true if it finds the key (or false
if it doesn't). The dba_replace( ) function takes three arguments: a
string key, a string value, and a DBM file handle. It puts the key/value pair
into the DBM file. If an entry already exists with the given key, it overwrites
that entry with the new value.

To close a database, call dba_close(). A DBM file
opened with dba_open( ) is automatically closed at the end of a
request, but you need to call dba_close( ) explicitly to close
persistent connections created with dba_popen( ).

You can use dba_firstkey()and dba_nextkey( )
to iterate through all the keys in a DBM file and dba_fetch( ) to
retrieve the values associated with each key. This program calculates the total
length of all passwords in a DBM file:

The dba_firstkey( ) function initializes $k
to the first key in the DBM file. Each time through the while loop, dba_fetch(
) retrieves the value associated with key $k and $total_length
is incremented by the length of the value (calculated with strlen( )).
With dba_nextkey( ), $k is set to the next key in the file.

You can use serialize() to store complex data in a
DBM file, just like in a text file. However, the data in the DBM file can be
indexed by a key:

While this example can store multiple users' data in the same
file, you can't search, for example, a user's last access time, without looping
through each key in the file. Structured data like this belongs in a SQL
database.

Each DBM handler has different behavior in some areas. For
example, GDBM provides internal locking. If one process has opened a GDBM file
in read-write mode, other calls to dba_open( ) to open the same file in
read-write mode will fail. The DB3 handler, however, provides no such internal
locking; you need to do that with additional code. Two DBA functions are also
database-specific: dba_optimize( )and dba_sync( ). The dba_optimize(
) function calls a handler-specific DBM file-optimization function.
Currently, this is implemented only for GDBM, for which its gdbm_reorganize(
) function is called. The dba_sync( ) function calls a
handler-specific DBM file synchronizing function. For DB2 and DB3, their sync(
) function is called. For GDBM, its gdbm_sync( ) function is
called. Nothing happens for other DBM handlers.

Using a DBM database is a step up from a text file but it
lacks most features of a SQL database. Your data structure is limited to
key/value pairs, and locking robustness varies greatly depending on the DBM
handler. Still, DBM handlers can be a good choice for heavily accessed read-only
data; for example, the Internet Movie Database uses DBM databases.