PRADO Component Framework for PHP 5
  • Home
  • About
  • Testimonials
  • Demos
  • Download
  • Documentation
  • Forum
  • Development
  • Tutorials
  • Class Docs
  • API Manual
  • Wiki

Packages

  • None
  • System
    • Caching
    • Collections
    • Data
      • ActiveRecord
        • Relations
        • Scaffold
          • InputBuilder
      • Commom
        • Sqlite
      • Common
        • Mssql
        • Mysql
        • Oracle
        • Pgsql
        • Sqlite
      • DataGateway
      • SqlMap
        • Configuration
        • Statements
    • Exceptions
    • I18N
    • IO
    • Security
    • Util
    • Web
      • Javascripts
      • Services
      • UI
        • ActiveControls
        • WebControls
    • Xml
  • Wsat
    • pages
  • Overview
  • Package
  • Class
  • Tree
  • Deprecated
  • Todo

Class TTableGateway

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 Command 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 Result property contains the data return from the database. The data returned can be changed by setting the TDataGatewayEventParameter::setResult Result 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.
}
TComponent
Extended by TTableGateway
Package: System\Data\DataGateway
Copyright: Copyright © 2005-2014 PradoSoft
License: http://www.pradosoft.com/license/
Author: Wei Zhuo <weizho[at]gmail[dot]com>
Version: $Id$
Since: 3.1
Located at Data/DataGateway/TTableGateway.php
Methods summary
public
# __construct( string|TDbTableInfo $table, TDbConnection $connection )

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

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

Parameters

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

Overrides

TComponent::__construct()
protected
# setTableInfo( TDbTableInfo $tableInfo )

Parameters

$tableInfo
TDbTableInfo
table or view information.
protected
# setTableName( string $tableName )

Sets up the command builder for the given table.

Sets up the command builder for the given table.

Parameters

$tableName
string
table or view name.
public
# getTableInfo( )
public
# getTableName( )
protected
# initCommandBuilder( TDbCommandBuilder $builder )

Parameters

$builder
TDbCommandBuilder
database specific command builder.
public
# onCreateCommand( TDataGatewayCommand $sender, TDataGatewayEventParameter $param )

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

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

Parameters

$sender
TDataGatewayCommand
originator $sender
$param
TDataGatewayEventParameter
public
# onExecuteCommand( TDataGatewayCommand $sender, TDataGatewayResultEventParameter $param )

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

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

Parameters

$sender
TDataGatewayCommand
originator $sender
$param
TDataGatewayResultEventParameter
protected TDataGatewayCommand
# getCommand( )

Returns

TDataGatewayCommand
command builder and executor.
public TDbConnection
# getDbConnection( )

Returns

TDbConnection
database connection.
public array
# findBySql( string $sql, array $parameters = array() )

Execute arbituary sql command with binding parameters.

Execute arbituary sql command with binding parameters.

Parameters

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

Returns

array
query results.
public TDbDataReader
# findAllBySql( string $sql, array $parameters = array() )

Execute arbituary sql command with binding parameters.

Execute arbituary sql command with binding parameters.

Parameters

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

Returns

TDbDataReader
query results.
public array
# find( string|TSqlCriteria $criteria, mixed $parameters = array() )

Find one single record that matches the criteria.

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.

Parameters

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

Returns

array
matching record object.
public TDbDataReader
# findAll( string|TSqlCriteria $criteria = null, mixed $parameters = array() )

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

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

Parameters

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

Returns

TDbDataReader
matching records.
public array
# findByPk( mixed $keys )

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

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

Parameters

$keys
mixed
primary keys

Returns

array
matching record.
public TDbDataReader
# findAllByPks( mixed $keys )

Similar to findByPk(), but returns TDbDataReader instead.

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

Parameters

$keys
mixed
primary keys

Returns

TDbDataReader
data reader.
public integer
# deleteAll( string $criteria, array $parameters = array() )

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

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

Parameters

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

Returns

integer
number of records deleted.
public integer
# deleteByPk( mixed $keys )

Delete records by primary key. Usage:

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

Parameters

$keys
mixed
primary key values.

Returns

integer
number of records deleted.
public
# deleteAllByPks( mixed $keys )

Alias for deleteByPk()

Alias for deleteByPk()

public integer
# count( string|TSqlCriteria $criteria = null, mixed $parameters = array() )

Find the number of records.

Find the number of records.

Parameters

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

Returns

integer
number of records.
public integer
# update( array $data, string $criteria, array $parameters = array() )

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

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

Parameters

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

Returns

integer
number of records updated.
public mixed
# insert( array $data )

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.

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.

Parameters

$data
array
new record data.

Returns

mixed
last insert id if one column contains a serial or sequence, otherwise true if command executes successfully and affected 1 or more rows.
public mixed
# getLastInsertId( )

Returns

mixed
last insert id, null if none is found.
protected TSqlCriteria
# getCriteria( string|TSqlCriteria $criteria, mixed $parameters, array $args )

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.

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.

Parameters

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

Returns

TSqlCriteria
criteria object.
public mixed
# __call( string $method, mixed $args )

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

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

Parameters

$method
string
method name that doesn't exist and is being called on the object
$args
mixed
method parameters

Returns

mixed
single record if method name starts with "findBy", 0 or more records if method name starts with "findAllBy"

Throws

TInvalidOperationException
If the property is not defined or read-only or method is undefined

Overrides

TComponent::__call()
Methods inherited from TComponent
__destruct(), __get(), __isset(), __set(), __sleep(), __unset(), __wakeup(), addParsedObject(), asa(), attachBehavior(), attachBehaviors(), attachClassBehavior(), attachEventHandler(), canGetProperty(), canSetProperty(), clearBehaviors(), createdOnTemplate(), detachBehavior(), detachBehaviors(), detachClassBehavior(), detachEventHandler(), disableBehavior(), disableBehaviors(), enableBehavior(), enableBehaviors(), evaluateExpression(), evaluateStatements(), fxAttachClassBehavior(), fxDetachClassBehavior(), getAutoGlobalListen(), getBehaviorsEnabled(), getClassHierarchy(), getEventHandlers(), getListeningToGlobalEvents(), getSubProperty(), hasEvent(), hasEventHandler(), hasProperty(), isa(), listen(), raiseEvent(), setSubProperty(), unlisten()
Constants inherited from TComponent
GLOBAL_RAISE_EVENT_LISTENER
Terms of Service | Contact Us
PRADO v3.2.4 API Manual API documentation generated by ApiGen 2.8.0
Copyright © 2006-2014 by the PRADO Group.
Powered by PRADO