## Class TTableGateway

Description

TTableGateway class provides several find methods to get data from the database and update, insert, and delete methods.

Each method maps the input parameters into a SQL call and executes the SQL against a database connection. The TTableGateway is stateless (with respect to the data and data objects), as its role is to push data back and forth.

Example usage:

     //create a connection
      $dsn = 'pgsql:host=localhost;dbname=test';
     $conn = new TDbConnection($dsn, 'dbuser','dbpass');

     //create a table gateway for table/view named 'address'
      $table = new TTableGateway('address', $conn);

     //insert a new row, returns last insert id (if applicable)
      $id = $table->insert(array('name'=>'wei', 'phone'=>'111111'));

     $record1 = $table->findByPk($id); //find inserted record

     //finds all records, returns an iterator
      $records = $table->findAll();
     print_r($records->readAll());

     //update the row
      $table->updateByPk($record1, $id);

All methods that may return more than one row of data will return an TDbDataReader iterator.

The OnCreateCommand event is raised when a command is prepared and parameter binding is completed. The parameter object is a TDataGatewayEventParameter of which the TDataGatewayEventParameter::getCommand property can be inspected to obtain the sql query to be executed.

The OnExecuteCommand event is raised when a command is executed and the result from the database was returned. The parameter object is a TDataGatewayResultEventParameter of which the TDataGatewayEventParameter::getResult property contains the data return from the database. The data returned can be changed by setting the TDataGatewayEventParameter::setResult property.

     $table->OnCreateCommand[] = 'log_it'; //any valid PHP callback statement
      $table->OnExecuteCommand[] = array($obj, 'method_name'); // calls 'method_name' on $obj

     function log_it($sender, $param)
     {
         var_dump($param); //TDataGatewayEventParameter object.
     }

- since: 3.1
- version: $Id$
- author: Wei Zhuo <weizho[at]gmail[dot]com>

Located in /Data/DataGateway/TTableGateway.php (line 79)

    TComponent
       |
       --TTableGateway

Method Summary
TTableGateway __construct (string|TDbTableInfo $table, TDbConnection $connection)
int count ([string|TSqlCriteria $criteria = null], [mixed $parameters = array()])
integer deleteAll (string $criteria, [array $parameters = array()])
void deleteAllByPks (mixed $keys)
int deleteByPk (mixed $keys)
array find (string|TSqlCriteria $criteria, [mixed $parameters = array()])
TDbDataReader findAll ([string|TSqlCriteria $criteria = null], [mixed $parameters = array()])
TDbDataReader findAllByPks (mixed $keys)
TDbDataReader findAllBySql (string $sql, [array $parameters = array()])
array findByPk (mixed $keys)
array findBySql (string $sql, [array $parameters = array()])
TDataGatewayCommand getCommand ()
TSqlCriteria getCriteria (string|TSqlCriteria $criteria, mixed $parameters, array $args)
TDbConnection getDbConnection ()
mixed getLastInsertId ()
void getTableInfo ()
void getTableName ()
void initCommandBuilder (TDbCommandBuilder $builder)
mixed insert (array $data)
void onCreateCommand (TDataGatewayCommand $sender, TDataGatewayEventParameter $param)
void onExecuteCommand (TDataGatewayCommand $sender, TDataGatewayResultEventParameter $param)
void setTableInfo (TDbTableInfo $tableInfo)
void setTableName (string $tableName)
integer update (array $data, string $criteria, [array $parameters = array()])
mixed __call (mixed $method, mixed $args)
Methods
Constructor __construct (line 90)

Creates a new generic table gateway for a given table or view name and a database connection.

- access: public

TTableGateway __construct (string|TDbTableInfo $table, TDbConnection $connection)

- string|TDbTableInfo $table: table or view name or table information.
- TDbConnection $connection: database connection.

count (line 355)

Find the number of records.

- return: number of records.
- access: public

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

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

deleteAll (line 302)

Delete records from the table with condition given by $where and binding values specified by $parameter argument.

This method uses additional arguments as $parameters. E.g.

     $table->delete('age > ? AND location = ?', $age, $location);

- return: number of records deleted.
- access: public

integer deleteAll (string $criteria, [array $parameters = array()])

- string $criteria: delete condition.
- array $parameters: condition parameters.

deleteAllByPks (line 342)

Alias for deleteByPk()

- access: public

void deleteAllByPks (mixed $keys)
deleteByPk (line 332)

Delete records by primary key. Usage:

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

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

     $table->deleteByPk(array($key1,$key2)); //delete 1 record

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

     //delete multiple records
      $table->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 227)

Find one single record that matches the criteria.

Usage:

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

- return: matching record object.
- access: public

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

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

findAll (line 240)

Accepts same parameters as find(), but returns TDbDataReader instead.

- return: matching records.
- access: public

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

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

findAllByPks (line 284)

Similar to findByPk(), but returns TDbDataReader instead.

For scalar primary keys:

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

For composite keys:

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

- return: data reader.
- access: public

TDbDataReader findAllByPks (mixed $keys)

- mixed $keys: primary keys

findAllBySql (line 203)

Execute arbituary sql command with binding parameters.

- return: query results.
- access: public

TDbDataReader findAllBySql (string $sql, [array $parameters = array()])

- string $sql: SQL query string.
- array $parameters: binding parameters, positional or named.

findByPk (line 260)

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

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

- return: matching record.
- access: public

array findByPk (mixed $keys)

- mixed $keys: primary keys

findBySql (line 190)

Execute arbituary sql command with binding parameters.

- return: query results.
- access: public

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

- string $sql: SQL query string.
- array $parameters: binding parameters, positional or named.

getCommand (line 171)

- return: command builder and executor.
- access: protected

TDataGatewayCommand getCommand ()
getCriteria (line 413)

Create a new TSqlCriteria object from a string $criteria. The $args are additional parameters and are used in place of the $parameters if $parameters is not an array and $args is an arrary.

- return: criteria object.
- access: protected

TSqlCriteria getCriteria (string|TSqlCriteria $criteria, mixed $parameters, array $args)

- string|TSqlCriteria $criteria: sql criteria
- mixed $parameters: parameters passed by the user.
- array $args: additional parameters obtained from function_get_args().

getDbConnection (line 179)

- return: database connection.
- access: public

TDbConnection getDbConnection ()
getLastInsertId (line 399)

- return: last insert id, null if none is found.
- access: public

mixed getLastInsertId ()
getTableInfo (line 121)

- access: public

void getTableInfo ()
getTableName (line 126)

- access: public

void getTableName ()
initCommandBuilder (line 134)

- access: protected

void initCommandBuilder (TDbCommandBuilder $builder)

- TDbCommandBuilder $builder: database specific command builder.

insert (line 391)

Inserts a new record into the table. Each array key must correspond to a column name in the table unless a null value is permitted.

- return: last insert id if one column contains a serial or sequence, otherwise true if command executes successfully and affected 1 or more rows.
- access: public

mixed insert (array $data)

- array $data: new record data.

onCreateCommand (line 149)

Raised when a command is prepared and parameter binding is completed.

The parameter object is TDataGatewayEventParameter of which the TDataGatewayEventParameter::getCommand property can be inspected to obtain the sql query to be executed.

- access: public

void onCreateCommand (TDataGatewayCommand $sender, TDataGatewayEventParameter $param)

- TDataGatewayCommand $sender: originator $sender
- TDataGatewayEventParameter $param

onExecuteCommand (line 163)

Raised when a command is executed and the result from the database was returned.

The parameter object is TDataGatewayResultEventParameter of which the TDataGatewayEventParameter::getResult property contains the data return from the database. The data returned can be changed by setting the TDataGatewayEventParameter::setResult property.

- access: public

void onExecuteCommand (TDataGatewayCommand $sender, TDataGatewayResultEventParameter $param)

- TDataGatewayCommand $sender: originator $sender
- TDataGatewayResultEventParameter $param

setTableInfo (line 104)

- access: protected

void setTableInfo (TDbTableInfo $tableInfo)

- TDbTableInfo $tableInfo: table or view information.

setTableName (line 114)

Sets up the command builder for the given table.

- access: protected

void setTableName (string $tableName)

- string $tableName: table or view name.

update (line 377)

Updates the table with new name-value pair $data. Each array key must correspond to a column name in the table. The update condition is specified by the $where argument and additional binding values can be specified using the $parameter argument.

This method uses additional arguments as $parameters. E.g.

     $gateway->update($data, 'age > ? AND location = ?', $age, $location);

- return: number of records updated.
- access: public

integer update (array $data, string $criteria, [array $parameters = array()])

- array $data: new record data.
- string $criteria: update condition
- array $parameters: additional binding name-value pairs.

__call (line 455)

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. Method name starting with "deleteBy" deletes records by the trail criteria. The condition is taken as part of the method name after "findBy", "findAllBy" or "deleteBy".

The following are equivalent:

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

     $table->findByUsernameAndPassword($name,$pass); // OR may be used
      $table->findBy_Username_And_Password($name,$pass); // _OR_ may be used
      $table->find('Username = ? AND Password = ?', $name, $pass);

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

     $table->deleteAll('Name = ?', $name);
     $table->deleteByName($name);

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

#### 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, 11 Jan 2009 20:24:03 -0500 by phpDocumentor 1.3.0RC4