DBI2 Class Reference

Database access class. More...

Inheritance diagram for DBI2:

List of all members.

Public Member Functions

__construct ($name, $db_host, $db_name, $db_user, $db_pass)

Creates a new DBI2 object.

addTransactionCallback ($cb)

Adds function to list of callbacks to call when transaction is complete.

cancelTransaction ()

Cancels a transaction.

clearErrors ()

INSERT BRIEF DESCRIPTION HERE.

commitTransaction ()

Commits a transaction.

createTransaction ($nest=false)

Creates a DBTransaction object.

delete ($table, $constraints=false)

Runs a DELETE query on the database.

getDB ()

INSERT BRIEF DESCRIPTION HERE.

getDefaultOperator ()

Retrieves current default equality operator.

getFieldName ()

INSERT BRIEF DESCRIPTION HERE.

getQuery ()

INSERT BRIEF DESCRIPTION HERE.

getResult ($a= '')

INSERT BRIEF DESCRIPTION HERE.

insert ($into, $what)

Runs an INSERT statement on the database.

inTransaction ()

Returns the depth of transaction nesting.

mysql_insert_id ()

INSERT BRIEF DESCRIPTION HERE.

query ($string)

Performs a query and returns a result set or status.

select ($from, $what=self::NUM_RESULTS, $constraints=array(), $limit=array(), $order=array(), $extraJoins= '', $groupBy= '')

Runs a SELECT query on the database.

setDefaultOperator ($op)

Changes current default equality operator.

setResult ($a, $b)

INSERT BRIEF DESCRIPTION HERE.

setValidAttributes ($table, $attributes)

Sets which attributes are considered valid for queries.

startTransaction ($callback=null)

Initiates a MySQL transaction.

update ($table, $what, $constraints=false)

Runs an UPDATE statement on the database.

Static Public Member Functions

static cleanup ()

INSERT BRIEF DESCRIPTION HERE.

static formatTimestamp ($dbTimestamp, $formatString)

Reformats database timestamp using strftime() format strings.

static getDBI ($name)

Retrieves DBI2 object by name.

Public Attributes

const FORMAT_DATE_DB

Date only: "2009-01-05".

const FORMAT_NICE_DATE

Date only: "Tuesday, January 5th, 2009".

const FORMAT_NICE_DATE_ABBR

Date only: "January 5th, 2009".

const FORMAT_NICE_DATETIME

Date and time: "5:15 PM, Tuesday, January 5th, 2009".

const FORMAT_NICE_TIME

Time only: "5:15 PM".

const FORMAT_SHORT_DATE

Date only: "1/5/2009".

Detailed Description

Database access class.

Each DBI2 instance contains a connection to a particular database, which cannot be changed over the lifetime of a DBI2 object. The connection is made lazily, so that if no queries are ever made, the connection is never made either (THIS MAY CHANGE). The class contains methods for making queries to the database and handling transactions. It is intended to be used by SModel2 objects, but has a general enough interface that it can easily be used directly if the need arises. For those coming from the original DBI2, please take note of the differences between DBI2 and DBI2:

Query results are returned in a DBResult object instead of a giant array
There are now specialized query methods, such as select() and insert()
Transaction support has been added; use it when multiple INSERT/UPDATE/DELETE queries must be made as part of a single logical operation
More error checking...

Constructor & Destructor Documentation

DBI2::__construct	(	$	name,
		$	db_host,
		$	db_name,
		$	db_user,
		$	db_pass
	)

Creates a new DBI2 object.

Use this method to create a new DBI2 object. The DBI2 object will be registered according to the name given as the first parameter and can be retrieved by the name using the getDBI2() function. You should probably create new DBI2 objects in your standardIncludes.php5.

Parameters:

	$name	[string]: name of database connection (used to identify DBI2 object)
	$db_host	[string]: server database is hosted on
	$db_name	[string]: name of database on server
	$db_user	[string]: username of user to connect to DB with
	$db_pass	[string]: password for $db_user

Member Function Documentation

DBI2::addTransactionCallback ( $ cb )

Adds function to list of callbacks to call when transaction is complete.

See startTransaction() for more on how the callbacks work

Parameters:

$cb

[callback]: callback function

DBI2::cancelTransaction ( )

Cancels a transaction.

This method can be called in place of commitTransaction() to indicate that the changes made during the transaction should NOT be applied to the database. Unlike commitTransaction(), this method immediately cancels the transaction, even if it is a nested transaction. Subsequent calls to cancelTransaction() will have no effect. The nesting counter for transaction is also set to zero so that a new transaction could be started immediately (although not recommended in the case of nested transactions since outside code might assume that it is still the same transaction).

In general, make sure that no additional database modifying queries follow a cancelTransaction() call that should be part of the transaction. This can be managed with proper return codes and the like, so that calling code doesn't inadvertently continue thinking that a transaction is still ongoing. Calling code can also call inTransaction() to find out if it is still inside a transaction or not. It is also a good idea not to cancel a transaction unless it really is not to continue at all. Calling code should also be aware of this.

Returns:: [boolean]: true if cancellation was successful, false otherwise.

static DBI2::cleanup ( ) [static]

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

DBI2::clearErrors ( )

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

DBI2::commitTransaction ( )

Commits a transaction.

This method should be called after calling startTransaction() and performing any number of queries that should be in that single transaction. This method causes all changes made in the database during that transaction to actually be applied to the database.

If this is called inside a nested transaction (i.e., startTransaction() was called multiple times), then this method has no effect other than to decrement the transaction nesting count. Only the final matching call to commitTransaction() will result in an actual commit.

Returns:: [boolean]: true if commit was successful or if called from within nested transaction, false if commit failed, or called outside of a transaction

DBI2::createTransaction ( $ nest = false )

Creates a DBTransaction object.

Using a DBTransaction object instead of startTransaction() and friends makes nested transactions unnecessary. Just pass the transaction object around call commit() or cancel() on it when finished. See the documentation for DBTransaction for more. Note that if you create a transaction object for this DBI when it is already inside a nested transaction, the transaction object will also be nested. Also, starting a transaction using startTransction() after a transaction object has been created will result in a nested transaction condition. Thus, it is best not to mix the two mechanisms unless you are clear on the semantics. One last note: there can be only one transaction object per DBI. If you call createTransaction() multiple times, you will get the same transaction object back and it will NOT increase the nesting level unless the $nest parameter is true. Again, be careful with this.

Parameters:

$nest

[boolean]: whether to increase the nesting level during this call

Returns:: [DBTransaction]: new transaction object that uses this database

DBI2::delete	(	$	table,
		$	constraints = `false`
	)

Runs a DELETE query on the database.

This method runs a simple DELETE query of the form 'DELETE FROM table WHERE ...'. You must either provide constraints, or provide true as the value for the constraints parameter. This is to prevent accidentally deletion of an entire table's worth of data.

Parameters:

	$table	[string]: which table to delete from
	$constraints	[array]: array of constraints, or true to delete all rows

Returns:: [boolean]: success or failure

static DBI2::formatTimestamp	(	$	dbTimestamp,
		$	formatString
	)			`[static]`

Reformats database timestamp using strftime() format strings.

You can also use a few predefined constants (DBI2::FORMAT_*) to avoid having to construct a format string yourself. This method is little more than a wrapper around strftime(), but it makes the process clearer.

Parameters:

	$dbTimestamp	[string]: raw timestamp value from the database
	$formatString	[string]: strftime()-compatible string describing output format

Returns:: [string]: reformatted time string

DBI2::getDB ( )

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

static DBI2::getDBI ( $ name ) [static]

Retrieves DBI2 object by name.

Parameters:

$name

[string]: name of DBI2, as was given in the create() method

Returns:: [DBI2]: DBI2 object associated with $name or null if no such DBI2 object exists

DBI2::getDefaultOperator ( )

Retrieves current default equality operator.

This operator is used as the default operator in constraint arrays. By default, it will be "=", but it can be changed to something else by either setting the 'dbi2.defaultOperator' SConfig option or calling DBI2::setDefaultOperator().

This method can be called as an object method or a static method. In the former case, it sets the default just for the DBI it was called on. Otherwise, it sets the default for all DBIs. When any particular DBI is checking for the default operator, it first checks to see if the particular DBI object has a default set, and if not, it looks at the global (static) setting before finally turning to SConfig.

Returns:: [string]: default constraint operator

DBI2::getFieldName ( )

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

DBI2::getQuery ( )

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

DBI2::getResult ( $ a = '' )

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Parameters:

$a

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

DBI2::insert	(	$	into,
		$	what
	)

Runs an INSERT statement on the database.

This method only builds the normal INSERT statement (e.g., "INSERT INTO foo (a,b,c) VALUES (x,y,z)") and not anything radical, such as INSERT statements that include subselects and ON DUPLICATE KEY clauses. For those, use the query() method.

Parameters:

	$into	[string]: table to insert into
	$what	[array]: associative array of values to insert, keyed by attribute name.

Returns:: [int]: insert ID for new insert, or false on failure

DBI2::inTransaction ( )

Returns the depth of transaction nesting.

This method can be used to determine if a transaction is in progress, and also how deeply it is nested.

Returns:: [int]: the depth of the transaction nesting (zero if no transaction is ongoing)

DBI2::mysql_insert_id ( )

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

DBI2::query ( $ string )

Performs a query and returns a result set or status.

This method takes a query string, performs it on the database and depending on the type of query, returns a DBResult object, or a simple boolean status. The query is not chacked for validity or processed in any way.

Parameters:

$string

[string]: query string

Returns:: [DBResult]: DBResult representing results of query (or simply to indicate that the query succeeded if the query was not a SELECT query); null if there was an error

DBI2::select	(	$	from,
		$	what = `self::NUM_RESULTS`,
		$	constraints = `array()`,
		$	limit = `array()`,
		$	order = `array()`,
		$	extraJoins = `''`,
		$	groupBy = `''`
	)

Runs a SELECT query on the database.

This method constructs a SELECT query from the parameters given, possibly with constraint checking. For a general SELECT query that may, for example, have joins, use the generic query() method.

Parameters:

	$from	[string]: table to select results from
	$what	[const]: list of attributes to select or DBI2::NUM_RESULTS (return the number of results selected by the query).
	$constraints	[array]: specify constraints for WHERE clause, using nested array
	$limit	[mixed]: specify how many results to return
	$order	[mixed]: specify the order of the results returned

Returns:: [DBResult]: object representing results, or an integer if $what == DBI2::NUM_RESULTS, or null on failure

DBI2::setDefaultOperator ( $ op )

Changes current default equality operator.

See getDefaultOperator() for more. This method can also be called as an object method or a static method.

Parameters:

$op

[string]: new default operator

Returns:: [string]: old default operator

DBI2::setResult	(	$	a,
		$	b
	)

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Parameters:

	$a	[TYPE]: DESCRIPTION
	$b	[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

DBI2::setValidAttributes	(	$	table,
		$	attributes
	)

Sets which attributes are considered valid for queries.

Valid attributes are used by the constraint, order ahd limit builder functions to make sure that the query is correct before sending it to the server. There is a set of valid attributes for each table in the database. If no valid attributes are set for a given table, then attribute checking is disabled. This may be useful if queries use aliases or joins. There is a performance loss if attribute checking is enabled.

Parameters:

	$table	[string]: name of table that we are setting the valid attributes for
	$attributes	[array]: list of attributes that are valid for the given table

DBI2::startTransaction ( $ callback = null )

Initiates a MySQL transaction.

When a transaction has been started, all new queries will not be applied to the database until the transaction is committed (see commitTransaction()). If something goes wrong or the transaction should not be completed, then it can be cancelled (see cancelTransaction()).

If a transaction is started and this method is called again after that, no new transaction is started, but a count is kept of how deep the nesting of transaction calls is. By this mechanism, only the last call to commitTransaction() actually commits the transaction. This makes it easy to have code that uses transactions call other code that also uses transactions, but doesn't know that the calling code makes use of transactions. Each chunk of code can start and commit transactions without having to worry about whether it is stomping on the code of a caller. Note, however, that this means that all the subtransactions are munged into one giant transaction. So the following code will not behave as intended when called from within an already started transaction:

 $dbi->startTransaction();
 $dbi->query(...);
 $dbi->query(...);
 $dbi->commitTransaction();

 $dbi->startTransaction();
 $dbi->query(...);
 $dbi->query(...);
 $dbi->commitTransaction();

Normally, this could would result in two transactions being committed independently of each other. If it is called, however, by code that has already started a transaction, then the two transactions will be subsumed into the parent transaction, so there will only be one transaction in the end. This case should be rare, but it is worth noting.

If a transaction is started, but due to a bug in the code, or the script crashing, there is no followup call to commitTransaction() or cancelTransaction(), DBI will automatically make sure that the transaction is cancelled so that the database connection does not become "locked" and unable to service any more queries.

You can optionally provide a callback that will be called when the transaction is committed or cancelled. It will not be called on any call to commitTransaction() or cancelTransaction(), but only on those calls that actually result in a database COMMIT or ROLLBACK query to be executed (i.e., not when nested). These callbacks are not guaranteed to be called in any particular order, although the current implementation has them called in the order they are added. Because calling code can start transactions and thus add callbacks before your code gets a chance, you should not expect your callback to ever be the first or last in the chain. Callbacks will not be called on page cleanup (that is, if a transaction was left dangling and had to be cancelled via a shutdown function).

Parameters:

$callback

[callback]: function to be called when transaction is committed or canceled

Returns:: [boolean]: whether the transaction was able to successfully begin

DBI2::update	(	$	table,
		$	what,
		$	constraints = `false`
	)

Runs an UPDATE statement on the database.

This method builds an UPDATE statement of the form 'UPDATE foo SET a='foo',b='bar' WHERE ...' and executes it. You are required to indicate something for constraints. If you pass in true, then the UPDATE query will run on all rows in the table. Otherwise, you must pass in a constraints array, as is used in other methods, such as select(). This is to prevent accidental UPDATEs that affect the entire table when only a single row was intended.

Parameters:

	$table	[string]: which table to update
	$what	[array]: associative array of attributes their new values to update (attribute => value)
	$constraints	[array]: constraints on which rows to update, or true to update all rows

Returns:: [boolean]: success or failure

The documentation for this class was generated from the following file:

content/DBI2.php5


Public Member Functions
	__construct ($name, $db_host, $db_name, $db_user, $db_pass)
	Creates a new DBI2 object.
	addTransactionCallback ($cb)
	Adds function to list of callbacks to call when transaction is complete.
	cancelTransaction ()
	Cancels a transaction.
	clearErrors ()
	INSERT BRIEF DESCRIPTION HERE.
	commitTransaction ()
	Commits a transaction.
	createTransaction ($nest=false)
	Creates a DBTransaction object.
	delete ($table, $constraints=false)
	Runs a DELETE query on the database.
	getDB ()
	INSERT BRIEF DESCRIPTION HERE.
	getDefaultOperator ()
	Retrieves current default equality operator.
	getFieldName ()
	INSERT BRIEF DESCRIPTION HERE.
	getQuery ()
	INSERT BRIEF DESCRIPTION HERE.
	getResult ($a= '')
	INSERT BRIEF DESCRIPTION HERE.
	insert ($into, $what)
	Runs an INSERT statement on the database.
	inTransaction ()
	Returns the depth of transaction nesting.
	mysql_insert_id ()
	INSERT BRIEF DESCRIPTION HERE.
	query ($string)
	Performs a query and returns a result set or status.
	select ($from, $what=self::NUM_RESULTS, $constraints=array(), $limit=array(), $order=array(), $extraJoins= '', $groupBy= '')
	Runs a SELECT query on the database.
	setDefaultOperator ($op)
	Changes current default equality operator.
	setResult ($a, $b)
	INSERT BRIEF DESCRIPTION HERE.
	setValidAttributes ($table, $attributes)
	Sets which attributes are considered valid for queries.
	startTransaction ($callback=null)
	Initiates a MySQL transaction.
	update ($table, $what, $constraints=false)
	Runs an UPDATE statement on the database.
Static Public Member Functions
static	cleanup ()
	INSERT BRIEF DESCRIPTION HERE.
static	formatTimestamp ($dbTimestamp, $formatString)
	Reformats database timestamp using strftime() format strings.
static	getDBI ($name)
	Retrieves DBI2 object by name.
Public Attributes
const	FORMAT_DATE_DB
	Date only: "2009-01-05".
const	FORMAT_NICE_DATE
	Date only: "Tuesday, January 5th, 2009".
const	FORMAT_NICE_DATE_ABBR
	Date only: "January 5th, 2009".
const	FORMAT_NICE_DATETIME
	Date and time: "5:15 PM, Tuesday, January 5th, 2009".
const	FORMAT_NICE_TIME
	Time only: "5:15 PM".
const	FORMAT_SHORT_DATE
	Date only: "1/5/2009".