Class.DB.php

Class.DB.php is a simple csv file database implementation to allow PHP based applications to have database facilities where none are otherwise available.

All file operations are transient, with the file being held open for the barest minimim of time. The data is held in arrays and written back to the file as appropriate.
Functions intended as the public interfaces for the class return true/false on successful operation. false returns also signify that a text error has beed added to the errors class property.

Class Synopsys

    var $dataFile = "data.dat";		// default filename
    var $dir = "data";			// default directory
    var $assoc = false ;		// default numeric indexes
    var $cryptKey = false;		// default encryption off
    var $db ;			// main database array
    var $newrows ;			// new lines array
    var $error = false;		// error string (no error=false)
    var $lastUpd = "";			// timestamp
    var $written = 0;			// no of rows written

DB()

class constructor

obj DB(string $filename, string $dirname, boolean $assoc_mode, string $cryptKey)

this takes optional parameters to set filename, directory, associative array mode and encryption key The parameters may also be set directly as class properties

readDB()

Load database array from file

boolean result readDB()

Opens specified file, returning true if successful, else false, an appropriate error text is loaded into the error property array db is loaded with data from the csv file. if associated mode is asserted, the first row of the csv file is used as array keys else numeric keys are used. Setting a text string in cryptKey causes the csv file to be read via the decrypter.

appendDB()

appends data to File

boolean appendB()

Appends rows previously loaded into the newrows array to the csv file using encryption if cryptKey is set. This function is useful for log writing and adding transaction entries to lists.

writeDB()

writes array to datafile

boolean writeDB(boolean $append, boolean $force)

This function writes the contents of array db to a csv file. using encryption if cryptKey is set.
optional behavior modifier: append causes the array to be appended to the existing csv file, else file is overwritten.
Optional behavior modifier: force, overrides a change detection mechanism. readDB() records the file's timestamp. If force is not asserted and the file's timestamp is found to have been changed between reading and writing, an attempt to overwrite the csv file by this method will fail with an error. force should be set to enable a new file to be created.

append()

Appends main buffer to datafile

int append()

transfers lines from newlines buffer to main db array. function returns the number of lines transferred, or boolean false on error

update()

Update array with new data

array update(int $rownumber, array $values)

the value for $rownumber is generally obtained via a call to find(). $values is an array in appropriate format for the current mode of the db array, either having numeric keys for assoc = false or associative key values if assoc is true.
all keys must exist in the db array or an error (false) is returned.

delete()

deletes rows from array

array delete(int $row,int $count)

deletes row indicated in $row plus additional rows as identified in $count ex. if row = 5 and count = 3, rows 5,6,7 will be deleted. count defaults to 1.
BEWARE - multiple calls to delete() in ASCENDING ORDER
the main db array renumbers itself automatically, thus if row 5 is deleted, the old row 6 becomes 5, 7 becomes 6 etc. calling delete(5), then delete(6) then delete(7) will actually delete rows 5,7,9 from the db array as seen before the row 5 deletion. Deleting in DECENDING numerical order does NOT suffer this affect and is the recommended method.

find()

finds row numbers matching key/value criteria

array find( array $values)

Returns an array of row numbers where the key/value pair in $value matches array db contents.
results are returned in ascending order and should be rsort()ed before use with delete()

The encryption feature was borrowd many moons ago from someone who had themselves borrowed the idea from someone else. To switch encryption on , provide a string vale for cryptKey in place of a boolean false. This may be done 'on the fly' enabling encrypted files to be written in un-encrypted form and vice-versa.

extended class constructor DBe()

unpackDB()

string unpackDB()

Returns entire database as a comma delimited bytestream.

August 2003, Hertford UK
Ron Barnett <ron dot barnett at BCS dot Org dot uk >