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

Class: DB_Table

Source Location: /DB_Table-1.5.6/DB/Table.php

Class Overview

DB_Table_Base
   |
   --DB_Table

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


Author(s):

Version:

  • Release: 1.5.6

Variables

Methods


Inherited Variables

Inherited Methods

Class: DB_Table_Base

DB_Table_Base::buildFilter()
Returns SQL condition equating columns to literal values.
DB_Table_Base::buildSQL()
Returns SQL SELECT string constructed from sql query array
DB_Table_Base::select()
Selects rows using one of the DB/MDB2 get*() methods.
DB_Table_Base::selectCount()
Counts the number of rows which will be returned by a query.
DB_Table_Base::selectResult()
Selects rows as a DB_Result/MDB2_Result_* object.
DB_Table_Base::setErrorMessage()
Overwrites one or more error messages, e.g., to internationalize them.
DB_Table_Base::throwError()
Specialized version of throwError() modeled on PEAR_Error.

Class Details

[line 528]
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

$auto_inc_col =  null

[line 575]

Name of an auto-increment column, if any. Null otherwise.

A table can contain at most one auto-increment column. Auto-incrementing is implemented in the insert() method, using a sequence accessed by the nextID() method.

  • Access: public

Type:   string


[ Top ]

$col = array()

[line 554]

Associative array of column definitions.
  • Access: public

Type:   array


[ Top ]

$idx = array()

[line 563]

Associative array of index definitions.
  • Access: public

Type:   array


[ Top ]

$table =  null

[line 537]

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

Type:   string


[ Top ]



Method Detail

DB_Table (Constructor)   [line 647]

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

Constructor.

The constructor returns a DB_Table object that wraps an instance $db DB or MDB2, and that binds to a specific database table named $table. It can optionally create the database table or verify that its schema matches that declared in the $col and $idx parameters, depending on the value of the $create parameter.

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 2065]

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

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

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.


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     Name of array of column names
clientValidate   $clientValidate     

[ Top ]

addStaticFormElements   [line 2088]

void addStaticFormElements( object &$form)

Adds static form elements like 'header', 'static', 'submit' or 'reset' to a pre-existing HTML_QuickForm object. The form elements needs to be defined in a property called $frm.

Parameters:

object   &$form     An HTML_QuickForm object.

[ Top ]

alter   [line 1822]

boolean alter( )

Alters the table to match schema declared in $this->col and $this->idx.

If the table does not exist, create it instead.


[ Top ]

autoRecast   [line 1492]

void autoRecast( [bool $flag = true])

Turns on (or off) automatic recasting of insert and update data.

Turns on (if $flag is true) or off (if $flag is false) automatic forcible recasting of data to the declared data type, if required, prior to inserting or updating. The recasting is done by calling the DB_Table::recast() method from within the DB_Table::insert() and DB_Table::update().

  • Access: public

Parameters:

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

[ Top ]

autoValidInsert   [line 1100]

void autoValidInsert( [bool $flag = true])

Turns on (or off) automatic validation of inserted data.

Enables (if $flag is true) or disables (if $flag is false) automatic validation of data types prior to actual insertion into the database by the DB_Table::insert() method.

  • Access: public

Parameters:

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

[ Top ]

autoValidUpdate   [line 1264]

void autoValidUpdate( [bool $flag = true])

Turns on (or off) automatic validation of updated data.

Enables (if $flag is true) or disables (if $flag is false) automatic validation of data types prior to updating rows in the database by the update() method.

  • Access: public

Parameters:

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

[ Top ]

create   [line 1752]

mixed create( string $flag)

Creates the table based on $this->col and $this->idx.
  • Return: Boolean true if the table was successfully created, false if there was no need to create the table, or a PEAR_Error if the attempted creation failed.
  • See: DB_Table_Manager::create()
  • See: DB_Table_Manager::tableExists()
  • Throws: PEAR_Error if
    • DB_Table_Manager::tableExists() returns Error (bubbles up)
    • DB_Table_Manager::create() returns Error (bubbles up)
  • Access: public

Parameters:

string   $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 1357]

mixed delete( string $where)

Deletes table rows matching a custom WHERE clause.

Constructs and submits and SQL DELETE command with the specified WHERE clause. Command is submitted by DB::query() or MDB2::exec().

If a reference to a DB_Table_Database instance exists, carry out any ON DELETE actions declared in that instance before actual insertion, if emulation of ON DELETE actions is enabled in that instance.

  • Return: void on success (PEAR_Error on failure)
  • See: MDB2::exec()
  • See: DB::query()
  • Throws: PEAR_Error if DB::query() or MDB2::exec() returns error (bubbles up)
  • Access: public

Parameters:

string   $where     Logical condition in the WHERE clause of the delete command.

[ Top ]

getBlankRow   [line 1465]

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 keys are column names and all values are null.
  • Access: public

[ Top ]

getColumns   [line 844]

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 2030]

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 2140]

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 2166]

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

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

Parameters:

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

[ Top ]

getFormGroup   [line 2115]

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 892]

mixed getIndexes( [mixed $idx = null])

Returns all or part of the $this->idx property array.
  • Return: All or part of the $this->idx property array, or boolean false if $idx is not null but invalid
  • Access: public

Parameters:

mixed   $idx     Index name (key in $this->idx), or array of index name strings.

[ Top ]

insert   [line 988]

mixed insert( array $data)

Inserts a single table row.

Inserts data from associative array $data, in which keys are column names and values are column values. All required columns (except an auto-increment column) must be included in the data array. Columns values that are not set or null are inserted as SQL NULL values.

If an auto-increment column is declared (by setting $this->auto_inc_col), and the value of that column in $data is not set or null, then a new sequence value will be generated and inserted.

If auto-recasting is enabled (if $this->_auto_recast), the method will try, if necessary to recast $data to proper column types, with recast().

If auto-validation is enabled (if $this->_valid_insert), the method will validates column types with validInsert() before insertion.

  • Return: Void on success (PEAR_Error on failure)
  • See: MDB2::autoExecute()
  • See: DB::autoExecute()
  • See: DB_Table::validInsert()
  • Throws: PEAR_Error if:
    • Error in auto_inc_col declaration (DB_TABLE_ERR_AUTO_INC_COL)
    • Error returned by DB/MDB2::autoExecute() (Error bubbled up)
  • 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.

[ Top ]

isRequired   [line 1972]

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 1889]

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 $val validates against data type, false if not
  • See: DB_Table_Valid
  • Throws: PEAR_Error if Invalid column type in $this->col (DB_TABLE_ERR_VALIDATE_TYPE)
  • 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 774]

bool modeSupported( string $mode, string $phptype)

Is a creation mode supported for a RDBMS by DB_Table?
  • Return: True if supported, false if not (PEAR_Error on failure)
  • Throws: PEAR_Error if Unknown creation mode is specified (DB_TABLE_ERR_CREATE_FLAG)
  • Access: public

Parameters:

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

[ Top ]

nextID   [line 1400]

integer nextID( [string $seq_name = null])

Generates and returns a sequence value.

Generates a sequence value by calling the DB or MDB2::nextID() method. The sequence name defaults to the table name, or may be specified explicitly.

  • Return: The next value in the sequence (PEAR_Error on failure)
  • See: MDB2::nextID()
  • See: DB::nextID()
  • Throws: PEAR_Error if Sequence name too long (>26 char + _seq) (DB_TABLE_ERR_SEQ_STRLEN)
  • Access: public

Parameters:

string   $seq_name     The sequence name; defaults to table_id.

[ Top ]

quote   [line 1445]

string quote( mixed $val)

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

Simple wrapper for DB_Common::quoteSmart() or MDB2::quote(), which returns the value of one of these functions. Helps makes user input safe against SQL injection attack.

  • Return: The value with quotes escaped, inside single quotes if non-numeric.
  • See: MDB2::quote()
  • See: DB_Common::quoteSmart()
  • Throws: PEAR_Error if DB_Common::quoteSmart() or MDB2::quote() returns Error (bubbled up)
  • Access: public

Parameters:

mixed   $val     The value to be quoted

[ Top ]

recast   [line 1522]

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.

  • 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?
  • Access: public

Parameters:

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

[ Top ]

setAutoInc   [line 1079]

void setAutoInc( [bool $flag = true])

Turns on or off auto-incrementing of $auto_inc_col column (if any)

For auto-incrementing to work, an $auto_inc_col column must be declared, auto-incrementing must be enabled (by this method), and the value of the $auto_inc_col column must be not set or null in the $data passed to the insert method.

  • Access: public

Parameters:

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

[ Top ]

setDatabaseInstance   [line 944]

void setDatabaseInstance( object &$database)

Connect or disconnect a DB_Table_Database instance to this table instance.

Used to re-connect this DB_Table object to a parent DB_Table_Database object during unserialization. Can also disconnect if the $database parameter is null. Use the DB_Table_Database::addTable method instead to add a table to a new DB_Table_Database.

  • Access: public

Parameters:

object   &$database     DB_Table_Database instance that this table belongs to (or null to disconnect from instance).

[ Top ]

setErrorMessage   [line 820]

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

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

Overrides DB_Table_Base::setErrorMessage() (Overwrites one or more error messages, e.g., to internationalize them.)

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 751]

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 ]

toXML   [line 2235]

string toXML( [string $indent = ''])

Returns XML string representation of the table
  • Return: XML string
  • Access: public

Parameters:

string   $indent     string of whitespace

[ Top ]

update   [line 1204]

mixed update( array $data, string $where)

Update table row or rows that match a custom WHERE clause

Constructs and submits an SQL UPDATE command to update columns whose names are keys in the $data array parameter, in all rows that match the logical condition given by the $where string parameter.

If auto-recasting is enabled (if $this->_auto_recast), update() will try, if necessary, to recast $data to proper column types, with recast().

If auto-validation is enabled (if $this->_valid_insert), update() validates column types with validUpdate() before insertion.

  • Return: Void on success, a PEAR_Error object on failure.
  • See: MDB2::autoExecute()
  • See: DB::autoExecute()
  • See: DB_Table::validUpdate()
  • Throws: PEAR_Error if:
    • Data fails type validation (bubbles error returned by validUpdate)
    • Error thrown by DB/MDB2::autoexecute()
  • 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 are to be updated.

[ Top ]

validInsert   [line 1129]

boolean validInsert( &$data, array $data)

Validates an array for insertion into the table.
  • Return: true on success (PEAR_Error on failure)
  • See: DB_Table::insert()
  • Throws: PEAR_Error if:
    • Invalid column name key in $data (DB_TABLE_ERR_INS_COL_NOMAP)
    • Missing required column value (DB_TABLE_ERR_INS_COL_NOMAP)
    • Column value doesn't match type (DB_TABLE_ERR_INS_DATA_INVALID)
  • 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.
   &$data     

[ Top ]

validUpdate   [line 1293]

mixed validUpdate( &$data, array $data)

Validates an array for updating the table.
  • Return: Boolean true on success (PEAR_Error object on failure)
  • See: DB_Table::update()
  • Throws: PEAR_Error if
    • Invalid column name key in $data (DB_TABLE_ERR_UPD_COL_NOMAP)
    • Missing required column value (DB_TABLE_ERR_UPD_COL_NOMAP)
    • Column value doesn't match type (DB_TABLE_ERR_UPD_DATA_INVALID)
  • 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.
   &$data     

[ Top ]

verify   [line 1862]

boolean verify( )

Verifies the table based on $this->col and $this->idx.
  • Return: true if verification succees (PEAR_Error on failure).
  • See: DB_Table_Manager::verify()
  • Throws: PEAR_Error if DB_Table_Manager::verify() returns Error (bubbles up)
  • Access: public

[ Top ]

_getFormColDefs   [line 2188]

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

Creates a column definition array suitable for DB_Table_QuickForm.
  • Return: An array of column 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 Thu, 25 Dec 2008 15:00:35 -0500 by phpDocumentor 1.4.0. PEAR Logo Copyright © PHP Group 2004.