php.activerecord

Constructs a model.

When a user instantiates a new object (e.g.: it was not ActiveRecord that instantiated via a find) then @var $attributes will be mapped according to the schema's defaults. Otherwise, the given $attributes will be mapped via set_attributes_via_mass_assignment.

 new Person(array('first_name' => 'Tito', 'last_name' => 'the Grief'));

	

Alias for self::find('all').

Assign a value to an attribute.

Returns a copy of the model's attributes hash.

Check if a particular attribute has been modified since loading the model.

Retrieve the connection for this model.

Get a count of qualifying records.

 YourModel::count(array('conditions' => 'amount > 3.14159265'));

	

Creates a model and saves it to the database.

Deletes this model from the database and returns true if successful.

Deletes records matching conditions in $options

Does not instantiate models and therefore does not invoke callbacks

Delete all using a hash:

 YourModel::delete_all(array('conditions' => array('name' => 'Tito')));

	

Delete all using an array:

 YourModel::delete_all(array('conditions' => array('name = ?', 'Tito')));

	

Delete all using a string:

 YourModel::delete_all(array('conditions' => 'name = "Tito"));

	

An options array takes the following parameters:

• conditions: Conditions using a string/hash/array
• limit: Limit number of records to delete (MySQL & Sqlite only)
• order: A SQL fragment for ordering such as: 'name asc', 'id desc, name asc' (MySQL & Sqlite only)

Returns hash of attributes that have been modified since loading the model.

Determine if a record exists.

 SomeModel::exists(123);
 SomeModel::exists(array('conditions' => array('id=? and name=?', 123, 'Tito')));
 SomeModel::exists(array('id' => 123, 'name' => 'Tito'));

	

Pulls out the options hash from $array if any.

Find records in the database.

Finding by the primary key:

 # queries for the model with id=123
 YourModel::find(123);

 # queries for model with id in(1,2,3)
 YourModel::find(1,2,3);

 # finding by pk accepts an options array
 YourModel::find(123,array('order' => 'name desc'));

	

Finding by using a conditions array:

 YourModel::find('first', array('conditions' => array('name=?','Tito'),
   'order' => 'name asc'))
 YourModel::find('all', array('conditions' => 'amount > 3.14159265'));
 YourModel::find('all', array('conditions' => array('id in(?)', array(1,2,3))));

	

Finding by using a hash:

 YourModel::find(array('name' => 'Tito', 'id' => 1));
 YourModel::find('first',array('name' => 'Tito', 'id' => 1));
 YourModel::find('all',array('name' => 'Tito', 'id' => 1));

	

An options array can take the following parameters:

• select: A SQL fragment for what fields to return such as: '*', 'people.*', 'first_name, last_name, id'
• joins: A SQL join fragment such as: 'JOIN roles ON(roles.user_id=user.id)' or a named association on the model
• include: TODO not implemented yet
• conditions: A SQL fragment such as: 'id=1', array('id=1'), array('name=? and id=?','Tito',1), array('name IN(?)', array('Tito','Bob')), array('name' => 'Tito', 'id' => 1)
• limit: Number of records to limit the query to
• offset: The row offset to return results from for the query
• order: A SQL fragment for order such as: 'name asc', 'name asc, id desc'
• readonly: Return all the models in readonly mode
• group: A SQL group by fragment

Finder method which will find by a single or array of primary keys for this model.

Find using a raw SELECT query.

 YourModel::find_by_sql("SELECT * FROM people WHERE name=?",array('Tito'));
 YourModel::find_by_sql("SELECT * FROM people WHERE name='Tito'");

	

Alias for self::find('first').

Flags an attribute as dirty.

Retrieve the primary key name.

Returns the actual attribute name if $name is aliased.

Returns array of validator data for this Model.

Will return an array looking like:

 array(
   'name' => array(
     array('validator' => 'validates_presence_of'),
     array('validator' => 'validates_inclusion_of', 'in' => array('Bob','Joe','John')),
   'password' => array(
     array('validator' => 'validates_length_of', 'minimum' => 6))
   )
 );

	

Returns an associative array containing values for all the attributes in $attributes

Returns true if the model has been modified.

Runs validations and returns true if invalid.

Determine if the model is a new record.

Determines if the specified array is a valid ActiveRecord options array.

Determine if the model is in read-only mode.

Run validations on model and returns whether or not model passed validation.

Alias for self::find('last')

Returns a hash containing the names => values of the primary key.

Helper method to run arbitrary queries against the model's database connection.

Flag model as readonly.

Retrieves an attribute's value or a relationship object based on the name passed. If the attribute accessed is 'id' then it will return the model's primary key no matter what the actual attribute name is for the primary key.

Re-establishes the database connection with a new connection.

Reloads the attributes and relationships of this object from the database.

Resets the dirty array.

Save the model to the database.

This function will automatically determine if an INSERT or UPDATE needs to occur. If a validation or a callback for this model returns false, then the model will not be saved and this will return false.

If saving an existing model only data that has changed will be saved.

Mass update the model with data from an attributes hash.

Unlike update_attributes() this method only updates the model's data but DOES NOT save it to the database.

Add a model to the given named ($name) relationship.

Updates a model's timestamps.

Returns the Table object for this model.

Be sure to call in static scoping: static::table()

Retrieves the name of the table for this Model.

Returns an Array representation of this model.

Returns an CSV representation of this model.

Can take optional delimiter and enclosure (defaults are , and double quotes)

Ex:

 ActiveRecord\CsvSerializer::$delimiter=';';
 ActiveRecord\CsvSerializer::$enclosure='';
 YourModel::find('first')->to_csv(array('only'=>array('name','level')));
 returns: Joe,2

 YourModel::find('first')->to_csv(array('only_header'=>true,'only'=>array('name','level')));
 returns: name,level

	

Returns a JSON representation of this model.

Returns an XML representation of this model.

Executes a block of code inside a database transaction.

 YourModel::transaction(function()
 {
   YourModel::create(array("name" => "blah"));
 });

	

If an exception is thrown inside the closure the transaction will automatically be rolled back. You can also return false from your closure to cause a rollback:

 YourModel::transaction(function()
 {
   YourModel::create(array("name" => "blah"));
   throw new Exception("rollback!");
 });

 YourModel::transaction(function()
 {
   YourModel::create(array("name" => "blah"));
   return false; # rollback!
 });

	

Updates records using set in $options

Does not instantiate models and therefore does not invoke callbacks

Update all using a hash:

 YourModel::update_all(array('set' => array('name' => "Bob")));

	

Update all using a string:

 YourModel::update_all(array('set' => 'name = "Bob"'));

	

An options array takes the following parameters:

• set: String/hash of field names and their values to be updated with
• conditions: Conditions using a string/hash/array
• limit: Limit number of records to update (MySQL & Sqlite only)
• order: A SQL fragment for ordering such as: 'name asc', 'id desc, name asc' (MySQL & Sqlite only)

Updates a single attribute and saves the record without going through the normal validation procedure.

Mass update the model with an array of attribute data and saves to the database.

Helper to return a hash of values for the specified attributes.

Helper that creates an array of values for the primary key(s).

Enables the use of build|create for associations.

Enables the use of dynamic finders.

Dynamic finders are just an easy way to do queries quickly without having to specify an options array with conditions in it.

 SomeModel::find_by_first_name('Tito');
 SomeModel::find_by_first_name_and_last_name('Tito','the Grief');
 SomeModel::find_by_first_name_or_last_name('Tito','the Grief');
 SomeModel::find_all_by_last_name('Smith');
 SomeModel::count_by_name('Bob')
 SomeModel::count_by_name_or_state('Bob','VA')
 SomeModel::count_by_name_and_state('Bob','VA')

	

You can also create the model if the find call returned no results:

 Person::find_or_create_by_name('Tito');

 # would be the equivalent of
 if (!Person::find_by_name('Tito'))
   Person::create(array('Tito'));

	

Some other examples of find_or_create_by:

 Person::find_or_create_by_name_and_id('Tito',1);
 Person::find_or_create_by_name_and_id(array('name' => 'Tito', 'id' => 1));

	

Magic method which delegates to read_attribute(). This handles firing off getter methods, as they are not checked/invoked inside of read_attribute(). This circumvents the problem with a getter being accessed with the same name as an actual attribute.

You can also define customer getter methods for the model.

EXAMPLE:

 class User extends ActiveRecord\Model {

   # define custom getter methods. Note you must
   # prepend get_ to your method name:
   function get_middle_initial() {
     return $this->middle_name{0};
   }
 }

 $user = new User();
 echo $user->middle_name;  # will call $user->get_middle_name()

	

If you define a custom getter with the same name as an attribute then you will need to use read_attribute() to get the attribute's value. This is necessary due to the way __get() works.

For example, assume 'name' is a field on the table and we're defining a custom getter for 'name':

 class User extends ActiveRecord\Model {

   # INCORRECT way to do it
   # function get_name() {
   #   return strtoupper($this->name);
   # }

   function get_name() {
     return strtoupper($this->read_attribute('name'));
   }
 }

 $user = new User();
 $user->name = 'bob';
 echo $user->name; # => BOB

	

Determines if an attribute exists for this Model.

Magic allows un-defined attributes to set via $attributes.

You can also define customer setter methods for the model.

EXAMPLE:

 class User extends ActiveRecord\Model {

   # define custom setter methods. Note you must
   # prepend set_ to your method name:
   function set_password($plaintext) {
     $this->encrypted_password = md5($plaintext);
   }
 }

 $user = new User();
 $user->password = 'plaintext';  # will call $user->set_password('plaintext')

	

If you define a custom setter with the same name as an attribute then you will need to use assign_attribute() to assign the value to the attribute. This is necessary due to the way __set() works.

For example, assume 'name' is a field on the table and we're defining a custom setter for 'name':

 class User extends ActiveRecord\Model {

   # INCORRECT way to do it
   # function set_name($name) {
   #   $this->name = strtoupper($name);
   # }

   function set_name($name) {
     $this->assign_attribute('name',strtoupper($name));
   }
 }

 $user = new User();
 $user->name = 'bob';
 echo $user->name; # => BOB