Docs For Class DBLQuery

Class DBLQuery

Description

Abstract superclass of a data source.

DBLIB uses generalized database model and this is it's main class. The model allows you to use DBLIB with different data sources. The most common one is a SQL database, but you may also wish to use LDAP, files, or even your own query types (see DBLArrayQuery for example).

The datasource here does not mean only source - it also provides ways to modify/create/delete records.

Please note, that DBLQuery descendant is responsible for properly converting (escaping) all values it is passed. So if your application uses DBLQuery to access database, it is safe!

It is quite hard to provide uniform interface to such different data bases. So rather the methods defined here are for the greatest functionality the DBLQuery descendant may provide. They may not be implemented all.

I suppose the application using DBLIB will know what database it uses and so what functionality the database can provide. If the database cannot do record ordering, the application cannot use order in filters. If it cannot do record range limiting, the application cannot use paged indexes, etc. Notes on required DBLQuery functionality can be found in DBLView method description.

However, DBLQuery descendants MAY provide some of the functionality missing in the DB engine, it's up to them.

Located in /DBLQuery.php (line 39)

Direct descendents

Class	Description
DBLArrayQuery	Query returning values from a (static) array as rows.
DBLSQLQuery	DBLQuery (abstract) subclass implementing routines common for all SQL databases.

Variable Summary

array $conditions

DBLDBDef $def

mixed $fields

int $offset

string $orderDef

bool $orderReferse

int $records

string $srcDef

array $values

Method Summary

DBLQuery DBLQuery (DBLDBDef &$def, mixed $sourceDef)

void addCondition (string $name, string $oper, string $value, bool $computed)

int addRecord ()

void addValue (string $name, string $value)

void clearConditions ()

void clearValues ()

void deleteRecord ()

string formatDateTime (array &$arr, bool $includeDate, bool $includeTime)

string getDefaultDateTime (bool $date, bool $time)

bool isEmptyDateTime (mixed $dateTime, string $datetime)

modifyRecord ()

mixed nextRecord ()

int parseDateTime (string $dateTime, array &$arr)

void reset ()

int search ()

void setFields (mixed $fields)

void setLimit (int $offset, int $records)

void setOrder (mixed $orderDef, bool $reverse)

void setSource (mixed $sourceDef)

Variables

array $conditions (line 59)

var: Internal array where DBLQuery stores set conditions (used in search/modify). Format is class dependent.

DBLDBDef $def (line 44)

var: Database definition.

mixed $fields (line 72)

var: Internal array where fields to be returned from search() are stored. Class dependent. This is, for example, string for SQL.

int $offset (line 76)

var: Internal - stores record offset to start returning search result from.

string $orderDef (line 63)

var: Internal - order definition. Class dependent.

bool $orderReferse (line 67)

var: Internal flag that order is reverse (i.e., descending)

int $records (line 80)

var: Internal - maximum number of records to return from search resilt.

string $srcDef (line 49)

var: Source definition (e.g., table name for SQL). Class dependent, see class constructor for description

array $values (line 54)

var: Internal array where DBLQuery stores field values to be set on modify/create record. The array is associative (name => value).

Methods

Constructor DBLQuery (line 88)

Constructor.

DBLQuery DBLQuery (DBLDBDef &$def, mixed $sourceDef)

DBLDBDef $def: Database definition.
mixed $sourceDef: Source definition. Class dependent.

addCondition (line 148)

Add condition to 'filter records'.

The conditions are used in three functions: - In the search() method, to limit which rows will be returned. - In tthe modifyRecord() method to designate which records will be modified. - In tthe deleteRecord() method to designate which records will be deleted.

This method is rather general. It is used by the DBLView class to implement filters, so it should be implemented by the DBLQuery class you use, if you wish to use the filters. There MAY be class specific methods to add DB specific conditions.

The operators that should be supported: <, >, =, !=, <>, <=, >=, wild (* and ? wildcards)

void addCondition (string $name, string $oper, string $value, bool $computed)

string $name: Field name to filter by.
string $oper: Condition operator. See method description for available operators.
string $value: Value to filter by. It should not be escaped in any way! It is DBLQuery responsibility to escape values.
bool $computed: Indicates that we filter not by a database field, but by a computed value. Used by SQL to place the condition to HAVING section instead of WHERE.

Redefined in descendants as:

DBLSQLQuery::addCondition()

addRecord (line 282)

Adds new record.

This is the method if you want to create a new record with DBLQuery. First you shoult setup values (by the addValue method), then call addRecord to create the record.

NOTE: This method does not clear the conditions/values set!

return: When it is possible/applicable, the method should return the value of the new record, when it has auto-incrementing primary key.

int addRecord ()

Redefined in descendants as:

DBLSQLQuery::addRecord()

addValue (line 257)

Adds value to be used to modify/create record.

void addValue (string $name, string $value)

string $name: Field name
string $value: Field value. It should not be escaped in any way! It is DBLQuery responsibility to escape values.

clearConditions (line 156)

Clear all set conditions.

void clearConditions ()

clearValues (line 265)

Clears all set values.

void clearValues ()

deleteRecord (line 320)

Deletes record(s).

This method deletes all records that match set conditions. You will usually want to set the condition to match primary key of the modified record ;-)

DBLIB does not use this method directly, it is here just for the function set to be complete.

NOTE: This method does not clear the conditions set!

void deleteRecord ()

Redefined in descendants as:

DBLSQLQuery::deleteRecord()

formatDateTime (line 337)

Format datetime for the database backend.

This is used by the DBLIB to format the date to pass to the addValue/addCondition method.

return: Datetime formated for the addValue/addCondition method.

string formatDateTime (array &$arr, bool $includeDate, bool $includeTime)

array $arr: Array to store date in. Used indexes are Y, m, d, H, M, S
bool $includeDate: Include date in the resulting string
bool $includeTime: Include time in the resulting string

Redefined in descendants as:

DBLSQLQuery::formatDateTime()

getDefaultDateTime (line 377)

Return default date/time/datetime in the DB notation

string getDefaultDateTime (bool $date, bool $time)

bool $date: Include date
bool $time: Include time

Redefined in descendants as:

DBLSQLQuery::getDefaultDateTime()

isEmptyDateTime (line 365)

Return whether the date/datetime is "empty"

bool isEmptyDateTime (mixed $dateTime, string $datetime)

string $datetime: date/datetime to check

Redefined in descendants as:

DBLSQLQuery::isEmptyDateTime()

modifyRecord (line 302)

Modifies existing record(s).

This method modifies existing records in the data source. The records are specified by set conditions (addCondition). You will usually want to set the condition to match primary key of the modified record ;-)

Function modifies all fields of the record, which were added by addValue(). The other fields should not be touched (!).

NOTE: This method does not clear the conditions/values set!

modifyRecord ()

Redefined in descendants as:

DBLSQLQuery::modifyRecord()

nextRecord (line 245)

Gets next record from a result set.

After the search has been initiated by caling the search() method, you can get the record(s) from the search by this method.

return: When no more records are availavle, the method should return false. When a record record is available, the method returns an associative array (field_name => field_value).

mixed nextRecord ()

Redefined in descendants as:

DBLArrayQuery::nextRecord() : Get next "record" - next array element.
DBLPGSQLQuery::nextRecord()
DBLMYSQLQuery::nextRecord()

parseDateTime (line 354)

Parse date or datetime from the database backend format to variables.

Dates are returned in human form - years in AD, months 1..12, days 1..31. When only date is passed in (without time), hour, minute and second are set to 0.

return: -1 when the value was not a valid date or datetime, 0 when a date was parsed, 1 when a datetime was parsed.

int parseDateTime (string $dateTime, array &$arr)

string $dateTime: Date/datetime to parse
array $arr: Array to store date in. Used indexes are Y, m, d, H, M, S

Redefined in descendants as:

DBLSQLQuery::parseDateTime()

reset (line 102)

Reset query.

This method 'resets' query to the state as if it was just created. Removes all set conditions, values, orders, limits (AND!) sources. so you have to call setSource after this!

void reset ()

Redefined in descendants as:

DBLSQLQuery::reset()

search (line 230)

Starts retrieving data from the data source.

This method initiates record search. After the search is initiated, data row can be get by calling the nextRecord() method.

return:
Number of rows that will be returned. This is used by DBLView::index() to implement paging. If you don't know this (or it is too costly to determine), the method should return -1. The the "Next Page" link will be always active, if you use paging and the index will not automatically "page back" when you delete all records on a page.
NOTE: This method does not clear the conditions set!

int search ()

Redefined in descendants as:

DBLArrayQuery::search() : "Start searching".
DBLSQLQuery::search()

setFields (line 195)

Set fields to be returned from search()/nextRecord() methods.

This method may be used to limit/specify which fields of the record will be returned. Its format is class dependent. By default, all applicable fields should be returned.

If you wish to use the lookup fields, the query you use should implement some kind of field aliasing (so that the record the query returns contains id and text fields). The fields specification is the place where field aliasing should be specified.

void setFields (mixed $fields)

mixed $fields: Fields to return (and) field aliasing specification. Class dependent.

setLimit (line 210)

Limits range of records to be returned from search()/nextRecord() methods.

This method sets range of records to return. It is used by the DBLView class to implement record index paging. If the DBLQuery descendant does not support record ranges, you cannot use paging (set DBLView::pageLength to 0).

void setLimit (int $offset, int $records)

int $offset: Offset of the first records (0 = first record)
int $records: Maximum number of records to return.

setOrder (line 174)

Set query order.

This method sets order of the records returned by the search() (and then nextRecord()) methods. If record ordering is not implemented by DBLQuery descendant, then you may not use the _order field in the filter form (see DBLView::filter()).

void setOrder (mixed $orderDef, bool $reverse)

mixed $orderDef: Order definition. Class dependent.
bool $reverse: Indicates that the record order should be reverse than the order specified by the $orderDef parameter. It is used by the DBLView to implement the 'Reverse' checkbox.

Redefined in descendants as:

DBLSQLQuery::setOrder()

setSource (line 118)

Set new source (sets the srcDef property).

void setSource (mixed $sourceDef)

mixed $sourceDef: Source definition. Class dependent.

Documentation generated on Mon, 6 Sep 2004 21:57:17 +0200 by phpDocumentor 1.2.3