Summary: Field | Method | Constr Detail: Field | Method | Constr

org.zenmagick.database.ZMDatabase

Interface ZMDatabase

ZMDatabase

public interface ZMDatabase

ZenMagick database abstractation.

A generic, lightweight database layer.

As a convention, implementation classes must support an array as single constructor argument. This array (or map) will contain the connection details.

Support for the following array keys is required:

driver: The database type; typical values would be: mysql, sqlite or pgsql.
host: The database host (and port).
port: The database port.
username: The database username.
password: The password for the database user.
database: The name of the database to connect to.

The data will be bound to the SQL using the configured table mappings.

It is also possible to generate table mappings on the fly. In that case no name translation will be done.

Syntax for parameters in SQL is: :{[0-9]+#}[propertyName]. The numeric prefix (for example :3#categoryId) is optional and only required if multiple values of a column are used in a single SQL statement.

Author:: DerManoMann
Version:: $Id: ZMDatabase.php 2186 2009-04-29 03:42:53Z dermanomann $

Field Summary
final mixed	DATETIME_FORMAT Internal date-time format.
final mixed	DATE_FORMAT Internal date format.
final mixed	MODEL_RAW If used as modelClass parameter, the raw SQL data will be returned (no mapping, etc).
final mixed	NULL_DATE NULL date.
final mixed	NULL_DATETIME NULL datetime.

Method Summary
void	beginTransaction() Start a transaction.
void	commit() Commits statements in a transaction.
mixed	createModel(string table, mixed model, mixed mapping) Create a single row using the given model and mapping.
array	getConfig() Get the configuration settings for this instance.
array	getMetaData(string table) Get meta data.
mixed	getResource() Get the underlying, implementation specific resource used to access the database.
array	getStats() Get some stats about database usage.
mixed	loadModel(string table, mixed key, string modelClass, mixed mapping) Load a single row using the given model and mapping.
array	query(string sql, array args, string modelClass, mixed mapping) Execute a query.
mixed	querySingle(string sql, array args, string modelClass, mixed mapping) Execute a query expecting a single result.
void	removeModel(string table, mixed model, mixed mapping) Remove a single row using the given model and mapping.
void	rollback() Rollback changes in a transaction.
int	update(string sql, mixed data, mixed mapping) Update using the provided SQL and data and model.
void	updateModel(string table, mixed model, mixed mapping) Update a single row using the given model and mapping.

Field Detail

DATETIME_FORMAT

public final mixed DATETIME_FORMAT = 'Y-m-d H:i:s'

Internal date-time format. */

DATE_FORMAT

public final mixed DATE_FORMAT = 'Y-m-d'

Internal date format. */

MODEL_RAW

public final mixed MODEL_RAW = '@raw'

If used as modelClass parameter, the raw SQL data will be returned (no mapping, etc). */

NULL_DATE

public final mixed NULL_DATE = '0001-01-01'

NULL date. */

NULL_DATETIME

public final mixed NULL_DATETIME = '0001-01-01 00:00:00'

NULL datetime. */

Method Detail

beginTransaction

public void beginTransaction()

Start a transaction.

If the database provider (and database driver) allow, nested transaction are possible.

Throws:: ZMDatabaseException

commit

public void commit()

Commits statements in a transaction.

Throws:: ZMDatabaseException

createModel

public mixed createModel(string table, mixed model, mixed mapping)

Create a single row using the given model and mapping.

Parameters:: table - The table to update.; model - The model instance.; mapping - The field mappings; default is null.
Returns:: The model with the updated primary key.
Throws:: ZMDatabaseException

getConfig

public array getConfig()

Get the configuration settings for this instance.

Returns:: Configuration settings as set via the constructor.

getMetaData

public array getMetaData(string table)

Get meta data.

Meta data is available for either the current database or, if specified, an individual table.

The following table information will be returned:

type: The data type. This will be a data type as supported by the ZMDatabase API.
name: The (case sensitive) column name.
key: A boolean indicating a primary key
autoIncrement: A boolean flag indication an auto increment column
maxLen: The max. field length; this value is context specific.

Parameters:: table - Optional table; if no table is provided, database meta data will be returned; * default is null.
Returns:: Context dependent meta data.
Throws:: ZMDatabaseException

getResource

public mixed getResource()

Get the underlying, implementation specific resource used to access the database.

Returns:: The (native) database handle, etc.

getStats

public array getStats()

Get some stats about database usage.

Returns:: A map with statistical data.

loadModel

public mixed loadModel(string table, mixed key, string modelClass, mixed mapping)

Load a single row using the given model and mapping.

Parameters:: table - The table to update.; key - The primary key.; modelClass - The class name to be used to build result obects; default is null.; mapping - The field mappings; default is null.
Returns:: The model with the updated primary key.
Throws:: ZMDatabaseException

query

public array query(string sql, array args, string modelClass, mixed mapping)

Execute a query.

If $resultClass is null, the returned list will contain a map of columns => value for each selected row.

$modelClass may be set to the magic value of ZMDatabase::MODEL_RAW to force returning the raw data without applying any mappings or conversions.

Parameters:: sql - The query.; args - Optional query args; default is an empty array.; mapping - The field mappings or table name (list); default is null.; modelClass - The class name to be used to build result obects; default is null.
Returns:: List of populated objects of class $resultClass or map if modelClass is null.
Throws:: ZMDatabaseException

querySingle

public mixed querySingle(string sql, array args, string modelClass, mixed mapping)

Execute a query expecting a single result.

$modelClass may be set to the magic value of ZMDatabase::MODEL_RAW to force returning the raw data without applying any mappings or conversions.

Parameters:: sql - The query.; args - Optional query args; default is an empty array.; mapping - The field mappings or table name (list); default is null.; modelClass - The class name to be used to build result obects; default is null.
Returns:: The (expected) single result or null
Throws:: ZMDatabaseException

removeModel

public void removeModel(string table, mixed model, mixed mapping)

Remove a single row using the given model and mapping.

Parameters:: table - The table to update.; model - The model instance.; mapping - The field mappings; default is null.
Throws:: ZMDatabaseException

rollback

public void rollback()

Rollback changes in a transaction.

Throws:: ZMDatabaseException

update

public int update(string sql, mixed data, mixed mapping)

Update using the provided SQL and data and model.

Parameters:: sql - The update sql.; data - A model instance or array; default is an empty array.; mapping - The field mappings or table name (list); default is null.
Returns:: The number of affected rows.
Throws:: ZMDatabaseException

updateModel

public void updateModel(string table, mixed model, mixed mapping)

Update a single row using the given model and mapping.

Parameters:: table - The table to update.; model - The model instance.; mapping - The field mappings; default is null.
Throws:: ZMDatabaseException

Frames No frames