Abstract base class for database engines. More...

Inheritance diagram for DbEngine:

Public Member Functions
	beginTransaction ()
	begins a transaction; must be implemented by driver; use sqlBeginTransaction to create the SQL statement! More...

	canAdministrate ()
	returns whether a passcode is known and admin.php may be used More...

	canUseDb ($checkVersion=true)
	tries to find out whether the connected DB version is usable More...

	checkAdmin ()
	check admin credentials More...

	commitTransaction ()
	ends a transaction successfully; must be implemented by driver; returns true on success; use sqlCommitTransaction to create the SQL statement! More...

	createDb ()
	creates the database, used by admin.php only!! More...

	dbName ()
	returns the name of the database the instance is connected to More...

	deleteRows ($table, $where)
	delete database values; returns the amount of rows deleted or false if an error occurred; use sqlDelete to create the SQL statement! More...

	dumpBackup ()
	dump a backup (returned as string) More...

	escapeBlob ($s)
	escapes blobs; the default uses addslashes and encloses the value in ''; it is recommended to overwrite this with the proper escaping procedure for the target DB More...

	escapeBool ($s)
	escapes a boolean value; the default translates 0, '0', 'f', 'false', 'n', 'no', false to FALSE and numerics !=0, 't', 'true', 'y', 'yes', true to TRUE; any other value (incl. More...

	escapeColumn ($table, $col, $val)
	generic escape routine: queries the schema for the correct escape mechanism and then returns the appropriately escaped value More...

	escapeInt ($i)
	escapes integers; the default implementation just makes sure it is an int (false and null are translated to NULL) More...

	escapeIntList (array $il)
	escapes a list of integers; uses escapeInt for each element; automatically adds parentheses More...

	escapeListColumn (array $il, $table, $col)
	escapes a list of values for a specific column; uses escapeInt for each element; automatically adds parentheses More...

	escapeString ($s)
	escapes strings; the default uses addslashes and encloses the value in ''; it is recommended to overwrite this with the proper escaping procedure for the target DB (false and null are translated to NULL) More...

	escapeStringList (array $il)
	escapes a list of strings; uses escapeInt for each element; automatically adds parentheses More...

	exploreBackup ()
	explore the backup settings and database and return an index to the current data as structured text; each line has the following format: S T tablename [min max [groupSize]] V base64value E More...

	getConfig ($key)
	returns a configuration setting More...

	hasTable ($tablename)
	returns whether the table exists; must be implemented by driver More...

	insert ($table, array $values)
	insert values into a table; returns false on failure, the new primary key if a sequence was set, true otherwise; use sqlInsert to create the SQL statement! More...

	isConnected ()
	check whether the DB object is connected to an actual database More...

	isNull ($val)
	returns whether the result value is NULL; the default interprets only the special value null as NULL More...

	lastError ()
	returns the error string of the last operation More...

	needVersion ()
	returns the version of the DB layout that is required by this version of Magic Smoke More...

	restoreData ($file, $overwrite)
	called from admin.php: restore a backup More...

	rollbackTransaction ()
	ends a transaction with a rollback; must be implemented by driver; returns true on success; use sqlRollbackTransaction to create the SQL statement! More...

	select ($table, $cols, $where="", $orderby="")
	gets some data from the database; $table is the name of the table, $cols is the list of columns to return or "" for all, $where is the where clause of the SQL-statement, $orderby may contain additional ORDER BY or GROUP BY clauses; returns array of rows, which are in _fetch_array format; returns false on error; use sqlSelect to create the SQL statement!; make sure that NULL values are returned as PHP value null (most DB drivers already do this) More...

	setAdminPassCode ($u, $p)
	set the admin passcode; used by the config.php file if admin access is allowed More...

	setConfig ($key, $val)
	sets a config setting More...

	setTransactionUpdating ($tm)
	set the transaction mode: true if it is an updating transaction More...

	showCreateDb ()
	shows how the database would be created, used by admin.php only!! More...

	sqlBeginTransaction ()
	returns the SQL92 statement for beginning a transaction; overwrite this to implement DB specific syntax More...

	sqlCommitTransaction ()
	returns the SQL92 statement for committing a transaction; overwrite this to implement DB specific syntax More...

	sqlRollbackTransaction ()
	returns the SQL92 statement for rolling a transaction back; overwrite this to implement DB specific syntax More...

	sqlSelect ($table, $cols, $where, $orderby)
	creates a SQL92 statement for selects; overwrite this to implement DB specific syntax; the concrete DB implementation should append "for update" to the select statement if $this->transmode is true and the DB supports it More...

	syncSequence ($table)
	synchronize the sequence of one database table; overwrite to actually do something More...

	syncSequences ()
	synchronize all sequences with current data More...

	tableName ($tname)
	transform an internally used table name to the actual table name in the DB; the default implementation returns exactly what it gets More...

	transactionIsUpdating ()
	returns whether the DB driver currently believes to be in RW transaction mode More...

	tryConnect ()
	connect to the database, must be overwritten by DB driver More...

	update ($table, array $values, $where)
	update database values; returns how many rows have been changed or false for failure; use sqlUpdate to create the SQL statement! More...

	upgradeDb ($doexec=true)
	Upgrades the database, used by admin.php. More...

Public Attributes
const	COLUMN_CREATE_ALL = 0xffff

const	COLUMN_CREATE_CONSTRAINT = 64

const	COLUMN_CREATE_DEFAULT = 16

const	COLUMN_CREATE_FKEY = 8

const	COLUMN_CREATE_INDEX = 32

const	COLUMN_CREATE_KEY = 12

const	COLUMN_CREATE_NULL = 2

const	COLUMN_CREATE_PKEY = 4

const	COLUMN_CREATE_TYPE = 1

Protected Member Functions
	columnFlag ($flag, $col, $table, $cflags)
	returns the correct name/coding of a flag: primarykey, notnull, unique (implies notnull), foreignkey:$table:$col, defaultint:$val, defaultstr:$val, index More...

	createTable ($tablename, $table)
	creates a table; the argument is an array of the form "col-name" => array("col-type", "flags"...); use sqlCreateTable() etc. More...

	createTableExtras ($tablename, $table)
	This function can be used to amend the column definitions of a table; if overwritten it must return a string; overwrite this to implement DB specific syntax. More...

	dataType ($type)
	returns the correct type name for the required abstract data type; types that must be understood are: int32 (INTEGER), int64 (LONG INTEGER), seq32 (auto-incrementing int), seq64, bool (boolean), string:$length (text up to 255 chars, length is optional, default is 255; VARCHAR($length)), text (unlimited text) More...

	lockDB ($writelock)
	locks the database - only used by the backup functions; if necessary should also start a transaction; default just starts a transaction More...

	sqlCreateColumn ($tablename, $columnname, $columndef, $flags=self::COLUMN_CREATE_ALL)
	creates SQL92 part of a statement for creating a single column More...

	sqlCreateTable ($tablename, $table)
	creates a SQL92 statement for creating a table; overwrite this to implement DB specific syntax More...

	sqlCreateTablePrimaryKey (array $cols)
	creates primary key statement for sqlCreateTable; overwrite this to implement DB specific syntax More...

	sqlCreateTableUniqueConstraint (array $constraints)
	creates the complex unique constraints; overwrite this to implement DB specific syntax More...

	sqlDelete ($table, $where)
	creates a SQL92 statement for deletes; overwrite this to implement DB specific syntax More...

	sqlInsert ($table, array $values)
	creates a SQL92 statement for inserts; overwrite this to implement DB specific syntax More...

	sqlUpdate ($table, array $values, $where)
	creates a SQL92 statement for updates; overwrite this to implement DB specific syntax More...

	unlockDB ()
	unlocks the database - only used by the backup functions; if necessary should also commit a transaction; default just commits More...

	upgradeTable ($tablename, $doexec)
	helper for upgradeDb -> upgrades a single table More...

Protected Attributes
	$transmode =false
	transaction RO/RW mode: false=assume readonly, true=assume inserts/updates More...

Detailed Description

Abstract base class for database engines.

Member Function Documentation

DbEngine::beginTransaction ( )

abstract

begins a transaction; must be implemented by driver; use sqlBeginTransaction to create the SQL statement!

Referenced by createDb(), lockDB(), and setConfig().

DbEngine::canAdministrate ( )

returns whether a passcode is known and admin.php may be used

Referenced by checkAdmin().

DbEngine::canUseDb ( $checkVersion = true )

tries to find out whether the connected DB version is usable

References WobSchemaBase\configTable(), WobSchemaBase\configVersionRow(), getConfig(), hasTable(), isConnected(), and needVersion().

DbEngine::checkAdmin ( )

check admin credentials

References canAdministrate().

DbEngine::columnFlag	(	$flag,
		$col,
		$table,
		$cflags
	)

protected

returns the correct name/coding of a flag: primarykey, notnull, unique (implies notnull), foreignkey:$table:$col, defaultint:$val, defaultstr:$val, index

References $col.

DbEngine::commitTransaction ( )

abstract

ends a transaction successfully; must be implemented by driver; returns true on success; use sqlCommitTransaction to create the SQL statement!

Referenced by createDb(), setConfig(), and unlockDB().

DbEngine::createDb ( )

creates the database, used by admin.php only!!

References $i, beginTransaction(), commitTransaction(), createTable(), insert(), lastError(), rollbackTransaction(), sqlCreateTable(), WobSchemaBase\tableDefaults(), WobSchemaBase\tableDefinition(), and WobSchemaBase\tableNames().

DbEngine::createTable	(	$tablename,
		$table
	)

abstractprotected

creates a table; the argument is an array of the form "col-name" => array("col-type", "flags"...); use sqlCreateTable() etc.

to create the actual statement

Referenced by createDb(), and upgradeDb().

DbEngine::createTableExtras	(	$tablename,
		$table
	)

protected

This function can be used to amend the column definitions of a table; if overwritten it must return a string; overwrite this to implement DB specific syntax.

Referenced by sqlCreateTable().

DbEngine::dataType ( $type )

protected

returns the correct type name for the required abstract data type; types that must be understood are: int32 (INTEGER), int64 (LONG INTEGER), seq32 (auto-incrementing int), seq64, bool (boolean), string:$length (text up to 255 chars, length is optional, default is 255; VARCHAR($length)), text (unlimited text)

Referenced by sqlCreateColumn().

DbEngine::dbName ( )

abstract

returns the name of the database the instance is connected to

DbEngine::deleteRows	(	$table,
		$where
	)

abstract

delete database values; returns the amount of rows deleted or false if an error occurred; use sqlDelete to create the SQL statement!

DbEngine::dumpBackup ( )

dump a backup (returned as string)

References $col, WobSchemaBase\backupTables(), lockDB(), select(), WobSchemaBase\tableColumns(), and unlockDB().

DbEngine::escapeBlob ( $s )

escapes blobs; the default uses addslashes and encloses the value in ''; it is recommended to overwrite this with the proper escaping procedure for the target DB

Referenced by escapeColumn(), sqlInsert(), and sqlUpdate().

DbEngine::escapeBool ( $s )

escapes a boolean value; the default translates 0, '0', 'f', 'false', 'n', 'no', false to FALSE and numerics !=0, 't', 'true', 'y', 'yes', true to TRUE; any other value (incl.

the PHP constant null) is translated to NULL

Referenced by MysqlEngine\escapeBool(), escapeColumn(), sqlInsert(), and sqlUpdate().

DbEngine::escapeColumn	(	$table,
		$col,
		$val
	)

generic escape routine: queries the schema for the correct escape mechanism and then returns the appropriately escaped value

References $col, escapeBlob(), escapeBool(), escapeInt(), escapeString(), WobSchemaBase\isBlobColumn(), WobSchemaBase\isBoolColumn(), WobSchemaBase\isIntColumn(), and WobSchemaBase\isStringColumn().

Referenced by escapeListColumn().

DbEngine::escapeInt ( $i )

escapes integers; the default implementation just makes sure it is an int (false and null are translated to NULL)

References $i.

Referenced by escapeColumn(), escapeIntList(), sqlInsert(), and sqlUpdate().

DbEngine::escapeIntList ( array $il )

escapes a list of integers; uses escapeInt for each element; automatically adds parentheses

References $i, and escapeInt().

DbEngine::escapeListColumn	(	array	$il,
			$table,
			$col
	)

escapes a list of values for a specific column; uses escapeInt for each element; automatically adds parentheses

References $col, $i, and escapeColumn().

DbEngine::escapeString ( $s )

escapes strings; the default uses addslashes and encloses the value in ''; it is recommended to overwrite this with the proper escaping procedure for the target DB (false and null are translated to NULL)

Referenced by escapeColumn(), escapeStringList(), getConfig(), setConfig(), sqlInsert(), sqlUpdate(), and upgradeDb().

DbEngine::escapeStringList ( array $il )

escapes a list of strings; uses escapeInt for each element; automatically adds parentheses

References $i, and escapeString().

DbEngine::exploreBackup ( )

explore the backup settings and database and return an index to the current data as structured text; each line has the following format: S T tablename [min max [groupSize]] V base64value E

-> S/E mark the start/end of the data -> T is a table description line -> min/max are minimal/maximal integer values of the backup key, if both are "-" then it is a string column -> groupSize is the recommended size of backup groups (in different key values) for this table -> V is a single value of the backup key if the preceding table has a string backup key

References $col, WobSchemaBase\backupGroupSizeForTable(), WobSchemaBase\backupKeyForTable(), WobSchemaBase\backupTables(), WobSchemaBase\isIntColumn(), WobSchemaBase\isStringColumn(), and select().

DbEngine::getConfig ( $key )

returns a configuration setting

References WobSchemaBase\configKeyColumn(), WobSchemaBase\configTable(), WobSchemaBase\configValueColumn(), escapeString(), and select().

Referenced by canUseDb().

DbEngine::hasTable ( $tablename )

abstract

returns whether the table exists; must be implemented by driver

Referenced by canUseDb(), restoreData(), and upgradeDb().

DbEngine::insert	(		$table,
		array	$values
	)

abstract

insert values into a table; returns false on failure, the new primary key if a sequence was set, true otherwise; use sqlInsert to create the SQL statement!

Referenced by createDb(), setConfig(), and upgradeDb().

DbEngine::isConnected ( )

abstract

check whether the DB object is connected to an actual database

Referenced by canUseDb().

DbEngine::isNull ( $val )

returns whether the result value is NULL; the default interprets only the special value null as NULL

DbEngine::lastError ( )

abstract

returns the error string of the last operation

Referenced by createDb(), and upgradeDb().

DbEngine::lockDB ( $writelock )

protected

locks the database - only used by the backup functions; if necessary should also start a transaction; default just starts a transaction

References beginTransaction().

Referenced by dumpBackup(), and restoreData().

DbEngine::needVersion ( )

returns the version of the DB layout that is required by this version of Magic Smoke

References WobSchemaBase\version().

Referenced by canUseDb(), and upgradeDb().

DbEngine::restoreData	(	$file,
		$overwrite
	)

called from admin.php: restore a backup

References hasTable(), lockDB(), syncSequences(), and unlockDB().

DbEngine::rollbackTransaction ( )

abstract

ends a transaction with a rollback; must be implemented by driver; returns true on success; use sqlRollbackTransaction to create the SQL statement!

Referenced by createDb(), and upgradeDb().

DbEngine::select	(	$table,
		$cols,
		$where = `""`,
		$orderby = `""`
	)

abstract

gets some data from the database; $table is the name of the table, $cols is the list of columns to return or "*" for all, $where is the where clause of the SQL-statement, $orderby may contain additional ORDER BY or GROUP BY clauses; returns array of rows, which are in *_fetch_array format; returns false on error; use sqlSelect to create the SQL statement!; make sure that NULL values are returned as PHP value null (most DB drivers already do this)

Referenced by dumpBackup(), exploreBackup(), getConfig(), and setConfig().

DbEngine::setAdminPassCode	(	$u,
		$p
	)

set the admin passcode; used by the config.php file if admin access is allowed

DbEngine::setConfig	(	$key,
		$val
	)

sets a config setting

References beginTransaction(), commitTransaction(), WobSchemaBase\configKeyColumn(), WobSchemaBase\configTable(), WobSchemaBase\configValueColumn(), escapeString(), insert(), select(), and update().

DbEngine::setTransactionUpdating ( $tm )

set the transaction mode: true if it is an updating transaction

DbEngine::showCreateDb ( )

shows how the database would be created, used by admin.php only!!

References $i, sqlBeginTransaction(), sqlCommitTransaction(), sqlCreateTable(), sqlInsert(), WobSchemaBase\tableDefaults(), WobSchemaBase\tableDefinition(), and WobSchemaBase\tableNames().

DbEngine::sqlBeginTransaction ( )

returns the SQL92 statement for beginning a transaction; overwrite this to implement DB specific syntax

Referenced by showCreateDb().

DbEngine::sqlCommitTransaction ( )

returns the SQL92 statement for committing a transaction; overwrite this to implement DB specific syntax

Referenced by showCreateDb().

DbEngine::sqlCreateColumn	(	$tablename,
		$columnname,
		$columndef,
		$flags = `self::COLUMN_CREATE_ALL`
	)

protected

creates SQL92 part of a statement for creating a single column

References $i, dataType(), sqlCreateTablePrimaryKey(), and sqlCreateTableUniqueConstraint().

Referenced by sqlCreateTable(), MysqlEngine\upgradeTable(), and PGsqlEngine\upgradeTable().

DbEngine::sqlCreateTable	(	$tablename,
		$table
	)

protected

creates a SQL92 statement for creating a table; overwrite this to implement DB specific syntax

References $col, createTableExtras(), WobTransactionBase\debug(), WobTransactionBase\DebugDbStatement, and sqlCreateColumn().

Referenced by createDb(), showCreateDb(), and upgradeDb().

DbEngine::sqlCreateTablePrimaryKey ( array $cols )

protected

creates primary key statement for sqlCreateTable; overwrite this to implement DB specific syntax

References $i.

Referenced by sqlCreateColumn().

DbEngine::sqlCreateTableUniqueConstraint ( array $constraints )

protected

creates the complex unique constraints; overwrite this to implement DB specific syntax

References $i.

Referenced by sqlCreateColumn().

DbEngine::sqlDelete	(	$table,
		$where
	)

protected

creates a SQL92 statement for deletes; overwrite this to implement DB specific syntax

References WobTransactionBase\debug(), and WobTransactionBase\DebugDbStatement.

Referenced by MysqlEngine\deleteRows(), and PGsqlEngine\deleteRows().

DbEngine::sqlInsert	(		$table,
		array	$values
	)

protected

creates a SQL92 statement for inserts; overwrite this to implement DB specific syntax

References WobTransactionBase\debug(), WobTransactionBase\DebugDbStatement, escapeBlob(), escapeBool(), escapeInt(), escapeString(), WobSchemaBase\isBlobColumn(), WobSchemaBase\isBoolColumn(), WobSchemaBase\isIntColumn(), WobSchemaBase\isStringColumn(), and WobSchemaBase\tableHasColumn().

Referenced by MysqlEngine\insert(), PGsqlEngine\insert(), showCreateDb(), and upgradeDb().

DbEngine::sqlRollbackTransaction ( )

returns the SQL92 statement for rolling a transaction back; overwrite this to implement DB specific syntax

DbEngine::sqlSelect	(	$table,
		$cols,
		$where,
		$orderby
	)

creates a SQL92 statement for selects; overwrite this to implement DB specific syntax; the concrete DB implementation should append "for update" to the select statement if $this->transmode is true and the DB supports it

References WobTransactionBase\debug(), and WobTransactionBase\DebugDbStatement.

Referenced by PGsqlEngine\select(), and MysqlEngine\select().