AnewtAutoRecord Class Reference

Automatic database record object. More...

List of all members.

Public Member Functions

Instance Methods

db_save ()

Save a record in the database.

db_insert ()

Insert the data as a new record in the database.

db_update ()

Update an existing record in the database.

db_delete ()

Delete this record from the database.

Static Public Member Functions

Autorecord Registration

static register ($class)

Register a class as an AnewtAutoRecord.

Database Methods

static db_connection ()

Obtain a database connection.

static db_table ()

Return the name of the table to use.

static db_columns ()

Return an associative array of column name to column type mappings.

static db_columns_skip_on_save ()

Return an array of column names which are read-only and should never be written.

static db_columns_skip_on_insert ()

Return an array of column names which should be skipped on insert queries when no values are given.

static db_columns_skip_on_update ()

Return an array of column names which should be skipped on update queries.

static db_columns_order_by ()

Return an associative array with sort columns and sort orders.

static db_primary_key_column ()

Return the name of the primary key.

static db_primary_key_sequence ()

Return the name of the sequence used for the primary key (PostgreSQL only).

static db_sql_select ($table_alias=null)

Return a SQL SELECT clause.

static db_sql_from ($table_alias=null)

Return a SQL FROM clause.

static db_sql_order_by ($table_alias=null)

Return a SQL ORDER BY clause.

static _db_sql_select ($class, $table_alias=null, $connection)

Return a SQL SELECT clause.

static _db_sql_from ($class, $table_alias=null, $connection)

Return a SQL FROM clause.

static _db_sql_order_by ($class, $table_alias=null, $connection)

Return a SQL ORDER BY clause.

Record Finding Methods

Note: These methods only have signatures, so that they can be documented. The actual implementation is done using magic in the register() method.

static db_find_all ()

Find all records in the database table.

static db_find_all_by_id ($values=array())

Find records by id.

static db_find_one_by_id ($value)

Find a single record by primary key value.

static db_find_all_by_sql ($sql=null, $values=array())

Find records by providing SQL contraints.

static db_find_one_by_sql ($sql=null, $values=array())

Find a single record by providing SQL contraints.

static db_find_all_by_column ($column, $value)

Find records by column value.

static db_find_one_by_column ($column, $value)

Find a single record by column value.

static _db_find_by_id ($class, $just_one_result, $values, $connection)

Find one or more records by primary key value.

static _db_find_by_sql ($class, $just_one_result=false, $sql=null, $values=array(), $connection)

Find one or more records by providing a part of the SQL query.

static _db_find_by_column ($class, $just_one_result, $column, $value, $connection)

Find one or more records by one column value.

Helper Methods

static array_by_column_value ($instances, $column, $unique)

Group AnewtAutoRecord instances by the value of a column.

static array_by_primary_key_value ($instances)

Convert a list of AnewtAutoRecord instances to an associative array indexed by primary key.

static db_object_from_array ($arr)

Create instance from array.

static db_objects_from_arrays ($arrs)

Create instances from arrays.

static _db_object_from_array ($class, $row)

Converts a result row into an object instance.

static _db_objects_from_arrays ($class, $rows)

Convert result rows into object instances.

Detailed Description

Automatic database record object.

AnewtAutoRecord is an advanced database wrapper class implementing the active record pattern. Each class wraps a single database table, providing you with a convenient search API for querying and easy to use db_save(), db_insert() and db_delete() methods for object manipulation.

The query API consists of several static methods:

db_find_all() retrieves all records in the database
db_find_all_by_id() and db_find_one_by_id() return records based on the primary key value
db_find_all_by_sql() and db_find_one_by_sql() return records based on constraints expressed as SQL query parts.
db_find_all_by_column() and db_find_one_by_column() return records where a specified column has the specified value.

The data manipulation methods are instance methods that operate on object instances themselves:

db_save() saves the current record
db_insert() inserts a new record
db_update() updates an existing record
db_delete() deletes the current record

For more advance SQL query building, several methods can be used to build (part of) the query:

In order to create an AnewtAutoRecord subclass, you should name your own class MyClass_ (with a trailing underscore!), and override some of the methods (db_table() and db_columns() are obligatory). See the documentation on the methods below for more information. Right after your class definition, you should register your AnewtAutoRecord subclass so that the actual magic can be put into place:

AnewtAutoRecord::register('MyClass')

Now you can use the MyClass class. Example:

$my_instance = MyClass::db_find_one_by_id(12);

Definition at line 61 of file autorecord.lib.php.

Member Function Documentation

static AnewtAutoRecord::register ( $ class ) [static, final]

Register a class as an AnewtAutoRecord.

This does some evil voodoo magic to get things to work in a decent way. Your own class name should be called MyClass_ (with a trailing underscore) and should extend AnewtAutoRecord. After calling this method class MyClass will be dynamically generated with all the static methods in place.

Parameters:

$class

The name of the class to register as an active record class (without the trailing underscore)

Definition at line 80 of file autorecord.lib.php.

static AnewtAutoRecord::db_connection ( ) [static]

Obtain a database connection.

By default this returns the default database connection. Override this method if you want to use a custom database connection.

Returns:: An AnewtDatabaseConnection instance

See also:: AnewtDatabase::get_connection()
AnewtDatabaseConnection

Definition at line 222 of file autorecord.lib.php.

static AnewtAutoRecord::db_table ( ) [static]

Return the name of the table to use.

You must override this method for your own classes. Example: return 'person';

Returns:: An string with the table name to use

See also:: db_columns

Definition at line 238 of file autorecord.lib.php.

static AnewtAutoRecord::db_columns ( ) [static]

Return an associative array of column name to column type mappings.

You must override this method for your own classes. Example:

return array( 'id' => 'int', 'name' => 'str', 'age' => 'int' );

Returns:: An associative array mapping column names to column types

See also:

db_table

db_columns_skip_on_insert

db_columns_skip_on_update

db_columns_skip_on_save

AnewtDatabaseSQLTemplate::column_type_from_string()

Definition at line 266 of file autorecord.lib.php.

static AnewtAutoRecord::db_columns_skip_on_save ( ) [static]

Return an array of column names which are read-only and should never be written.

This is like db_columns_skip_on_insert() and db_columns_skip_on_update(), but is taken into account for both INSERT and UPDATE queries.

Definition at line 279 of file autorecord.lib.php.

static AnewtAutoRecord::db_columns_skip_on_insert ( ) [static]

Return an array of column names which should be skipped on insert queries when no values are given.

The database is expected to fill a default value for these columns.

Definition at line 290 of file autorecord.lib.php.

static AnewtAutoRecord::db_columns_skip_on_update ( ) [static]

Return an array of column names which should be skipped on update queries.

These are usually read-only values which don't need to get updated every time.

Definition at line 301 of file autorecord.lib.php.

static AnewtAutoRecord::db_columns_order_by ( ) [static]

Return an associative array with sort columns and sort orders.

These columns are used for sorting in the find methods when no explicit ORDER BY clause has been provided. The keys in the returned array must be column names, and the values must be one of the string literals ASC or DESC.

If not specified, no ORDER BY clause will be used by the standard find methods.

Example:

return array( 'name' => 'ASC', 'age' => 'DESC', );

See also:: db_find_all_by_sql
db_find_one_by_sql

Definition at line 329 of file autorecord.lib.php.

static AnewtAutoRecord::db_primary_key_column ( ) [static]

Return the name of the primary key.

Override this method if you don't want to use the default value id.

Returns:: The name of the primary key column

Definition at line 343 of file autorecord.lib.php.

static AnewtAutoRecord::db_primary_key_sequence ( ) [static]

Return the name of the sequence used for the primary key (PostgreSQL only).

Override this function if you're using a non-standard sequence for the primary key values of your table.

Returns:: The name of the sequence used for the primary key value

Definition at line 358 of file autorecord.lib.php.

static AnewtAutoRecord::db_sql_select ( $ table_alias = null ) [static]

Return a SQL SELECT clause.

Note that you cannot override this method.

Parameters:

$table_alias

Optional table alias name

Returns:: SELECT string

Definition at line 372 of file autorecord.lib.php.

static AnewtAutoRecord::db_sql_from ( $ table_alias = null ) [static]

Return a SQL FROM clause.

Note that you cannot override this method.

Parameters:

$table_alias

Optional table alias name

Returns:: FROM string

Definition at line 386 of file autorecord.lib.php.

static AnewtAutoRecord::db_sql_order_by ( $ table_alias = null ) [static]

Return a SQL ORDER BY clause.

By default the array returned by db_columns_order_by is used to build the ORDER BY clause, which suffices for most simple cases. Note that null is return if no columns where specified in db_columns_order_by.

You can override this method if you want more complex sorting by default. Make sure you honor the $table_alias argument if you do so (and make sure you escape it properly). Example:

return sprintf('SOME_FUNCTION(s.some_column) ASC', MyClass::db_connection()->escape_table_name($table_alias);

Parameters:

$table_alias

Optional table alias name

Returns:: ORDER BY string, or null

See also:: db_columns_order_by

Definition at line 411 of file autorecord.lib.php.

static AnewtAutoRecord::_db_sql_select	(	$	class,
		$	table_alias = `null`,
		$	connection
	)			`[static, final, protected]`

Return a SQL SELECT clause.

The SELECT keyword is not included.

Parameters:

	$class	Class name
	$table_alias	Optional table alias name
	$connection	AnewtDatabaseConnection instance

Returns:: String with comma-separated escaped column names. This string can be used directly (unescaped) in the SELECT part of an SQL query, i.e. using a ?raw? placeholder.

Definition at line 430 of file autorecord.lib.php.

static AnewtAutoRecord::_db_sql_from	(	$	class,
		$	table_alias = `null`,
		$	connection
	)			`[static, final, protected]`

Return a SQL FROM clause.

Parameters:

	$class	Class name
	$table_alias	Optional table alias name
	$connection	AnewtDatabaseConnection instance

Returns:: String with comma-separated escaped table names with join conditions. This string can be used directly (unescaped) in the FROM part of an SQL query.

Definition at line 467 of file autorecord.lib.php.

static AnewtAutoRecord::_db_sql_order_by	(	$	class,
		$	table_alias = `null`,
		$	connection
	)			`[static, final, protected]`

Return a SQL ORDER BY clause.

Parameters:

	$class	Class name
	$table_alias	Optional table alias name
	$connection	AnewtDatabaseConnection instance

Returns:: String with comma-separated escaped table names with join conditions. This string can be used directly (unescaped) in the FROM part of an SQL query.

Definition at line 500 of file autorecord.lib.php.

static AnewtAutoRecord::db_find_all ( ) [static]

Find all records in the database table.

Returns:: Array of AnewtAutoRecord instances (may be empty)

Definition at line 553 of file autorecord.lib.php.

static AnewtAutoRecord::db_find_all_by_id ( $ values = array() ) [static]

Find records by id.

Parameters:

$values

The primary key values of the records to retrieve

Returns:: Array of AnewtAutoRecord instances (may be empty)

See also:: db_find_one_by_id

Definition at line 569 of file autorecord.lib.php.

static AnewtAutoRecord::db_find_one_by_id ( $ value ) [static]

Find a single record by primary key value.

Parameters:

$value

The primary key value of the record to retrieve

Returns:: AnewtAutoRecord instance (or NULL)

See also:: db_find_all_by_id

Definition at line 585 of file autorecord.lib.php.

static AnewtAutoRecord::db_find_all_by_sql	(	$	sql = `null`,
		$	values = `array()`
	)			`[static]`

Find records by providing SQL contraints.

The $sql argument can be:

a string: the part of the WHERE clause up to the end of the query
an associative array with one or more of the following keys (with string values), all optional:
- where for the WHERE clause
- order-by for a custom ORDER BY to be used instead of the the order specified by the db_columns_order_by() method
- limit for the LIMIT clause
- offset for the OFFSET clause
- select, which can be be used to provide additional columns for the SELECT part of the query, in addition to the standard columns specified in db_columns()
- join, which will be inserted right after the FROM clause of the generated query, so that it is easy to create simple joins. Note that you should provide a complete string here just as you would in normal regular SQL queries, i.e. including the JOIN and ON or USING keywords.
- table-alias for the table alias used for the main table (most useful if join is used as well)

In both cases, ?str?-style placeholders can be used in the values provided for the $sql parameter. The $values array will be used to fill these placeholders.

Parameters:

	$sql	The constraints of the SQL query
	$values	Array with placeholder values

See also:: db_find_one_by_sql

Definition at line 622 of file autorecord.lib.php.

static AnewtAutoRecord::db_find_one_by_sql	(	$	sql = `null`,
		$	values = `array()`
	)			`[static]`

Find a single record by providing SQL contraints.

See db_find_all_by_sql for a detailed description of the $sql parameter.

Parameters:

	$sql	Contraints of the SQL query
	$values	Values to be substituted in the query

Returns:: AnewtAutoRecord instance (or NULL)

See also:: db_find_all_by_sql

Definition at line 642 of file autorecord.lib.php.

static AnewtAutoRecord::db_find_all_by_column	(	$	column,
		$	value
	)			`[static]`

Find records by column value.

This is a shorthand to find records based on the value of a single column, e.g. a unique key.

Parameters:

	$column	The name of the column to use
	$value	The value for the column

Returns:: Array of AnewtAutoRecord instances (may be empty)

See also:: db_find_one_by_column

Definition at line 662 of file autorecord.lib.php.

static AnewtAutoRecord::db_find_one_by_column	(	$	column,
		$	value
	)			`[static]`

Find a single record by column value.

This is a shorthand to find a record based on the value of a single column, e.g. a unique key.

Parameters:

	$column	The name of the column to use
	$value	The value for the column

Returns:: AnewtAutoRecord instance (or NULL)

See also:: db_find_all_by_column

Definition at line 682 of file autorecord.lib.php.

static AnewtAutoRecord::_db_find_by_id	(	$	class,
		$	just_one_result,
		$	values,
		$	connection
	)			`[static, final, protected]`

Find one or more records by primary key value.

Parameters:

	$class	Class name
	$just_one_result	Whether to return just one instance (or null) or an array of instances (possibly empty)
	$values	The values to search for (primary key values)
	$connection	AnewtDatabaseConnection instance

Returns:: A single instance (or null) or an array of instances (or empty array)

Definition at line 704 of file autorecord.lib.php.

static AnewtAutoRecord::_db_find_by_sql	(	$	class,
		$	just_one_result = `false`,
		$	sql = `null`,
		$	values = `array()`,
		$	connection
	)			`[static, final, protected]`

Find one or more records by providing a part of the SQL query.

Parameters:

	$class	Class name
	$just_one_result	Whether to return just one instance (or null) or an array of instances
	$sql	The constraints of the SQL query
	$values	Array with placeholder values
	$connection	AnewtDatabaseConnection instance

Definition at line 764 of file autorecord.lib.php.

static AnewtAutoRecord::_db_find_by_column	(	$	class,
		$	just_one_result,
		$	column,
		$	value,
		$	connection
	)			`[static, final, protected]`

Find one or more records by one column value.

Parameters:

	$class	Class name
	$just_one_result	Whether to return just one instance (or null) or an array of instances (possibly empty)
	$column	The column to match
	$value	The value to match
	$connection	AnewtDatabaseConnection instance

Definition at line 932 of file autorecord.lib.php.

AnewtAutoRecord::db_save ( ) [final]

Save a record in the database.

If the record was previously unsaved (no primary key value was set), an INSERT query is performed; otherwise, an UPDATE on the existing row is done.

See also:: db_insert
db_update

Definition at line 976 of file autorecord.lib.php.

AnewtAutoRecord::db_insert ( ) [final]

Insert the data as a new record in the database.

In most cases you should use db_save() instead.

See also:: db_save
db_update

Definition at line 994 of file autorecord.lib.php.

AnewtAutoRecord::db_update ( ) [final]

Update an existing record in the database.

In most cases you should use db_save() instead.

See also:: db_save
db_insert

Definition at line 1089 of file autorecord.lib.php.

AnewtAutoRecord::db_delete ( ) [final]

Delete this record from the database.

If the record was previously unsaved, this method does nothing. If a value for the the primary key has been set, the record is assumed to have been saved.

Definition at line 1143 of file autorecord.lib.php.

static AnewtAutoRecord::array_by_column_value	(	$	instances,
		$	column,
		$	unique
	)			`[static, final]`

Group AnewtAutoRecord instances by the value of a column.

This method can be used to group an array of AnewtAutoRecord instances by the value of a column. It handles both unique and non-unique column values, based on the $unique parameter.

Note that the column value should be a string, or convertable to a string.

The resulting array uses the column values as keys. If $unique is true, each array value is an object instance. If $unique is false, each array value is an array of object instances.

the column value as the key and the instance itself as the value (if $unique is true)

Parameters:

	$instances	A list of AnewtAutoRecord instances
	$column	The name of the (unique) column to use as the associative array.
	$unique	Whether the column value should be unique. This influences the structure of the resulting array.

Returns:: Associative array with instances by column value

See also:: array_by_primary_key_value

Definition at line 1198 of file autorecord.lib.php.

static AnewtAutoRecord::array_by_primary_key_value ( $ instances ) [static, final]

Convert a list of AnewtAutoRecord instances to an associative array indexed by primary key.

Parameters:

$instances

A list of AnewtAutoRecord instances

Returns:: An associative array with the primary key as the key and the instance itself as the value

See also:: array_by_column_value

Definition at line 1245 of file autorecord.lib.php.

static AnewtAutoRecord::db_object_from_array ( $ arr ) [static]

Create instance from array.

Parameters:

$arr

An associative array with data, e.g. a row from a database

Returns:: AnewtAutoRecord instance

See also:: db_objects_from_arrays

Definition at line 1269 of file autorecord.lib.php.

static AnewtAutoRecord::db_objects_from_arrays ( $ arrs ) [static]

Create instances from arrays.

Parameters:

$arrs

List of associative arrays with data, e.g. multiple rows from a database

Returns:: Array of AnewtAutoRecord instances (may be empty)

See also:: db_object_from_array

Definition at line 1286 of file autorecord.lib.php.

static AnewtAutoRecord::_db_object_from_array	(	$	class,
		$	row
	)			`[static, final, protected]`

Converts a result row into an object instance.

Parameters:

	$class	Class name
	$row	The row with data (or null).

Returns:: A reference to a new instance or null if no data was provided

See also:: db_object_from_array
_db_objects_from_arrays

Definition at line 1305 of file autorecord.lib.php.

static AnewtAutoRecord::_db_objects_from_arrays	(	$	class,
		$	rows
	)			`[static, final, protected]`

Convert result rows into object instances.

Parameters:

	$class	Class name
	$rows	The rows with data (or an empty array).

Returns:: An array with references to new instances or an empty array no data was provided

See also:: db_objects_from_arrays
_db_objects_from_array

Definition at line 1327 of file autorecord.lib.php.

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

autorecord.lib.php


Public Member Functions
Instance Methods
	db_save ()
	Save a record in the database.
	db_insert ()
	Insert the data as a new record in the database.
	db_update ()
	Update an existing record in the database.
	db_delete ()
	Delete this record from the database.
Static Public Member Functions
Autorecord Registration
static	register ($class)
	Register a class as an AnewtAutoRecord.
Database Methods
static	db_connection ()
	Obtain a database connection.
static	db_table ()
	Return the name of the table to use.
static	db_columns ()
	Return an associative array of column name to column type mappings.
static	db_columns_skip_on_save ()
	Return an array of column names which are read-only and should never be written.
static	db_columns_skip_on_insert ()
	Return an array of column names which should be skipped on insert queries when no values are given.
static	db_columns_skip_on_update ()
	Return an array of column names which should be skipped on update queries.
static	db_columns_order_by ()
	Return an associative array with sort columns and sort orders.
static	db_primary_key_column ()
	Return the name of the primary key.
static	db_primary_key_sequence ()
	Return the name of the sequence used for the primary key (PostgreSQL only).
static	db_sql_select ($table_alias=null)
	Return a SQL `SELECT` clause.
static	db_sql_from ($table_alias=null)
	Return a SQL `FROM` clause.
static	db_sql_order_by ($table_alias=null)
	Return a SQL `ORDER BY` clause.
static	_db_sql_select ($class, $table_alias=null, $connection)
	Return a SQL `SELECT` clause.
static	_db_sql_from ($class, $table_alias=null, $connection)
	Return a SQL `FROM` clause.
static	_db_sql_order_by ($class, $table_alias=null, $connection)
	Return a SQL `ORDER BY` clause.
Record Finding Methods
Note: These methods only have signatures, so that they can be documented. The actual implementation is done using magic in the register() method.
static	db_find_all ()
	Find all records in the database table.
static	db_find_all_by_id ($values=array())
	Find records by id.
static	db_find_one_by_id ($value)
	Find a single record by primary key value.
static	db_find_all_by_sql ($sql=null, $values=array())
	Find records by providing SQL contraints.
static	db_find_one_by_sql ($sql=null, $values=array())
	Find a single record by providing SQL contraints.
static	db_find_all_by_column ($column, $value)
	Find records by column value.
static	db_find_one_by_column ($column, $value)
	Find a single record by column value.
static	_db_find_by_id ($class, $just_one_result, $values, $connection)
	Find one or more records by primary key value.
static	_db_find_by_sql ($class, $just_one_result=false, $sql=null, $values=array(), $connection)
	Find one or more records by providing a part of the SQL query.
static	_db_find_by_column ($class, $just_one_result, $column, $value, $connection)
	Find one or more records by one column value.
Helper Methods
static	array_by_column_value ($instances, $column, $unique)
	Group AnewtAutoRecord instances by the value of a column.
static	array_by_primary_key_value ($instances)
	Convert a list of AnewtAutoRecord instances to an associative array indexed by primary key.
static	db_object_from_array ($arr)
	Create instance from array.
static	db_objects_from_arrays ($arrs)
	Create instances from arrays.
static	_db_object_from_array ($class, $row)
	Converts a result row into an object instance.
static	_db_objects_from_arrays ($class, $rows)
	Convert result rows into object instances.