Class: AkActiveRecord  - X-Ref

Active Record objects doesn't specify their attributes directly, but rather infer them from the table definition with
which they're linked. Adding, removing, and changing attributes and their type is done directly in the database. Any change
is instantly reflected in the Active Record objects. The mapping that binds a given Active Record class to a certain
database table will happen automatically in most common cases, but can be overwritten for the uncommon ones.

See the mapping rules in table_name and the full example in README.txt for more insight.

== Creation ==

Active Records accepts constructor parameters either in an array or as a list of parameters in a specific format. The array method is especially useful when
you're receiving the data from somewhere else, like a HTTP request. It works like this:

<code>
$user = new User(array('name' => 'David', 'occupation' => 'Code Artist'));
echo $user->name; // Will print "David"
</code>

You can also use a parameter list initialization.:

$user = new User('name->', 'David', 'occupation->', 'Code Artist');

And of course you can just create a bare object and specify the attributes after the fact:

<code>
$user = new User();
$user->name = 'David';
$user->occupation = 'Code Artist';
</code>

== Conditions ==

Conditions can either be specified as a string or an array representing the WHERE-part of an SQL statement.
The array form is to be used when the condition input is tainted and requires sanitization. The string form can
be used for statements that doesn't involve tainted data. Examples:

<code>
class User extends ActiveRecord
{
function authenticateUnsafely($user_name, $password)
{
return findFirst("user_name = '$user_name' AND password = '$password'");
}

function authenticateSafely($user_name, $password)
{
return findFirst("user_name = ? AND password = ?", $user_name, $password);
}
}
</code>

The <tt>authenticateUnsafely</tt> method inserts the parameters directly into the query and is thus susceptible to SQL-injection
attacks if the <tt>$user_name</tt> and <tt>$password</tt> parameters come directly from a HTTP request. The <tt>authenticateSafely</tt> method,
on the other hand, will sanitize the <tt>$user_name</tt> and <tt>$password</tt> before inserting them in the query, which will ensure that
an attacker can't escape the query and fake the login (or worse).

When using multiple parameters in the conditions, it can easily become hard to read exactly what the fourth or fifth
question mark is supposed to represent. In those cases, you can resort to named bind variables instead. That's done by replacing
the question marks with symbols and supplying a hash with values for the matching symbol keys:

<code>
$Company->findFirst(
"id = :id AND name = :name AND division = :division AND created_at > :accounting_date",
array(':id' => 3, ':name' => "37signals", ':division' => "First", ':accounting_date' => '2005-01-01')
);
</code>

== Accessing attributes before they have been type casted ==

Some times you want to be able to read the raw attribute data without having the column-determined type cast run its course first.
That can be done by using the <attribute>_before_type_cast accessors that all attributes have. For example, if your Account model
has a balance attribute, you can call $Account->balance_before_type_cast or $Account->id_before_type_cast.

This is especially useful in validation situations where the user might supply a string for an integer field and you want to display
the original string back in an error message. Accessing the attribute normally would type cast the string to 0, which isn't what you
want.

== Saving arrays, hashes, and other non-mappable objects in text columns ==

Active Record can serialize any object in text columns. To do so, you must specify this with by setting the attribute serialize with
a comma separated list of columns or an array.
This makes it possible to store arrays, hashes, and other non-mappeable objects without doing any additional work. Example:

<code>
class User extends ActiveRecord
{
var $serialize = 'preferences';
}

$User = new User(array('preferences'=>array("background" => "black", "display" => 'large')));
$User->find($user_id);
$User->preferences // array("background" => "black", "display" => 'large')
</code>

== Single table inheritance ==

Active Record allows inheritance by storing the name of the class in a column that by default is called "type" (can be changed
by overwriting <tt>AkActiveRecord->_inheritanceColumn</tt>). This means that an inheritance looking like this:

<code>
class Company extends ActiveRecord{}
class Firm extends Company{}
class Client extends Company{}
class PriorityClient extends Client{}
</code>

When you do $Firm->create('name =>', "akelos"), this record will be saved in the companies table with type = "Firm". You can then
fetch this row again using $Company->find('first', "name = '37signals'") and it will return a Firm object.

If you don't have a type column defined in your table, single-table inheritance won't be triggered. In that case, it'll work just
like normal subclasses with no special magic for differentiating between them or reloading the right type with find.

Note, all the attributes for all the cases are kept in the same table. Read more:
http://www.martinfowler.com/eaaCatalog/singleTableInheritance.html

== Connection to multiple databases in different models ==

Connections are usually created through AkActiveRecord->establishConnection and retrieved by AkActiveRecord->connection.
All classes inheriting from AkActiveRecord will use this connection. But you can also set a class-specific connection.
For example, if $Course is a AkActiveRecord, but resides in a different database you can just say $Course->establishConnection
and $Course and all its subclasses will use this connection instead.

Active Records will automatically record creation and/or update timestamps of database objects
if fields of the names created_at/created_on or updated_at/updated_on are present.
Date only: created_on, updated_on
Date and time: created_at, updated_at

This behavior can be turned off by setting <tt>$this->_recordTimestamps = false</tt>.