This is the base class of zoglair database drivers. It defines all methods required for persistent I/O operations, as well as a few implementation specific stubs. Methods must conform to the ANSI92 standard.
It should be noted that there is no provision for raw (~arbitrary) sql statements. All CRUD and SELECT operations are made through related wrappers (~facades). For example, instead of using something like:
$ROW = $zDbms->sql("SELECT * FROM user WHERE id=1");
... the following is used:
$ROW = $zDbms->select("user", 1);
A descendant of this class is instantiated as the globally available $zDbms object, based on the “plugin”
setting in zoglair.cfg.php ($Z_DOM).
- Parent Class
- zObject
- Public Methods (11)
- __construct, build_mulid_where, delete, error, error_str, insert, qualify_name, qualify_pair, qualify_value, select, update
- Protected Methods
- none
void __construct(array $INFO) ⇧
Descendants should use their constructor to connect/select a database, plus define actual library calls under the “z_cmd”
property key. Zoglair will pass all necessary information, as per zoglair.cfg.php settings.
- Parameters
- Initial object properties (see zObject's constructor)
- Returns
- void
string build_mulid_where(mixed $mixed, string $col=zDataBase::Z_COL_NAME_ID) ⇧
Constructs a WHERE clause for SELECTing rows by multiple column values. The result is suitable for using as the value of the “where”
key in $ARGS of select(). For example:
$s = $zDbms->build_mulid_where('1,3,5'); // $s = '`id` IN (1,3,5)'
- Parameters
- • A CSV string or array with column values
- • The column name to use (default:
“id”
)
- Returns
- A WHERE clause suitable for passing to select()
mixed delete(mixed $mixed, mixed $where) ⇧
Implements the corresponding SQL statement, for deleting rows from a table:
DELETE FROM table WHERE where
Examples:
$zDbms->delete('table', $id);
$zDbms->delete('table', 'col=5');
- Parameters
- • A table name or object (created via zoglair::load_table())
- • A condition or just a row's ID
- Returns
- Affected rows or zDbmsBase::Z_ERROR
array error() ⇧
Returns error information about the last failed query. A query can fail either at the model level (zDataBase) or the DBMS level (zDbmsBase). Specifically, before a ROW gets inserted or updated, $zDbms asks the table to validate it. This is called “fixing”
, and it is implemented through a call to fix_row(). If that method returns an error, this is saved under the “z_fix”
key (see below) and the SQL statement is aborted. Otherwise, it is sent to the DBMS, which can itself respond with an error, too.
- Parameters
- none
- Returns
- A MAP with the following keys:
errno
=> DBMS specific error number
error
=> DBMS specific error message
query
=> Failed query
z_fix
=> zDataBase::fix_row() error array
string error_str() ⇧
Returns a formatted DBMS error message, using the “errno”
and “error”
keys of the error() return value.
- Parameters
- none
- Returns
- A formatted error message:
“Error #%d: %s”
mixed insert(mixed $mixed, array $SOR, string $position='') ⇧
Implements the corresponding SQL statement, for inserting rows into a table:
INSERT INTO table (names) VALUES (values)
Examples:
$zDbms->insert('table', $ROW);
$zDbms->insert('table', $ROW, 'after 12');
- Parameters
- • A table name or object (created via zoglair::load_table())
- • A SET or ROW to be inserted
- • If the table is Sitemap, position of insert (pivot)
- Returns
- Last inserted row ID or zDbmsBase::Z_ERROR
string qualify_name(string $name) ⇧
[stub] Qualifies a column name, so that there is no clashing with keywords and/or an extended character set is accepted. This is implementation depended. For example, MySQL uses backticks for identifier qualification.
- Parameters
- The column name to be qualified
- Returns
- The qualified name
See also qualify_value().
string qualify_pair(string $name, string $value, string $op='=') ⇧
Qualifies a “name op value”
pair, using qualify_name() and qualify_value() accordingly.
- Parameters
- • The column name to be qualified
- • The column value to be qualified
- • An optional operand
- Returns
- The qualified pair
string qualify_value(string $value) ⇧
[stub] Qualifies and escapes a column value, so that it can safely used in SQL statements. This is implementation depended.
- Parameters
- The column value to be qualified
- Returns
- The qualified value
See also qualify_name().
mixed select(mixed $mixed, mixed $ARGS=NULL, boolean $ffo=FALSE, mixed $t2l=0) ⇧
Implements the corresponding SQL statement, for retrieving rows from one or more tables:
SELECT cols FROM table WHERE where GROUP BY group ORDER BY order LIMIT ...
Required clauses are passed in a map. The result of this function is usually a SET (vector of ROWs) but depending on $ARGS, it can be a single ROW or a count.
Examples:
$SET = $zDbms->select('table');
$SET = $zDbms->select('table', array('where'=>'condition','limit'=>'12'));
$ROW = $zDbms->select('table', $id);
$cnt = $zDbms->select('table', zDbmsBase::Z_COUNT);
- Parameters
- • A table name or object (created via zoglair::load_table())
- • A numeric ID, zDbmsBase::Z_COUNT or MAP with the various clauses applicable to SELECT. Known and supported clauses are:
'cols'
=> a column list
'from'
=> FROM
'where'
=> WHERE
'group'
=> GROUP BY
'havng'
=> HAVING
'order'
=> ORDER BY
'limit'
=> LIMIT
'join'
=> the join clause
- • Fix for output? (see fix_set())
- • A cache time-to-live value (see zCaheBase)
- Returns
- SET, ROW, count or zDbmsBase::Z_ERROR
See also “Common MySQL Queries”
, “A Visual Explanation of SQL Joins”
.
mixed update(mixed $mixed, array $ROW, mixed $where) ⇧
Implements the corresponding SQL statement, for updating rows in a table:
UPDATE table SET pairs WHERE where
Examples:
$zDbms->update('table', $ROW, $id);
$zDbms->update('table', $ROW, 'col=5');
- Parameters
- • A table name or object (created via zoglair::load_table())
- • A ROW with column values to be updated
- • A condition or just a row's ID
- Returns
- The query's result (driver specific)