Quick navigation:

ptb_connect

Connects to the specified database, which simply means that data from the database are read into memory as an array. Preliminary condition for displaying records and using some other functions: ptb_select, ptb_map, ptb_count, ptb_max, ptb_min.

Syntax

$var = ptb_connect($filename[, $location = PTB_DEFAULT_DB_LOCATION[, $recursive = true[, $keyField = '']]]);

Syntax description

$filename

name of file containing the database

$location

optional: location of $filename; can be:

G: globally defined (in ptb_ini.php) directory
L: local directory (ie. the same where script calling ptb_connect is placed)
<path>: other, defined directory, eg. /samples/db (no trailing slash)
F: filename (ie. absolute or relative path without DOCUMENT_ROOT dependency)

$recursive

optional: specifies whether linked fields should be read; can be set to true (default) or false

$keyField

optional: name of field to be used as main key; if it is not given, first record's key is 0, next 1 etc.; if it is used, each record's key is equal to $keyField's value (usually you'd want to use id field here); $keyField should be primary key: if there is more than one record with the same value of $keyField, only the last one will be inserted into table (read more)

Return

This function returns array or null, if data file doesn't exist or contains no data.

Sample(s)

$books = ptb_connect('books.csv'); $books = ptb_connect('books.csv', 'L'); $books = ptb_connect('books.csv', '/other/data'); $books = ptb_connect('../books.csv', 'F');

Tips

I find it to be a useful programming custom to name variable that holds the whole database after the $filename, even if it may be subsequently modified by reading linked files or with ptb_merge, eg.

$something = ptb_connect('something.csv');

Keyfield concept

If you don't use $keyField (4th argument to ptb_connect), records' keys start at 0 and are consecutive: 0, 1, 2, 3 etc. The biggest is equal to total number of records in the array minus 1, and you can loop through the array with standard for:

for ($i = 0, $c = ptb_count($myDatabase); $i < $c; $i++) { // instructions, eg. echo $myDatabase[$i]['title']; }

Pure and simple, with one drawback, though: you can't easily get other values of the record, for which one field's value (usually it would be id) you know–you need to use ptb_map for this. Probably the most common example of this situation is when you have value of $_GET['id'] and want to display other fields of the record, for which id is equal to it:

$x = ptb_map($myDatabase, "'id' == '$_GET['id']'");

Now $x holds the said record (ptb_map without third argument was introduced in version 1.2), so you can use:

echo $x[0]['title'];

With setting $keyField to id you don't need to use ptb_map at all, since you can directly acces the record in question, eg.:

echo $myDatabase[$_GET['id']]['title'];

Of course you can set $keyField to any field, but it makes sense if it is set to primary key of your databse (in other words to such field, for which values are unique throughout the whole database, so you can doubtlessly identify each record by the said value). If there are eg. two records with identical ids, only the latter will be available.

Please notice that if you want to loop through the database with standard for, you need to start from the smallest id, not from 0:

for ($i = <smallest id>, $c = ptb_count($myDatabase); $i < $c; $i++) { // instructions, eg. echo $myDatabase[$i]['title']; }

If there are some "gaps", ie. ids aren't consecutive, you'll get warning message. In such a case you may want to use foreach:

foreach ($myDatabase as $key => $value) { // instructions, eg. echo $myDatabase[$key]['title']; }

If you use $keyField in ptb_connect, do not forget to use it also in ptb_merge.