AnewtAutoRecord class

Automatic database record object.

Page Contents

  1. Class Overview
  2. Autorecord Registration
  3. Database Methods
  4. Record Finding Methods
  5. Helper Methods
  6. Instance Methods
  7. Inheritance

Class Overview

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:

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

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);

Autorecord Registration

static register($class) [static]

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)

Database Methods

static 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.

Return value

An AnewtDatabaseConnection instance

See also

static db_table() [static]

Return the name of the table to use.

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

Return value

An string with the table name to use

See also

static 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' );

Return value

An associative array mapping column names to column types

See also

static 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.

static 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.

static 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.

static 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

static 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.

Return value

The name of the primary key column

static 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.

Return value

The name of the sequence used for the primary key value

static 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

Return value

SELECT string

static 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

Return value

FROM string

static 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

Return value

ORDER BY string, or null

See also

static _db_sql_select($class, $table_alias=null, $connection) [protected] [static]

Return a SQL SELECT clause.

The SELECT keyword is not included.

Parameters

$class

Class name

$table_alias

Optional table alias name

$connection

AnewtDatabaseConnection instance

Return value

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.

static _db_sql_from($class, $table_alias=null, $connection) [protected] [static]

Return a SQL FROM clause.

Parameters

$class

Class name

$table_alias

Optional table alias name

$connection

AnewtDatabaseConnection instance

Return value

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.

static _db_sql_order_by($class, $table_alias=null, $connection) [protected] [static]

Return a SQL ORDER BY clause.

Parameters

$class

Class name

$table_alias

Optional table alias name

$connection

AnewtDatabaseConnection instance

Return value

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.

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() [static]

Find all records in the database table.

Return value

Array of AnewtAutoRecord instances (may be empty)

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

Find records by id.

Parameters

$values

The primary key values of the records to retrieve

Return value

Array of AnewtAutoRecord instances (may be empty)

See also

static 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

Return value

AnewtAutoRecord instance (or NULL)

See also

static 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

static 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

Return value

AnewtAutoRecord instance (or NULL)

See also

static 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

Return value

Array of AnewtAutoRecord instances (may be empty)

See also

static 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

Return value

AnewtAutoRecord instance (or NULL)

See also

static _db_find_by_id($class, $just_one_result, $values, $connection) [protected] [static]

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

Return value

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

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

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

static _db_find_by_column($class, $just_one_result, $column, $value, $connection) [protected] [static]

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

Helper Methods

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

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.

Return value

Associative array with instances by column value

See also

static array_by_primary_key_value($instances) [static]

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

Parameters

$instances

A list of AnewtAutoRecord instances

Return value

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

See also

static db_object_from_array($arr) [static]

Create instance from array.

Parameters

$arr

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

Return value

AnewtAutoRecord instance

See also

static 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

Return value

Array of AnewtAutoRecord instances (may be empty)

See also

static _db_object_from_array($class, $row) [protected] [static]

Converts a result row into an object instance.

Parameters

$class

Class name

$row

The row with data (or null).

Return value

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

See also

static _db_objects_from_arrays($class, $rows) [protected] [static]

Convert result rows into object instances.

Parameters

$class

Class name

$rows

The rows with data (or an empty array).

Return value

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

See also

Instance Methods

db_save()

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()

Insert the data as a new record in the database.

In most cases you should use db_save() instead.

See also

db_update()

Update an existing record in the database.

In most cases you should use db_save() instead.

See also

db_delete()

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.

Inheritance

Base Classes

Inherited members

Anewt. Almost No Effort Web Toolkit.

© 2006–2009. This page was generated at 2009-08-02T22:54:42+02:00.