TextDB Manual
From MyUPBWiki
The Text Database Manual was written by Jerroyd Moore (aka Rebles) on the © Ultimate PHP Board (UPB) Team (http://www.myupb.com) for © PHP Outburst.
Text Database was written by Tim Hoeppner (aka Pilot) on the © Ultimiate PHP Board (UPB) Team (http://www.myupb.com) for © PHP Outburst
This wiki document, created at the start of TextDB Version 4.4.0, which was later renamed 5.0.0, is designed to familiarize yourself with the workings of the Text Database ("tdb") and help you understand each individual function and how to use them together to achieve your objective. This is not recommended for users who are not familiar with PHP or classes/objects of PHP. If you are one of those users, you should visit http://www.php.net to familiarize yourself with the language before continuing onto TextDB. TextDB was written to be a user-friendly alternative to mySQL, for those websites who cannot use mySQL.
If you need technical support, please visit the TextDB Discussion Forum to seek help.
Getting Started
A quick Introduction to TextDB.
What is TextDB?
TextDB, a.k.a. tdb, is a simple yet innovative and alternative database system. If you find SQL too difficult to understand or your server does not come with a SQL server, TextDB is your solution. TextDB stores the database directly on your file server. It's easy to backup, and once you get the hang of it, it's simple.
Requirements
The TextDB recommends having PHP 4.3.2 or better. You must be able to chmod() folders, so the TextDB can edit/create/delete tables and databases. safe_mode should also be turned off.
Installation and Configuration
There is actually no installation to the TextDB. It's just a PHP file that contains the TextDB class. To start using the TextDB, simply upload the tdb.class.php into a folder, and make sure to have a folder in the same directory tree that is readable and writable [chmod() to 0644] so that the tdb.class.php can access it.
Creating a Database and a Table
There are two methods to creating the database. The first method is to access the class "tdb" and create it from there.
<?php
require('tdb.class.php');
$tdb = new tdb('', '');
$tdb->createDatabase('./db/', 'database');
$tdb->tdb('./db/', 'database');
//Insert tdb coding here
?>
You are now ready to start creating tables for your new database. The alternative option to create a database is to create the database first, then access the class.
<?php
require('tdb.class.php');
tdb::createDatabase('./db/', 'database');
$tdb = new tdb('./db/', 'database');
//Insert tdb coding here
?>
To create a table, use the createTable() function. You have three arguments. The first argument is the table's name. The second argument is the field array and its parameters. The third argument is optional, and sets the number of bytes a block in the memo uses. It defaults to 100.
<?php
require('tdb.class.php');
$tdb->tdb('./db/', 'database');
$tdb->createTable('theTable1', array(array('field1', 'string', 10), array('id', 'id')));
?>
The second argument's format is a multi-dimensional array. It goes as follows:
array(array(field1_name, field1_type, field1_length), array(field2_name, field2_type, field2_length), ...)
You are now ready to start accessing your TextDB and its tables.
Language Reference
The TextDB has a certain set of rules or a "language" that it follows for its functions. This section will help you familiarize yourself with the language, so you won't have problems utilizing TextDB.
The Beginning: Classes/Objects
As you script TextDB, you may begin to notice a dash followed by an arrow (" -> ") at the beginning of all your functions. This is because the TextDB is a class, meaning you have to access the class using an object (the variable on the left side of the dash and arrow). To initiate an object, call it using "new".
Example 1. Calling a class
$tdb = new tdb('./folder/', 'database.tdb5');
Single Records
When a user is calling a function, which has an argument for a single record, such as add() or edit(), the format of the argument is very important. It is calling for an array where the fields' names are the keys and the fields' value is the array's value
Examples
The following is an example of using the array directly in the function.
$tdb->add('theTable', array('theField1' => 'data', 'theField2' => 'moredata'));
You can also store the values in an array before executing a function.
$array = array('theField1' => 'data');
$array['theField2'] = 'moredata';
$tdb->add('theTable', $array);
Multiple Records
There is no existence where multiple records are needed for arguments in functions, however the functions listRec(), basicQuery(), and query() all return multi-dimentional arrays of records.
Examples
If you were to list the records of a table and print the results, it would look something like this:
Array
(
[0] => Array
(
[theField1] => data
[theField2] => moredata
[id] => 1
)
[1] => Array
(
[theField1] => different data
[theField2] => more_diff_data
[id] => 2
)
)
This format is extremely resourceful in loops.
<?php
//Using the $array above
for($i=0,$max=count($array);$i<$max;$i++) {
echo '#'.$i.' ';
$k = 0;
while(list($key, $val) = each($array[$i])) {
echo sprintf('Field%d: "%s" => "%s" ',
$k,
$key,
$val);
$k++;
}
echo "\n";
}
?>
This will print the following:
#0 Field0: "theField1" => "data" Field1: "theField2" => "moredata" Field2: "id" => "1" #1 Field0: "theField1" => "different data" Field1: "theField2" => "more_diff_data" Field2: "id" => "2"
Reading the Header
Before tDB 5.1, when reading the header, you had must declare the variable as an array before executing __readHeader(), and type your newly declared variable into the second argument of the function.
Before tDB 5.1 Example
<?php
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta1', 'thetable');
$header = array();
$tdb->readHeader('ta1', $header);
//You may now use the header information
?>
Since tDB 5.1, __readHeader() returns the header information.
After tDB 5.1 Example
<?php
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta1', 'thetable');
$header = $tdb->__readHeader('ta1');
//You may now use the header information
?>
Alternatively, you might want to run getFieldList() if you just want the fields in the table and not the extra header information.
Types of Fields
There are four field_types the TextDB utilizes: string, number, memo, and id. string accepts any and all characters since tDB 4 >= 4.3, but is limited with a length. number accepts numbers, decimal (period), and a negative sign (dash), and is limited with a length. memo accepts all characters like string but does not have the restriction, length. For more information about memo see createTable(). While all records have an id (record id), that is used in edit() and delete() and is returned in add(), you must have a field with the file_type id in order to retrieve the id. id has a strict length, which cannot be changed nor set.
Field Array
For functions such as addField(), createTable(), editField(), the format of the field array is essential.
For the single field array, the format is
array(field_name, field_type, field_length)
For the multiple fields array, the format is
array(array(field1_name, field1_type, field1_length), array(field2_name, field2_type, field2_length), ... )
field_name, field_type, and field_length respectively are the name of the field, the type of the field (string, number, memo, and id), and the maximum length the data can be for the field.
Note memo and id do not have a length, therefore, you don't need to declare it in the field arrays.
Example 1. Example of multiple fields array
<?php
$tdb = new tdb('./db/', 'database');
$tdb->createTable('theTable', array(
array('name', 'string', 35),
array('age', 'number', 3),
array('comments', 'memo'),
array('identification_number', 'id')));
?>
Example 2. Example of single field array
<?php
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$tdb->editField('ta', 'old_field', array('new_field', 'string', '40));
?>
Security
Because you might be storing sensitive information in the TextDB, we recommend you create a file called ".htaccess" in the directory that you're storing your database, with the contents of
Order deny,allow Deny from all
This will prevent attackers from access the directory via browser. This does not prevent access via FTP. This prevents browsers from opening up any files in the folder directly, that's why it is recommended you store your database in a separate folder apart.
Features
- Ability to store information in a formated and database-style file.
- Advanced query algorithm with unique but easy-to-understand query string.
- simplified column or "field" types to avoid confusion.
Function Reference
Here you can find a list of all the TextDB functions, what they do, what they return, and what errors you might expect.
add
(tDB 4, tDB 5)
add -- add a record
Description
int add ( string fp, array input )
Returns int ID on success or false upon failure.
Adds a record with the parameters input in the table specified by the table pointer fp. The format for input is a single record array. The keys should be labelled the fields and the values should be data. Since tDB 5.0.2, if the number of records in the table reaches five million, the function will return FALSE and will generate an error. For tDB < 5.0.2, if the ID number of the table reaches five million, the function will return FALSE and will generate an error. Add() will also return FALSE and generate errors based on __check().
Example 1. add() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$tdb->add('ta', array('theField' => 'insert data here'));
?>
Example 2. add() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$array['theField'] = "insert data here";
$array['theField2'] = "insert data here";
$tdb->add('ta', $array);
?>
addField
(tDB 4, tDB 5)
addField -- adds a field to a table
Description
bool addField ( string fp, array field )
Returns a true or false.
Adds a new field based on the parameters of field to the table specified by the table pointer fp. field follows the single field array format.
It will return FALSE and generate an error if the field name already exists or if the field type is invalid. It will also return FALSE and generate errors based on __check().
Example 1. addField() example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$tdb->addField('ta', array('field2', 'number', 5));
?>
See Also removeField(), editField(), and getFieldList()
basicQuery
(tDB 4, tDB 5)
basicQuery -- queries a table based on one field
Description
bool basicQuery ( string fp, string field, string value [, int start [, int howmany [, array fields ]]] )
Identical to query(), except its queries are limited to one field and it has to equal the value. Returns a multi-dimentional array of records. It will return FALSE if there is any errors as well as generate errors. It will return an empty array if there were no results. It will also return FALSE and generate errors based on __check().
Since tDB 5.1, the optional argument fields was added to retrieve only the values of the fields specified.
Example 1. basicQuery() Example
The following will return one record, where field's value has to be "bob".
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$tdb->basicQuery('ta', 'name', 'bob', 1, 1); //will retrieve all fields
?>
Example 2. SELECT fields Example
The following will return all records, whose field's value has to be "bob", but only the fields age and id.
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$tdb->basicQuery('ta', 'name', 'bob', 1, -1, array('age', 'id')); //will retrieve all fields
?>
See Also query() and the SELECT Field Reference.
__bytesToSeek
(tDB 4, tDB 5)
__bytesToSeek -- find the position of a record
Description
int __bytesToSeek ( string fp, array header, int fileId )
Note This is an internal function, not meant to be used outside of the tdb class.
Returns the position of a record, based on its fileId in the table specified by the table pointer fp. If the position evaluated by __bytesToSeek() is after the end of file, __bytesToSeek() will return FALSE. Since tDB 5, if the position evaluated is before the beginning of file or in the middle of the header, __bytesToSeek() will return FALSE aswell.
You must set the fp using setFp() or else it will generate errors and return FALSE. The header must be the header information defined by using __readHeader().
See also __fileIdById().
__check
(tDB 4, tDB5)
__check -- validates variables before executing functions
Description
bool __check ( int line [, string fp ] )
Note This is an internal function, not meant to be used outside of the tdb class.
Returns TRUE if the internal variables workingDir, Db, and the optional fp are defined. Returns FALSE otherwise.
cleanUp
(tDB 4, tDB 5)
cleanUp -- frees caches and fps
Description
int cleanUp ( void )
Until tDB 4.3.4, cleanUp only destroyed fps. In more current versions, it also destroys the cache information about the tables and records.
Example 1. cleanUp() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta1', 'theTable1'); //Stores the fp
$header = $tdb->__readHeader('ta1'); //Caches the header
$tdb->cleanUp();
?>
Example 2. Changing TextDBs
Please note that when you switch to another TextDB, that the cache information from the last TextDB has not been cleared.
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable1'); //Stores the fp
$header = $tdb->__readHeader('ta'); //Caches the header
$tdb->tdb('./db/', 'TextDB'); //fp and cache still valid
$tdb->cleanUp();
?>
createDatabase
(tDB 4, tDB 5)
createDatabase -- creates a new TextDB
Description
bool createDatabase ( string directory, string name )
Creates a new TextDB based on the arguments. createDatabase() will return FALSE and generate errors if 1) the TextDB already exists, 2) The directory is not writable, or 3) the directory is not a valid path.
createDatabase() will automatically append the extention "" to the name if it needs it, and it will append a backslash to the directory if it doesn't have it already.
Example 1. First way to create a TextDB
There are two ways to create a TextDB. One way is by using an object.
<?php
require('tdb.class.php');
$tdb = new tdb('', '',);
$tdb->createDatabase('./db/', 'database');
$tdb->tdb('./db/', 'database');
?>
Example 2. Second way to create a TextDB
Warning If any of the three errors mentioned above occurs, it will cause a Fatal Error, ending the script.
<?php
require('tdb.class.php');
tdb::createDatabase('./db/', 'database');
$tdb = new tdb('./db/', 'database');
?>
See Also removeDatabase() and Installation and Configuration
createSortingArchive
(tDB 5 > 5.1)
createSortingArchive -- creates a sorting archive
Description
bool createSortingArchive ( string fp, string nickname , array instructions )
Creates a sorting archive named nickname for the table specified by fp, with the sorting method specified by instructions. If instructions is empty (lit. a string with length 0), it will attempt to delete the sorting archive. createSortingArchive() will return FALSE and generate an error if 1) it tries to create the sorting archive, but the nickname specified already exists, 2) it tries to delete the sorting archive, but the nickname specified does not exist, 3) the format for instructions is incorrect, or 4) a field specified in instructions does not exist. createSortingArchive() will also return FALSE and generate errors based on __check().
instructions Example:
instructions is useful because if a table's field has multiple records with the same values, it will sort inside of that field, based on the second specified field (if any)
Array
(
[theField1] => DESC
[theField2] => ASC
[id] => ASC
)
createSortingArchive()'s usefulness comes in retrieving records. If you specify an existing nickname in basicQuery(), query(), listRec(), or get(), it will retrieve records in the order it was sorted when createSortingArchive() was run. sort(), compared to createSortingArchive(), also sorts the records in ascending or descending order, but is limited to only one field, and is slower. sort() uses a linear search, where as createSortingArchive() uses a binary search.
See Also sort().
createTable
(tDB 4, tDB 5)
createTable -- creates a Table
Description
bool createTable ( string table_name, array fields [, int memo_block_size ] )
Creates a table based on the arguments. Fields is a Multiple Field array.
It will return FALSE and generate errors if 1)fields is not an array, 2) a table with the name table_name already exists, 3) or any fields' type is invalid (not "string", "number", "memo", or "id"). createTable() will also return FALSE and generate errors based on __check().
Since tDB 5, the script will prepend the TextDB's name to the table_name if you have not done so. Also in tDB 4.4 the optional memo_block_size has been added to define the number of bytes a memo block will be. This does not limit how long the value of a field has to be. If you expect to store smaller amounts of information, set this to a lower number. If you expect to store bigger bytes of information, set memo_block_size to a higher number. The default value for memo_block_size is 100.
See Also deleteTable() and Installation and Configuration
define_error_handler
(tDB 5 >= 5.0.2)
define_error_handler -- sets the error handler
Description
void define_error_handler ( mixed method )
Sets the error handler to method. method may be a user defined function. Class methods may also be invoked statically using this function by passing array(&$classname, $methodname) to the method parameter. The user defined function defined by method must accept an error code for its first argument, the error message for its second argument, and an optional line number for its third argument.
TextDB errors will not be passed to te error handler if the constant TDB_PRINT_ERRORS is set to TRUE, which will cause __sendError() to print directly to the screen. If TDB_PRINT_ERRORS is FALSE and an error handler was not defined, __sendError() will trigger an error.
For examples and more information, See also call_user_func()
See also __sendError()
delete
(tDB 4, tDB 5)
delete -- delete a record
Description
bool delete ( string fp, int id )
Deletes a record based on the id from the table specified by the table pointer fp. delete() will return TRUE on success or FALSE and generate errors if it cannot identify the id. It will also return FALSE and generate errors based on __check().
Example 1. delete() Example
<?php
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$tdb->delete('ta', 1);
?>
__deleteMemo
(tDB 5)
__deleteMemo -- deletes memo blocks
Description
void __deleteMemo ( string fp, int memo_pointer, array header )
Note This is an internal function, not meant to be used outside of the tdb class.
__deleteMemo deletes memo blocks based on memo_pointer from the table specified from the filepointer fp. header must be defined by __readHeader(). Fails and generates errors if __deleteMemo() tries to delete the 0th block, if memo_pointer is empty, or if the __deleteMemo() tries to delete the same block in a loop.
See Also __readMemo(), __writeMemo(), and createTable().
edit
(tDB 4, tDB 5)
edit -- edit a record
Description
bool edit ( string fp, int id, array input )
Edits a record specified by in with the parameters of input in the table specified by the table pointer fp. Returns TRUE on success. Returns FALSE and generates an error if it cannot find the record based on id. edit() will also return FALSE and generate errors based on __check().
Example 1. edit() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./tdb/', 'database');
$tdb->setFp('ta', 'theTable');
$array = array('name' => 'bob');
$array['age'] = 42;
$tdb->edit('ta', 1, $array);
?>
Example 2. Editing some values
You can choose to edit certain fields of a record, When you execute edit() don't include the fields you don't want to edit in the input.
<?php
//assume 2 fields: name & age
require('tdb.class.php');
$tdb = new tdb('./tdb/', 'database');
$tdb->setFp('ta', 'theTable');
$array = array();
$array['age'] = 42;
$tdb->edit('ta', 1, $array);
?>
editField
(tDB 4 >= 4.3.3, tDB 5)
editField -- edits a field's properties
Description
bool editField ( string fp, string field_name, array new_field )
Edits the properties of an existing field named field_name in the table specified by the table pointer fp. It changes the properties of the field to the new properties in new_field. new_field follows the Single Field array format.
editField will return false if the field is not found or if the field_type specified in new_field is invalid. editField() will also return FALSE and generate errors based on __check().
Warning If the new field length is shorter than the old one, values of the field in all records may be shortened to confirm with the field's new parameters.
Warning Changing the field type, will also alter the value to conform to the field's parameters. If field type was string and changed to number, only numeric characters will remain.
Example 1. editField() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$tdb->editField('ta', 'theField', array('theNewFieldName', 'string', 35));
?>
Example 2. Changing the field_type
<?php
//theField's properties: array('theField', 'string', 35)
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
//changing theField's properties:
$tdb->editField('ta', 'theField', array('theField', 'number', 35));
//All characters except numbers, periods, and dashes have been stripped.
?>
See Also addField(), removeField() and getFieldList().
__fileIdById
(tDB 4, tDB 5)
__fileIdById -- retrieves the FileId by the recordId
Description
int __fileIdById ( string fp, int id )
Note This is an internal function, not meant to be used outside of the tdb class.
Returns fileId, or the position of the record, based on the id, or recordId, in the table specified by the table pointer fp. __fileIdById() returns FALSE upon failure. Before tDB 5, __fileIdById() would return a -1 upon failure. __fileIdById() returns FALSE if id was not found in the reference file. If the fileId found is less than one __fileIdById() will return FALSE and generate an error. It will also return FALSE and generate errors based on __check().
get
(tDB 4, tDB 5)
get -- gets a record
Description
array get ( string fp, int id [, array fields ] )
Returns a multidimentional array of a record specified by id found in the table specified by the table pointer fp. Will return FALSE and generate an additional error based on __fileIdById(), or if the record found was deleted. Since tDB 5 > 5.1, the fourth optional argument fields was added to specify which fields' values you want, instead of retrieving ALL the values.
The multidimentional array returned uses the same format of query() uses except there is only one array instead of multiple.
Example 1. get() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable);
$record = $tdb->get('ta', $_GET['id']);
print_r($record);
?>
Example 2. get()'s return
Example 1 would print something simular to this:
Array
(
[0] => Array
(
[theField1] => data
[theField2] => moredata
[id] => 1
)
)
Example 3. SELECT Fields Functionality
<?php
require('tdb.class.php');
$tdb = new tdb('./db/,' 'database');
$tdb->setFp('ta', 'theTable');
$tdb->get('ta', 1, array('field1', 'field3' 'field9')); //retrieve only 3 fields' values, instead of reading unnecessary values.
?>
See Also listRec() and query().
get_ref_data
(tDB 5)
get_ref_data -- retrieves the order of records and recordId to fileId reference data
Description
string get_ref_data ( string fp )
Note This is an internal function, not meant to be used outside of the tdb class.
Retreives the *.ref information and caches it for further use. get_ref_data() returns FALSE and generate errors based on __check().
getFieldList
(tDB 4, tDB 5)
getFieldList -- Retrieves the field's list
Description
array getFieldList ( string fp )
Returns fields and their parameters from the table specified by the table pointer fp. The format follows the regulations of the Language Reference:Field Array. getFieldList returns FALSE and generate errors based on __check().
Example 1. getFieldList() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable);
$fields = $tdb->getFieldList('ta');
print_r($fields);
?>
Example 2. getFieldList()'s return
Example 1 would print something simular to this:
Array
(
[0] => Array
(
[fName] => thefield1
[fType] => string
[fLength] => 15
)
[1] => Array
(
[fName] => thefield2
[fType] => memo
[fLength] => 10
)
)
getNumberOfRecords
(tDB 4, tDB 5)
getNumberOfRecords -- retrieves the number of records
Description
int getNumberOfRecords ( string fp )
Retrieves the number of records from the table specified by the table pointer fp. getNumberOfRecords returns FALSE and generates errors based on __check().
Example 1. getNumberOfRecords() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable);
$howmany = $tdb->getNumberOfRecords('ta');
echo $howmany;
?>
getTableList
(tDB 4, tDB 5)
getTableList -- retrieves the table list
Description
array getTableList ( void )
Retrieves the table list of the database. getTableList returns FALSE and generate errors based on __check().
Example 1. getTableList() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tables = $tdb->getTableList();
?>
isTable
(tDB 4, tDB 5)
isTable -- verifies a table
Description
bool isTable ( string table_name )
isTable() to see if the table table_name exists in the database. Returns TRUE if found, or FALSE is not found. It will also return FALSE and generate errors based on __check().
Note table_name is literally the table's name and is not the table pointer fp.
listRec
(tDB 4, tDB 5)
listRec -- retrieves consecutive records
Description
array listRec ( string fp, int start [, int howmany [, array fields]]] )
Retrieves a Multiple Records array of consecutive records skipping start amount of records from the first one and only returning howmany amount of records. If start is set to 1, listRec() will begin from the first record. If howmany is not set or set to a negative number, all records after start will be returned. listRec() will return FALSE and generate errors if it start exceeds the number of records or if there is a parsing error. It will also return FALSE and generate errors based on __check(). For more information on the format of the multidimentional array, read Multiple Records.
Example 1. listRec() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/,' 'database');
$tdb->setFp('ta', 'theTable');
$tdb->listRec('ta', 20, 20);
//skips the first twenty and retrieves the subsequent twenty
?>
Example 2. Retrieving all records
<?php
require('tdb.class.php');
$tdb = new tdb('./db/,' 'database');
$tdb->setFp('ta', 'theTable');
$tdb->listRec('ta', 1);
?>
Since tDB 5 > 5.1, the fourth optional argument fields was added to specify which fields' values you want, instead of retrieving ALL the values.
Example 3. SELECT Fields Functionality
<?php
require('tdb.class.php');
$tdb = new tdb('./db/,' 'database');
$tdb->setFp('ta', 'theTable');
$tdb->listRec('ta', 1, -1, array('field1', 'field3' 'field9')); //retrieve only 3 fields' values of all records, and doesn't read unnecessary values.
?>
__parseRecord
(tDB 4, tDB 5)
__parseRecord -- parses a raw record
Description
array __parseRecord ( string fp, string raw_record, array header )
Note This is an internal function, not meant to be used outside of the tdb class
Parses the raw record, raw_record based on header and retrieves memo data from the table specified by the filepointer fp. Since tDB 5, __parseRecord() returns an empty array and generates errors if raw_record contains a deleted record marker.
__parseQueryString
(tDB 5 >= 5.1)
__parseQueryString -- parses a tDB query string into an array for the function query() to read
Description
array __parseQueryString ( string queryString )
Note This is an internal function, not meant to be used outside of the tdb class
Parses the query string, queryString into an array for query(). __parseQueryString() will exit and generate an error if there is a syntax error.
See Also query().
query
(tDB 4 >= 4.3, tDB 5)
query -- queries a table
Description
array query ( string fp, string query_string [, int start [, int howmany ]] )
Queries a table specified by the table pointer fp with the parameters specified in the query_string. If start is defined, query() will skip that many results before retrieving records. If howmany is defined, instead of returning all results (after skipping the number of results defined by start), it will return the number specified by howmany. Note default for start is one and the default for howmany is all records preceeding after start.
query() will ignore a parameter defined in query_string and generate an error if the query syntax is invalid. query() will generate an error if a field is invalid. query() will ignore a record if it is unable to parse it. query() will also return FALSE and generate errors based on __check().
query() will return a multidimentional array. For more information, see Multiple Records.
query_string syntax
The query_string is used as the parameters for retrieving records that share the same or simular values in muliple fields. The six syntaxes that query_string utilizes are = (equal sign), > (greater than symbol), < (less than symbol), ? (question mark), && (double ampersand), and ' (single quotes). Using these syntaxes, it is quite simular to $_SERVER['QUERY_STRING']. Consider the following:
As of version 5.0.3 the || (double pipe) is now supported to allow for OR logic within the query string, a example is posted below.
$_SERVER['QUERY_STRING'] = "name=bob&age=40&location=London" $query = "name='bob'&&age='40'&&location='London'"
The syntax && (double ampersand) separates the fields that is being searched. The syntax = (equal sign) means that the field HAS TO equal it. The syntax ? (question mark) means the phrase that follows it is somewhere in that field. The syntaxes >(greater than) and <(less than) are for fields whose field_type is number that respectfully has a value greater than or less than the specified ammount. The syntax '(single quote) is used to define the value of the field in question.
Example 1. query_string format
The other comparison syntaxes can be useful when searching for information that doesn't exactly match the field. Consider the following, when querying for a man named Bob Johnson, age 40, living in London U.K., and we don't know everything about him. If we know his first name, that he's older than 18, and he lives in the London, we can get query for results without having definite values:
<?php
$query = "name?'Johnson'&&age>'18'&&location?'London'"
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'thetable');
$tdb->query('ta', $query);
?>
This allows you to query a large table of records and retieve broader results. With ? (question mark), you can look for a part of a string within the value.
Example 2. New tDB 5.1 Ability: OR Logical Operator
The following example shows the new functionality available in version 5.1. Logically the following example would read: If name contains Joe and age is less than 57 OR name contains Joe and age is equal to 60.
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$query = "name?'Joe'&&age<'57'||name?'Joe'&&age='60'";
$records = $tdb->query('ta', $query, 1, 3);
?>
Example 3. New tDB 5.1 Ability: SELECT Fields
The following example shows how to use the SELECT Fields ability introduced in tDB 5.1. If you are querying a table for a person named Joe, but you only want to recieve certain information, like there interests and location, it is possible.
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$query = "name?'Joe'&&age<'57'||name?'Joe'&&age='60'";
$records = $tdb->query('ta', $query, 1, 3, array('interests', 'location'));
?>
More Examples
The following is a very specific query with few, if any results
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$query = "name='Carl'&&age='47'&&interests='tv'";
$records = $tdb->query('ta', $query);
?>
The following is a less specific query with more results
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$query = "name='Carl'&&age<'47'&&interests?'tv'";
$records = $tdb->query('ta', $query);
?>
The following is a very broad query, but will only return the first three results
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$query = "age<'47'";
$records = $tdb->query('ta', $query, 1, 3);
?>
See Also basicQuery() and __parseQueryString().
__readHeader
(tDB 4, tDB 5)
__readHeader -- retrieves the header
Description
bool __readHeader ( string fp, array &header )
Note This is an internal function, not meant to be used outside of the tdb class.
Retrieves the header information and stores it in header of the table specified by the table pointer fp. Returns TRUE upon success or FALSE if it cannot access the table file. __readHeader() will also return FALSE and generate errors based on __check().
Note header information is cached.
Also See getFieldList().
__readMemo
(tDB 5)
__readMemo -- retrieves information from the memo file
Description
string __readMemo ( string fp, int memo_pointer, array header )
Note This is an internal function, not meant to be used outside of the tdb class.
Retrieves a memo entry based on memo_pointer using header information in the table specified by the file pointer fp. __readMemo() will stop if memo_pointer is negative or empty. __readMemo() will stop the script and generate an error if it enters into a continuous loop or if it encounters an non-numeric, internal or external memo pointer.
removeDatabase
(tDB 4, tDB 5)
removeDatabase -- removes a database
Description
bool removeDatabase ( void )
Removes all of the tables from and including the database. removeDatabse() will return FALSE and generate errors based on __check().
Example 1. removeDatabase() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->removeTable();
?>
See Also createDatabase().
removeTable
(tDB 4, tDB 5)
removeTable -- removes a Table from the current Database
Description
bool removeTable ( string table_name )
Removes the table, table_name, from the database. Returns FALSE if table_name does not exist. removeTable() will also return FALSE and generate errors based on __check(). Otherwise, removeTable() will return TRUE.
Note: table_name is not a table pointer set by setFp().
Example 1. removeTable() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->removeTable('theTable');
?>
See Also createTable()
removeField
(tDB 4 >= 4.3.3, tDB 5)
removeField -- removes a field from a table
Description
bool removeField ( string fp, string field)
Removes field from the table specified by the table pointer fp. Returns FALSE if field is not found, otherwise returns TRUE. removeField() will also return FALSE and generate errors based on __check().
Example 1. removeField() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$tdb->removeField('ta', 'field1');
?>
See Also addField(), editField(), and getFieldList()
__sendError
(tDB 4, tDB 5)
__sendError -- triggers errors caused in the TextDB class
Description
string __sendError ( int error_number, string error_string [, int error_line ] )
Note This is an internal function, not meant to be used outside of the tdb class.
Triggers an error with the error code, error_number with the message, error_string. If error_line is defined, the error message will reference it in the tdb.class.php. The error_line was added in tDB 5. If the constant TDB_PRINT_ERRORS is set to TRUE, __sendError() will print directly to the screen, regardless if an error handler was defined. If TDB_PRINT_ERROR is FALSE and an error handler was not defined, __sendError() will trigger an error.
Since tDB 5, the argument, error_number did not exist. The only existing argument in tDB 4 < 4.4 was error_string.
See also define_error_handler() and php.net's trigger_error().
setFp
(tDB 4, tDB 5)
setFp -- sets an internal table pointer
Description
bool setFp ( string fp, string table)
Sets an internal table pointer, fp to the table. If fp is being redefined, meaning fp was set before and is being set again, all cached information will be destroyed.
Example 1. setFp() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->createTable('theTable', array(array('theField', 'string', 20)));
$tdb->setFp('ta', 'theTable');
$tdb->add('ta', array('theField' => 'insert data here'));
?>
See Also cleanUp().
sort
(tDB 4, tDB 5)
sort -- reorganizes a table's records
Description
bool sort ( string fp, string field_name [, string direction ] )
Sorts records by the value of the field field_name in the table specified by the table pointer fp. direction can be defined as "ASC" or "DESC" and will sort the records ascendingly or descendingly repectively. The default for direction is ASC. Records may only be sorted by fields that have a field type of string, number, or id; memo is not accepted.
sort() will return FALSE and generate errors if the file type of field_name is memo or if field_name does not exist in the table sort() will also return FALSE and generate errors based on __check().
Example 1. sort() Example
<?php
require('tdb.class.php');
$tdb = new tdb('./db/', 'database');
$tdb->setFp('ta', 'theTable');
$tdb->sort('ta', 'theField', 'DESC');
?>
See Also createSortingArchive().
tdb
(tDB 4, tDB 5)
tdb -- initiates the TextDB class
Description
bool tdb ( [ string directory [ , string tdb_name ]] )
Initiates the TextDB, and if directory and tdb_name is defined, defines the directory and the tdb_name for use. tdb() will return FALSE if directory and tdb_name is not set. tdb() will return FALSE and generate errors if directory is not a valid path, directory is writable, or if tdb_name isn't writable.
Example 1. tdb() Example
<?php
require('tdb.class.php');
tdb::createDatabase('./db/', 'database');
$tdb = new tdb('./db/', 'database');
//prone to fatal errors if unexpected errors arises.
?>
Example 2. tdb() Example
<?php
require('tdb.class.php');
$tdb = new tdb('', '');
$tdb->createDatabase('./db/', 'database');
$tdb = new tdb('./db/', 'database');
?>
Example 3. Switching TextDBs
You can go from one TextDB to another by using tdb().
<?php
require('tdb.class.php');
$tdb = new tdb('', '');
$tdb->createDatabase('./db/', 'database');
$tdb->createDatabase('./db/', 'textdb');
$tdb = new tdb('./db/', 'database');\
$tdb->createTable('members', array(array('name', 'string', 20), array('age', 'number' 3), array('location', 'memo')));
$tdb->cleanUp();
$tdb->tdb('./db/', 'textdb');
$tdb->createTable('archive', array(array('title', 'string', 35), array('date', 'number', 14), array('data', 'memo'), array('item_number', 'id')));
?>
See Also createDatabase().
version
(tDB 4, tDB 5)
version -- gets the current TextDB version
Description
string version ( void )
Returns a string containing the version of the current TextDB class.
Example 1. version() Example
<?php
require('tdb.class.php');
// prints e.g. 'Current TextDB version: 5.0.2'
echo 'Current TextDB version: ' . $tdb::version();
$tdb = new tdb();
// prints e.g. 'Current TextDB version: 5.0.2'
echo 'Current TextDB version: ' . $tdb->version();
?>
__writeMemo
(tDB 5)
__writeMemo -- stores information in the memo file
Description
int __writeMemo ( string fp, string data, array header )
Note This is an internal function, not meant to be used outside of the tdb class.
Stores information data to the table specified by the table pointer fp, using the the header information, header, which was called through __readHeader(). __writeMemo() will stop the script if it enters into a continuous loop and generate an error.
See Also __readMemo(), __deleteMemo(), and createTable().
FAQ: Frequently Asked Questions
If you have questions or are looking for answers, look in our TextDB Discussion Forum
