DBobject
Objectify and automate database access.
Typically used as a superclass. We're using the “_db” prefix in the local namespace to clearly see what is done by DBobject and what is done by the extending classes that will use it as a base.
It was decided that the class should not discover table columns, primary keys and auto_increment attributes automatically, to keep runtime more efficient. It also paves the way for future automated table creation.
WARNING
Development has stopped, as this superclass uses PHP's MySQL API. I am using PDO now, which solves most of the per-row handling this used to take care of. I'll eventually create a new PDO class for the paging aspect.
Example
// Minimalist subclass example. It expects to represent a single row
// in its lifespan.
class MyTable extends DBobject {
function MyTable($id) {
$this->DBobject(
'user',
'pass',
'dbase',
'MyTable',
false,
array('id' => 0, 'ColumnTwo' => 'default2', 'ColumnThree' => 'default3'),
array('id'),
null,
20
);
$sid = mysql_real_escape_string($id);
$this->_dbFetchRecord(array(
'where' => "id = '$sid'"
));
}
function DESTROY() {
$this->_dbDestroy();
}
function Save() {
return $this->_dbCommitRecord('replace');
}
}
// Now let's use our new subclass!
$foo = new MyTable(34);
// I can safely access columns as properties of MyTable:
echo $foo->ColumnTwo;
$foo->ColumnThree = "bar";
$foo->Save();
TODO
- Replace _dbSetColumns() with overloading.
- Cache _dbFetchRecord() in $_DBOBJECTS as $where => array($columns).
- Data access on Page should be the same, so an array of DBobject not data direct. (Perhaps DBobject extends Enumeration?)
- Ask for CREATE TABLE and extract our 3 variables from that.
Summary
- Methods
- DBobject Create an instance of the DBobject class.
- _dbDestroy Eliminate this instance of the DBobject class.
- DESTROY Equivalent to _dbDestroy().
- _dbEscape Escape string for use in a value inside a query string.
- _dbTableExists Verify our table's existence.
- _dbError Get next error message from this instance's stack.
- _dbSetColumns Set columns in _dbcolumns safely.
- _dbFetchRecord Fetch a single record.
- _dbFetchPage Fetch a series of records.
- _dbCommitRecord Inserts, updates or deletes a row in the table.
- _dbCount Count how many results a query would yield.
Methods
DBobject
function DBobject($dbuser, $dbpass, $dbname, $dbtable, $dbconn, $dbcolumns, $dbpkeys, $dbautoinc = null, $dbrows_per_page = 0)
Create an instance of the DBobject class.
You will most likely want to create your own constructor if you're using DBobject as a superclass, and start it by calling this function so that you have sane defaults to start with. Note that a database connection is not yet opened at this stage, we only set defaults for every property of the class. Database connection will be established if necessary when a first I/O method will get called.
Parameters
- dbuser
- Username for database server authentication.
- dbpass
- Password for database server authentication.
- dbname
- Name of database.
- dbtable
- Name of table.
- dbconn
- Resource of an existing database connection to use. (False if you have none.)
- dbcolumns
- Array of column names as keys, with default values.
- dbpkeys
- Array of column names forming the primary key.
- dbautoinc
- Name of column which is auto_increment. (Optional. Null if you have none.)
- dbrows_per_page
- How many rows are in a page. (Optional. Default: no pages.)
_dbDestroy
function _dbDestroy()
Eliminate this instance of the DBobject class. Connection to MySQL will be closed only if it was opened by this instance.
DESTROY
function DESTROY()
Equivalent to _dbDestroy(). Since DESTROY() is likely to be defined in subclasses, in this class all the real work is actually done by _dbDestroy().
_dbEscape
function _dbEscape($string)
Escape string for use in a value inside a query string.
Parameters
- string
- String to escape.
Returns
Input string escaped with the current database engine.
_dbTableExists
function _dbTableExists()
Verify our table's existence.
Returns
True if our table exists, false otherwise.
_dbError
function _dbError()
Get next error message from this instance's stack. More than one error message may be pending, so you may need to call this method in a loop.
Returns
A string containing the most recent error message, or NULL if none is left.
_dbSetColumns
function _dbSetColumns($array)
Set columns in _dbcolumns safely. Only keys present in _dbcolumns get their values updated, other keys found in the supplied array are safely ignored.
Parameters
- array
- Array of column names and their new values.
Returns
The number of _dbcolumns items that have been updated.
_dbFetchRecord
function _dbFetchRecord($args)
Fetch a single record. Any _dbcolumns keys which are found in the resulting data will have their values updated, others will remain unchanged. If you're renaming columns in your “select” or using multiple tables in your “from” however, you need to use the returned array in order to access all of your resulting data.
Parameters
- args
- Array of arguments to build _dbquery with. In this method, it only makes sense to define: where, group, having. One can also override the defaults for: select, from.
Returns
The resulting array if successful, false otherwise.
See Also
_dbFetchPage
function _dbFetchPage($args = false, $page = 1)
Fetch a series of records.
Parameters
- args
- Array of arguments to build _dbquery with. If you don't set “limit” here, pagination will work for you. Leave unset if you've already defined the current query in a previous call.
- page
- Current page number. Leave unset if you aren't using pagination. As per _dbrows_per_page, pagination is off by default.
Returns
Two-dimensional array with each row of results if successful, false otherwise or if no results were produced.
See Also
_dbCommitRecord
function _dbCommitRecord($mode = 'insert')
Inserts, updates or deletes a row in the table. Precede with a call to _dbSetColumns() to define/replace column contents. Columns listed in _dbpkeys must all be defined for this to succeed as they are used to uniquely identify the record to process.
Note that for updates you should call _dbFetchRecord() prior to _dbSetColumns() if you want to be absolutely certain of the result in the database. Failure to do so may write unexepcted previous contents of _dbcolumns along with your data.
Parameters
- mode
- One of: insert, replace, update, delete.
Returns
True if successful, false otherwise.
_dbCount
function _dbCount($args = false)
Count how many results a query would yield.
Parameters
- args
- Array of arguments to build _dbquery with. Leave unset if you've already defined the current query in a previous call.
Returns
The number of results, or -1 if an error occured.