zDbmsBase

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)
(C) Nick B. Cassos - All Rights Reserved
powered by zoglair
page generated in 55ms (11 queries, 6ms)