Docs For Class TActiveRecord

Class TActiveRecord

Description

Base class for active records.

An active record creates an object that wraps a row in a database table or view, encapsulates the database access, and adds domain logic on that data.

The essence of an Active Record is an object model of the domain (e.g. products, items) that incorporates both behavior and data in which the classes match very closely the record structure of an underlying database. Each Active Record is responsible for saving and loading to the database and also for any domain logic that acts on the data.

The Active Record provides methods that do the following:

Construct an instance of the Active Record from a SQL result set row.
Construct a new instance for later insertion into the table.
Finder methods to wrap commonly used SQL queries and return Active Record objects.
Update the database and insert into it the data in the Active Record.

Example:

 class UserRecord extends TActiveRecord
 {
     public $username; //corresponds to the fieldname in the table
          public $email;
 
     public static final $_tablename='users'; //optional table name.
 
     //returns active record finder instance
          public static function finder()
     {
         return self::getRecordFinder('UserRecord');
     }
 }
 
 //create a connection and give it to the ActiveRecord manager.
  $dsn = 'pgsql:host=localhost;dbname=test';
 $conn = new TDbConnection($dsn, 'dbuser','dbpass');
 TActiveRecordManager::getInstance()->setDbConnection($conn);
 
 //load the user record with username (primary key) 'admin'.
  $user = UserRecord::finder()->findByPk('admin');
 $user->email = 'admin@example.org';
 $user->save(); //update the 'admin' record.

abstract:
since: 3.1
version: $Id: TActiveRecord.php 1606 2007-01-09 10:42:06Z wei $
author: Wei Zhuo <weizho[at]gmail[dot]com>

Located in /Data/ActiveRecord/TActiveRecord.php (line 66)

TComponent
   |
   --TActiveRecord

Method Summary

TActiveRecord __construct ([array $data = array()], [TDbConnection $connection = null])

int count ([string|TActiveRecordCriteria $criteria = null], [mixed $parameters = array()])

boolean delete ()

int deleteAll (string|TActiveRecordCriteria $criteria, [mixed $parameters = array()])

int deleteByPk (mixed $keys)

TActiveRecord find (string|TActiveRecordCriteria $criteria, [mixed $parameters = array()])

array findAll ([string|TActiveRecordCriteria $criteria = null], [mixed $parameters = array()])

array findAllByPks (mixed $keys)

TActiveRecord findByPk (mixed $keys)

array findBySql (string $sql, [array $parameters = array()])

TDbConnection getDbConnection ()

TActiveRecord getRecordFinder (string $class)

TActiveRecordManager getRecordManager ()

TActiveRecord populateObject (string $type, array $data)

boolean save ()

void setDbConnection (TDbConnection $connection)

mixed __call (mixed $method, mixed $args)

void __sleep ()

void __wake ()

Methods

Constructor __construct (line 98)

Create a new instance of an active record with given $data. The record can be saved to the database specified by the $connection object.

access: public

TActiveRecord __construct ([array $data = array()], [TDbConnection $connection = null])

array $data: optional name value pair record data.
TDbConnection $connection: optional database connection this object record use.

count (line 394)

Find the number of records.

return: number of records.
access: public

int count ([string|TActiveRecordCriteria $criteria = null], [mixed $parameters = array()])

string|TActiveRecordCriteria $criteria: SQL condition or criteria object.
mixed $parameters: parameter values.

delete (line 175)

Deletes the current record from the database. Once deleted, this object can not be saved again in the same instance.

return: true if the record was deleted successfully, false otherwise.
access: public

boolean delete ()

deleteAll (line 220)

Delete multiple records using a criteria.

return: number of records deleted.
access: public

int deleteAll (string|TActiveRecordCriteria $criteria, [mixed $parameters = array()])

string|TActiveRecordCriteria $criteria: SQL condition or criteria object.
mixed $parameters: parameter values.

deleteByPk (line 205)

Delete records by primary key. Usage:

 $finder->deleteByPk($primaryKey); //delete 1 record
  $finder->deleteByPk($key1,$key2,...); //delete multiple records
  $finder->deleteByPk(array($key1,$key2,...)); //delete multiple records

For composite primary keys (determined from the table definitions):

 $finder->deleteByPk(array($key1,$key2)); //delete 1 record
 
 //delete multiple records
  $finder->deleteByPk(array($key1,$key2), array($key3,$key4),...);
 
 //delete multiple records
  $finder->deleteByPk(array( array($key1,$key2), array($key3,$key4), .. ));

return: number of records deleted.
access: public

int deleteByPk (mixed $keys)

mixed $keys: primary key values.

find (line 279)

Find one single record that matches the criteria.

Usage:

 $finder->find('username = :name AND password = :pass',
                     array(':name'=>$name, ':pass'=>$pass));
 $finder->find('username = ? AND password = ?', array($name, $pass));
 $finder->find('username = ? AND password = ?', $name, $pass);
 //$criteria is of TActiveRecordCriteria
  $finder->find($criteria); //the 2nd parameter for find() is ignored.

return: matching record object.
access: public

TActiveRecord find (string|TActiveRecordCriteria $criteria, [mixed $parameters = array()])

string|TActiveRecordCriteria $criteria: SQL condition or criteria object.
mixed $parameters: parameter values.

findAll (line 302)

Same as find() but returns an array of objects.

return: matching record objects
access: public

array findAll ([string|TActiveRecordCriteria $criteria = null], [mixed $parameters = array()])

string|TActiveRecordCriteria $criteria: SQL condition or criteria object.
mixed $parameters: parameter values.

findAllByPks (line 359)

Find multiple records matching a list of primary or composite keys.

For scalar primary keys:

 $finder->findAllByPk($key1, $key2, ...);
 $finder->findAllByPk(array($key1, $key2, ...));

For composite keys:

 $finder->findAllByPk(array($key1, $key2), array($key3, $key4), ...);
 $finder->findAllByPk(array(array($key1, $key2), array($key3, $key4), ...));

return: matching ActiveRecords
access: public

array findAllByPks (mixed $keys)

mixed $keys: primary keys

findByPk (line 333)

Find one record using only the primary key or composite primary keys. Usage:

 $finder->findByPk($primaryKey);
 $finder->findByPk($key1, $key2, ...);
 $finder->findByPk(array($key1,$key2,...));

access: public

TActiveRecord findByPk (mixed $keys)

mixed $keys: primary keys

findBySql (line 377)

Find records using full SQL, returns corresponding record object.

return: matching active records.
access: public

array findBySql (string $sql, [array $parameters = array()])

array $parameters
string $sql: select SQL

getDbConnection (line 111)

Gets the current Db connection, the connection object is obtained from the TActiveRecordManager if connection is currently null.

return: current db connection for this object.
access: public

TDbConnection getDbConnection ()

getRecordFinder (line 133)

Returns the instance of a active record finder for a particular class.

return: active record finder instance.
static:
access: public

TActiveRecord getRecordFinder (string $class)

string $class: active record class name.

getRecordManager (line 150)

Gets the record manager for this object, the default is to call TActiveRecordManager::getInstance().

return: default active record manager.
access: public

TActiveRecordManager getRecordManager ()

populateObject (line 241)

Populate the record with data, registers the object as clean.

return: object record, null if data is empty.
access: protected

TActiveRecord populateObject (string $type, array $data)

string $type: new record name
array $data: name value pair record data

save (line 159)

Saves the current record to the database, insert or update is automatically determined.

return: true if record was saved successfully, false otherwise.
access: public

boolean save ()

setDbConnection (line 123)

access: public

void setDbConnection (TDbConnection $connection)

TDbConnection $connection: db connection object for this record.

__call (line 432)

Dynamic find method using parts of method name as search criteria.

Method name starting with "findBy" only returns 1 record. Method name starting with "findAllBy" returns 0 or more records. The condition is taken as part of the method name after "findBy" or "findAllBy".

The following are equivalent:

 $finder->findByName($name)
 $finder->find('Name = ?', $name);

 $finder->findByUsernameAndPassword($name,$pass);
 $finder->findBy_Username_And_Password($name,$pass);
 $finder->find('Username = ? AND Password = ?', $name, $pass);

 $finder->findAllByAge($age);
 $finder->findAll('Age = ?', $age);

return: single record if method name starts with "findBy", 0 or more records if method name starts with "findAllBy"
access: public

mixed __call (mixed $method, mixed $args)

__sleep (line 81)

Prevent __call() method creating __sleep() when serializing.

access: public

void __sleep ()

__wake (line 89)

Prevent __call() method creating __wake() when unserializing.

access: public

void __wake ()

Inherited Methods

Inherited From TComponent

TComponent::addParsedObject()
TComponent::attachEventHandler()
TComponent::canGetProperty()
TComponent::canSetProperty()
TComponent::createdOnTemplate()
TComponent::detachEventHandler()
TComponent::evaluateExpression()
TComponent::evaluateStatements()
TComponent::getEventHandlers()
TComponent::getSubProperty()
TComponent::hasEvent()
TComponent::hasEventHandler()
TComponent::hasProperty()
TComponent::raiseEvent()
TComponent::setSubProperty()
TComponent::__get()
TComponent::__set()

Documentation generated on Sun, 14 Jan 2007 21:40:56 -0500 by phpDocumentor 1.3.0RC4