DB_Table
[ class tree: DB_Table ] [ index: DB_Table ] [ all elements ]

Class: DB_Table

Source Location: /DB_Table-1.3.0RC5/DB/Table.php

Class Overview


DB_Table is a database API and data type SQL abstraction class.


Author(s):

Version:

  • @package_version@

Variables

Methods


Child classes:

example
DB_Table is a database API and data type SQL abstraction class.

Inherited Variables

Inherited Methods


Class Details

[line 471]
DB_Table is a database API and data type SQL abstraction class.

DB_Table provides database API abstraction, data type abstraction, automated SELECT, INSERT, and UPDATE queries, automated table creation, automated validation of inserted/updated column values, and automated creation of QuickForm elemnts based on the column definitions.



[ Top ]


Class Variables

$backend =  null

[line 497]

The backend type
  • Access: public

Type:   string


[ Top ]

$col = array()

[line 523]

Associative array of column definitions.
  • Access: public

Type:   array


[ Top ]

$db =  null

[line 484]

The PEAR DB/MDB2 object that connects to the database.
  • Access: public

Type:   object


[ Top ]

$error =  null

[line 626]

If there is an error on instantiation, this captures that error.

This property is used only for errors encountered in the constructor at instantiation time. To check if there was an instantiation error...


1 $obj =& new DB_Table();
2 if ($obj->error) {
3 // ... error handling code here ...
4 }


Type:   object PEAR_Error


[ Top ]

$fetchmode =  null

[line 590]

When calling select() and selectResult(), use this fetch mode (usually a DB_FETCHMODE_* constant). If null, uses whatever is set in the $db PEAR DB/MDB2 object.
  • Access: public

Type:   int


[ Top ]

$fetchmode_object_class =  null

[line 605]

When fetchmode is DB_FETCHMODE_OBJECT, use this class for each returned row. If null, uses whatever is set in the $db PEAR DB/MDB2 object.
  • Access: public

Type:   string


[ Top ]

$idx = array()

[line 536]

Associative array of index definitions.
  • Access: public

Type:   array


[ Top ]

$sql = array()

[line 549]

Baseline SELECT maps for select(), selectResult(), selectCount().
  • Access: public

Type:   array


[ Top ]

$table =  null

[line 510]

The table or view in the database to which this object binds.
  • Access: public

Type:   string


[ Top ]



Method Detail

DB_Table (Constructor)   [line 707]

object DB_Table DB_Table( object &$db, string $table, [mixed $create = false])

Constructor.

If there is an error on instantiation, $this->error will be populated with the PEAR_Error.

  • Access: public

Parameters:

object   &$db     A PEAR DB/MDB2 object.
string   $table     The table name to connect to in the database.
mixed   $create     The automatic table creation mode to pursue:
  • boolean false to not attempt creation
  • 'safe' to create the table only if it does not exist
  • 'drop' to drop any existing table with the same name and re-create it
  • 'verify' to check whether the table exists, whether all the columns exist, whether the columns have the right type, and whether the indexes exist and have the right type
  • 'alter' does the same as 'safe' if the table does not exist; if it exists, a verification for columns existence, the column types, the indexes existence, and the indexes types will be performed and the table schema will be modified if needed

[ Top ]

addFormElements   [line 2463]

void addFormElements( object &$form, [array $columns = null], [string $array_name = null], [mixed $clientValidate = null])

Adds elements and rules to a pre-existing HTML_QuickForm object.

Parameters:

object   &$form     An HTML_QuickForm object.
array   $columns     A sequential array of column names to use in the form; if null, uses all columns.
string   $array_name     By default, the form will use the names of the columns as the names of the form elements. If you pass $array_name, the column names will become keys in an array named for this parameter.

[ Top ]

alter   [line 2210]

mixed alter( )

Alters the table based on $this->col and $this->idx.
  • Return: Boolean true if altering was successful or a PEAR_Error on failure.
  • See: DB_Table_Manager::alter()
  • Access: public

[ Top ]

autoRecast   [line 1885]

void autoRecast( [bool $flag = true])

Turns on (or off) automatic recasting of insert and update data.
  • Access: public

Parameters:

bool   $flag     True to autmatically recast insert and update data, false to not do so.

[ Top ]

autoValidInsert   [line 1549]

void autoValidInsert( [bool $flag = true])

Turns on (or off) automatic validation of inserted data.
  • Access: public

Parameters:

bool   $flag     True to turn on auto-validation, false to turn it off.

[ Top ]

autoValidUpdate   [line 1683]

void autoValidUpdate( [bool $flag = true])

Turns on (or off) automatic validation of updated data.
  • Access: public

Parameters:

bool   $flag     True to turn on auto-validation, false to turn it off.

[ Top ]

buildSQL   [line 1401]

mixed buildSQL( string $sqlkey, [string $filter = null], [string $order = null], [int $start = null], [int $count = null])

Builds the SQL command from a specified $this->sql element.
  • Return: A PEAR_Error on failure, or an SQL command string on success.
  • Access: public

Parameters:

string   $sqlkey     The $this->sql key to use as the basis for the SQL query string.
string   $filter     A filter to add to the WHERE clause of the defined SELECT in $this->sql.
string   $order     An ORDER clause to override the defined order in $this->sql.
int   $start     The row number to start listing from in the result set.
int   $count     The number of rows to list in the result set.

[ Top ]

create   [line 2146]

mixed create( mixed $flag)

Creates the table based on $this->col and $this->idx.
  • Return: Boolean false if there was no need to create the table, boolean true if the attempt succeeded, or a PEAR_Error if the attempt failed.
  • See: DB_Table_Manager::create()
  • Access: public

Parameters:

mixed   $flag     The automatic table creation mode to pursue:
  • 'safe' to create the table only if it does not exist
  • 'drop' to drop any existing table with the same name and re-create it

[ Top ]

delete   [line 1768]

mixed delete( string $where)

Deletes table rows matching a custom WHERE clause.
  • Return: Void on success or a PEAR_Error object on failure.
  • See: MDB2::exec()
  • See: DB::query()
  • Access: public

Parameters:

string   $where     The WHERE clause for the delete command.

[ Top ]

getBlankRow   [line 1858]

array getBlankRow( )

Returns a blank row array based on the column map.

The array keys are the column names, and all values are set to null.

  • Return: An associative array where the key is column name and the value is null.
  • Access: public

[ Top ]

getColumns   [line 944]

mixed getColumns( [mixed $col = null])

Returns all or part of the $this->col property array.
  • Return: All or part of the $this->col property array, or boolean false if no matching column names are found.
  • Access: public

Parameters:

mixed   $col     If null, returns the $this->col property array as it is. If string, returns that column name from the $this->col array. If an array, returns those columns named as the array values from the $this->col array as an array.

[ Top ]

getForm   [line 2428]

object HTML_QuickForm &getForm( [array $columns = null], [string $array_name = null], [array $args = array()], [string $clientValidate = null], [array $formFilters = null])

Creates and returns a QuickForm object based on table columns.

Parameters:

array   $columns     A sequential array of column names to use in the form; if null, uses all columns.
string   $array_name     By default, the form will use the names of the columns as the names of the form elements. If you pass $array_name, the column names will become keys in an array named for this parameter.
array   $args     

An associative array of optional arguments to pass to the QuickForm object. The keys are...

'formName' : String, name of the form; defaults to the name of this table.

'method' : String, form method; defaults to 'post'.

'action' : String, form action; defaults to $_SERVER['REQUEST_URI'].

'target' : String, form target target; defaults to '_self'

'attributes' : Associative array, extra attributes for <form> tag; the key is the attribute name and the value is attribute value.

'trackSubmit' : Boolean, whether to track if the form was submitted by adding a special hidden field

string   $clientValidate     By default, validation will match the 'qf_client' value from the column definition. However, if you set $clientValidate to true or false, this will override the value from the column definition.
array   $formFilters     An array with filter function names or callbacks that will be applied to all form elements.

[ Top ]

getFormElement   [line 2526]

object HTML_QuickForm_Element &getFormElement( string $column, string $elemname)

Creates and returns a single QuickForm element based on a DB_Table column name.

Parameters:

string   $column     A DB_Table column name.
string   $elemname     The name to use for the generated QuickForm element.

[ Top ]

getFormElements   [line 2557]

object HTML_QuickForm_Element &getFormElements( string $cols, [string $array_name = null])

Creates and returns an array of QuickForm elements based on a DB_Table column name.

Parameters:

string   $cols     Array of DB_Table column names
string   $array_name     The name to use for the generated QuickForm elements.

[ Top ]

getFormGroup   [line 2497]

array &getFormGroup( [array $columns = null], [string $array_name = null])

Creates and returns an array of QuickForm elements based on an array of DB_Table column names.
  • Return: An array of HTML_QuickForm_Element objects.
  • See: DB_Table_QuickForm
  • See: HTML_QuickForm
  • Access: public

Parameters:

array   $columns     A sequential array of column names to use in the form; if null, uses all columns.
string   $array_name     By default, the form will use the names of the columns as the names of the form elements. If you pass $array_name, the column names will become keys in an array named for this parameter.

[ Top ]

getIndexes   [line 994]

array getIndexes( [mixed $idx = null], string $col)

Returns all or part of the $this->idx property array.
  • Return: All or part of the $this->idx property array.
  • Access: public

Parameters:

string   $col     If specified, returns only this index key from the $this->col property array.

[ Top ]

getPHPTypeAndDBSyntax   [line 886]

array getPHPTypeAndDBSyntax( object &$db)

Detect values of 'phptype' and 'dbsyntax' keys of DSN.
  • Return: Values of 'phptype' and 'dbsyntax' keys of DSN.
  • Access: public

Parameters:

object   &$db     A PEAR DB/MDB2 object.

[ Top ]

insert   [line 1512]

mixed insert( array $data)

Inserts a single table row after validating through validInsert().
  • Return: Void on success, a PEAR_Error object on failure.
  • See: MDB2::autoExecute()
  • See: DB::autoExecute()
  • See: DB_Table::validInsert()
  • Access: public

Parameters:

array   $data     An associative array of key-value pairs where the key is the column name and the value is the column value. This is the data that will be inserted into the table. Data is checked against the column data type for validity.

[ Top ]

isRequired   [line 2367]

boolean isRequired( mixed $column)

Is a specific column required to be set and non-null?
  • Return: True if required, false if not.
  • Access: public

Parameters:

mixed   $column     The column to check against.

[ Top ]

isValid   [line 2279]

boolean isValid( array $val, array $col)

Checks if a value validates against the DB_Table data type for a given column. This only checks that it matches the data type; it does not do extended validation.
  • Return: True if the value validates (matches the data type), false if not.
  • See: DB_Table_Valid
  • Access: public

Parameters:

array   $val     A value to check against the column's DB_Table data type.
array   $col     A column name from $this->col.

[ Top ]

modeSupported   [line 837]

bool|object True modeSupported( string $mode, string $phptype)

Is a creation mode supported for a RDBMS by DB_Table?
  • Return: if supported, false if not, or a PEAR_Error if an unknown mode is specified.
  • Access: public

Parameters:

string   $mode     The chosen creation mode.
string   $phptype     The RDBMS type for PHP.

[ Top ]

nextID   [line 1795]

integer nextID( [string $seq_name = null])

Generates a sequence value; sequence name defaults to the table name.
  • Return: The next value in the sequence.
  • See: MDB2::nextID()
  • See: DB::nextID()
  • Access: public

Parameters:

string   $seq_name     The sequence name; defaults to table_id.

[ Top ]

quote   [line 1834]

string quote( mixed $val)

Escapes and enquotes a value for use in an SQL query.

Helps makes user input safe against SQL injection attack.

  • Return: The value with quotes escaped, and inside single quotes.
  • See: MDB2::quote()
  • See: DB_Common::quoteSmart()
  • Access: public

[ Top ]

recast   [line 1918]

void recast( array &$data)

Forces array elements to the proper types for their columns.

This will not valiate the data, and will forcibly change the data to match the recast-type.

The date, time, and timestamp recasting has special logic for arrays coming from an HTML_QuickForm object so that the arrays are converted into properly-formatted strings.

  • Access: public
  • Todo: If a column key holds an array of values (say from a multiple select) then this method will not work properly; it will recast the value to the string 'Array'. Is this bad?

Parameters:

array   &$data     The data array to re-cast.

[ Top ]

select   [line 1081]

mixed select( string $sqlkey, [string $filter = null], [string $order = null], [int $start = null], [int $count = null], [array $params = array()])

Selects rows from the table using one of the DB/MDB2 get*() methods.
  • Return: An array of records from the table (if anything but 'getOne'), a single value (if 'getOne'), or a PEAR_Error object.
  • See: MDB2::getOne()
  • See: DB::getOne()
  • See: DB::getRow()
  • See: MDB2::getRow()
  • See: DB_Table::_swapModes()
  • See: MDB2::getCol()
  • See: DB::getCol()
  • See: DB::getAll()
  • See: MDB2::getAll()
  • See: DB::getAssoc()
  • See: MDB2::getAssoc()
  • Access: public

Parameters:

string   $sqlkey     The name of the SQL SELECT to use from the $this->sql property array.
string   $filter     Ad-hoc SQL snippet to AND with the default SELECT WHERE clause.
string   $order     Ad-hoc SQL snippet to override the default SELECT ORDER BY clause.
int   $start     The row number to start listing from in the result set.
int   $count     The number of rows to list in the result set.
array   $params     Parameters to use in placeholder substitutions (if any).

[ Top ]

selectCount   [line 1277]

mixed selectCount( string $sqlkey, [string $filter = null], [string $order = null], [int $start = null], [int $count = null], [array $params = array()])

Counts the number of rows which will be returned by a query.

This function works identically to select(), but it returns the number of rows returned by a query instead of the query results themselves.

This makes using DB_Table with Pager easier, since you can pass the return value of this to Pager as totalItems, then select only the rows you need to display on a page.


Parameters:

string   $sqlkey     The name of the SQL SELECT to use from the $this->sql property array.
string   $filter     Ad-hoc SQL snippet to AND with the default SELECT WHERE clause.
string   $order     Ad-hoc SQL snippet to override the default SELECT ORDER BY clause.
int   $start     The row number to start listing from in the result set.
int   $count     The number of rows to list in the result set.
array   $params     Parameters to use in placeholder substitutions (if any).

[ Top ]

selectResult   [line 1184]

mixed selectResult( string $sqlkey, [string $filter = null], [string $order = null], [int $start = null], [int $count = null], [array $params = array()])

Selects rows from the table as a DB_Result/MDB2_Result_* object.
  • Return: A PEAR_Error on failure, or a DB_Result/MDB2_Result_* object on success.
  • See: DB_Table::_swapModes()
  • Access: public

Parameters:

string   $sqlkey     The name of the SQL SELECT to use from the $this->sql property array.
string   $filter     Ad-hoc SQL snippet to add to the default SELECT WHERE clause.
string   $order     Ad-hoc SQL snippet to override the default SELECT ORDER BY clause.
int   $start     The record number to start listing from in the result set.
int   $count     The number of records to list in the result set.
array   $params     Parameters to use in placeholder substitutions (if any).

[ Top ]

setErrorMessage   [line 917]

void setErrorMessage( mixed $code, [string $message = null])

Overwrite one or more error messages, e.g. to internationalize them.
  • Access: public

Parameters:

mixed   $code     If string, the error message with code $code will be overwritten by $message. If array, the error messages with code of each array key will be overwritten by the key's value.
string   $message     Only used if $key is not an array.

[ Top ]

supported   [line 811]

bool supported( string $phptype, [string $dbsyntax = ''])

Is a particular RDBMS supported by DB_Table?
  • Return: True if supported, false if not.
  • Access: public

Parameters:

string   $phptype     The RDBMS type for PHP.
string   $dbsyntax     The chosen database syntax.

[ Top ]

throwError   [line 662]

object PEAR_Error &throwError( string $code, [string $extra = null])

Specialized version of throwError() modeled on PEAR_Error.

Throws a PEAR_Error with a DB_Table error message based on a DB_Table constant error code.

  • Access: public

Parameters:

string   $code     A DB_Table error code constant.
string   $extra     Extra text for the error (in addition to the regular error message).

[ Top ]

update   [line 1644]

mixed update( array $data, string $where)

Updates table row(s) matching a custom WHERE clause, after checking against validUpdate().
  • Return: Void on success, a PEAR_Error object on failure.
  • See: MDB2::autoExecute()
  • See: DB::autoExecute()
  • See: DB_Table::validUpdate()
  • Access: public

Parameters:

array   $data     An associative array of key-value pairs where the key is the column name and the value is the column value. These are the columns that will be updated with new values.
string   $where     An SQL WHERE clause limiting which records are to be updated.

[ Top ]

validInsert   [line 1577]

mixed validInsert( array &$data)

Validates an array for insertion into the table.
  • Return: Boolean true on success, a PEAR_Error object on failure.
  • See: DB_Table::insert()
  • Access: public

Parameters:

array   $data     An associative array of key-value pairs where the key is the column name and the value is the column value. This is the data that will be inserted into the table. Data is checked against the column data type for validity.

[ Top ]

validUpdate   [line 1711]

mixed validUpdate( array &$data)

Validates an array for updating the table.
  • Return: Boolean true on success, a PEAR_Error object on failure.
  • See: DB_Table::update()
  • Access: public

Parameters:

array   $data     An associative array of key-value pairs where the key is the column name and the value is the column value. This is the data that will be inserted into the table. Data is checked against the column data type for validity.

[ Top ]

verify   [line 2251]

mixed verify( )

Verifies the table based on $this->col and $this->idx.
  • Return: Boolean true if the verification was successful, and a PEAR_Error if verification failed.
  • See: DB_Table_Manager::verify()
  • Access: public

[ Top ]

_getFormColDefs   [line 2582]

array _getFormColDefs( [string|array $column_set = null])

Creates a column definition array suitable for DB_Table_QuickForm.
  • Return: An array of columne defintions suitable for passing to DB_Table_QuickForm.
  • Access: public

Parameters:

string|array   $column_set     A string column name, a sequential array of columns names, or an associative array where the key is a column name and the value is the default value for the generated form element. If null, uses all columns for this class.

[ Top ]


Documentation generated on Wed, 19 Apr 2006 15:03:06 -0400 by phpDocumentor 1.2.3. PEAR Logo Copyright © PHP Group 2004.