Class: DB_Table_Database
Source Location: /DB_Table-1.5.0RC1/DB/Table/Database.php
Relational database abstraction class
Author(s):
|
|
|
Inherited Variables
|
Inherited Methods
|
Class Details
Class Variables
Method Detail
DB_Table_Database (Constructor) [line 667]
Constructor If an error is encountered during instantiation, the error message is stored in the $this->error property of the resulting object. See $error property docblock for a discussion of error handling.
Parameters:
addAllLinks [line 1757]
Adds all possible linking tables to the $_link property array Identifies all potential linking tables in the datbase, and adds them all to the $_link property. Table $link is taken to be a link between tables $table1 and $table2 if it contains foreign key references to both $table1 and $table2.
addLink [line 1685]
mixed addLink(
string
$table1, string
$table2, string
$link)
|
|
Identifies a linking/association table that links two others Adds table name $link to $this->_link[$table1][$table2] and to $this->_link[$table2][$table1]. Returns true on success, and PEAR error on failure. Returns the following DB_TABLE_DATABASE_ERR_* error codes if: - $ftable does not exist ( _NO_FTABLE )
- $rtable does not exist ( _NO_RTABLE )
Parameters:
addRef [line 1373]
mixed addRef(
string
$ftable, mixed
$fkey, string
$rtable, [mixed
$rkey = null], [string
$on_delete = null], [string
$on_update = null])
|
|
Adds a foreign key reference to the database. Adds a reference from foreign key $fkey of table $ftable to referenced key $rkey of table named $rtable to the $this->_ref property. The values of $fkey and $rkey (if not null) may either both be column name strings or they may both be numerically indexed arrays of corresponding column names. If $rkey is null (the default), the referenced key taken to be the primary key of of $rtable. The $on_delete and $on_update actions may each have string values 'restrict', 'cascade', 'set null', or 'set default', or (by default) PHP null. PHP null value signifies that no action is taken on deletion or updating of a referenced row to maintain foreign key integrity. There may no more than one reference from a table to another, though reference may contain multiple columns. Returns true on success, and PEAR error on failure. Returns the following DB_TABLE_DATABASE_ERR_* error codes if: - $ftable does not exist ( _NO_FTABLE )
- $rtable does not exist ( _NO_RTABLE )
- $rkey is null and $rtable has no primary key ( _NO_PKEY )
- $fkey is neither a string nor an array ( _FKEY )
- $rkey is not a string, $fkey is a string ( _RKEY_NOT_STRING )
- $rkey is not an array, $fkey is an array ( _RKEY_NOT_ARRAY )
- A column of $fkey does not exist ( _NO_FCOL )
- A column of $rkey does not exist ( _NO_RCOL )
- A column of $fkey and $rkey have different types ( _REF_TYPE )
- A reference from $ftable to $rtable already exists ( _MULT_REF )
Parameters:
addTable [line 1210]
mixed addTable(
&$table_obj, object
$table_obj)
|
|
Adds a table to the database. Creates references between $this DB_Table_Database object and the child DB_Table object, by adding a reference to $table_obj to the $this->_table array, and setting $table_obj->database = $this. Adds the primary key to $this->_primary_key array. The relevant element of $this->_primary_key is set to null if no primary key index is declared. Returns an error if more than one primary key is declared. Returns true on success, and PEAR error on failure. Returns the following DB_TABLE_DATABASE_ERR_* error codes if: - $table_obj is not a DB_Table ( _DBTABLE_OBJECT )
- more than one primary key is defined ( _ERR_MULT_PKEY )
Parameters:
autoInc [line 2315]
void autoInc(
[bool
$flag = true])
|
|
Turns on (or off) php implementation of auto-incrementing on insertion for all tables
Parameters:
autoJoin [line 2836]
array autoJoin(
[array
$cols = null], [array
$tables = null], [array
$filter = null])
|
|
Builds a select command involving joined tables from a list of column names and/or a list of table names. Returns an query array of the form used in $this->buildSQL, constructed on the basis of a sequential array $cols of column names and/or a sequential array $tables of table names. The 'FROM' clause in the resulting SQL contains all the table listed in the $tables parameter and all those containing the columns listed in the $cols array, as well as any linking tables required to establish many to many relationships between these tables. The 'WHERE' clause is constructed so as to create an inner join of these tables. The $cols parameter is a sequential array in which the values are column names. Column names may be qualified by a table name, using the SQL table.column syntax, but need not be qualified if they are unambiguous. The values in $cols can only be column names, and may not be functions or more complicated SQL expressions. If cols is null, the resulting SQL command will start with 'SELECT * FROM ...' . The $tables parameter is a sequential array in which the values are table names. If $tables is null, the FROM clause is constructed from the tables containing the columns in the $cols. The $params array is an associative array can have 'filter', and 'order' keys, which are both optional. A value $params['filter'] is an condition string to add (i.e., AND) to the automatically constructed set of join conditions. A value $params['order'] is an SQL 'ORDER BY' clause, with no 'ORDER BY' prefix. The function returns an associative array with keys ('select', 'from', 'where', ['order']), for which the associated values are strings containing the SELECT, FROM, WHERE and (optionally) ORDER BY clauses of the select statement. The entire SELECT command string can be obtained by passing the resulting array to the buildSQL method.
Parameters:
autoRecast [line 2300]
void autoRecast(
[bool
$flag = true])
|
|
Turns on (or off) automatic recasting of insert and update data for all tables
Parameters:
autoValidInsert [line 2074]
void autoValidInsert(
[bool
$flag = true])
|
|
Turns on or off automatic validation of inserted data for all tables
Parameters:
autoValidUpdate [line 2284]
void autoValidUpdate(
[bool
$flag = true])
|
|
Turns on (or off) automatic validation of updated data for all tables.
Parameters:
buildFilter [line 3198]
string buildFilter(
array
$data, [mixed
$data_key = null], [
$filt_key = null], [
$match = 'simple'])
|
|
Returns WHERE clause equating values of $data array to database column values Usage: In the simplest usage of this method, which is obtained when both $data_key and $filt_key are null or absent, the method returns an SQL logical expression that equates the values of $data to the values of database columns whose names are given by the keys of $data. In the general case, function is designed to return an SQL logical expression that equates the values of a set of foreign key columns in associative array $data, which is a row to be inserted or updated in one table, to the values of the corresponding columns of a referenced table. In this usage, $data_key is the foreign key (a column name or numerical array of column names), and $filt_key is the corresponding referenced key. Parameters: Parameter $data is an associative array containing data to be inserted into or used to update one row of a database table, in which array keys are column names. When present, $data_key contains either the name of a single array key of interest, or a numerical array of such keys. These are usually the names of the columns of a foreign key in that table. When, $data_key is null or absent, it is taken to be equal to an array containing all of the keys of $data. When present, $filt_key contains either a string or a numerical array of strings that are aliases for the keys in $data_key. These are usually the names of the corresponding columns in the referenced table. When $filt_key is null or absent, it is equated with $data_key internally. The function returns an SQL logical expression that equates the values in $data whose keys are specified by $data_key, to the values of database columns whose names are specified in $filt_key. Simple case: If parameters $data_key and $filt_key are null, and $data = array( 'c1' => $v1, 'c2' => $v2, 'c3' => $v3)
"c1 => $val1 AND c2 => $val2 AND c3 = $v3"
General case: Buildfilter returns a SQL logical exprssion that equates the values of $data whose keys are given in $data_key with the values values of database columns with names given in $filt_key. For example, if $data = array( 'k1' => $v1, 'k2' => $v2, ... , 'k10' => $v10 ); $data_key = array('k2', 'k5', 'k7'); $filt_key = array('c2', 'c5', 'c7');
"c2 = $v2 AND c5 = $v5 AND c7 = $v7"
"c5 = $v5"
Quoting is done by the DB_Table_Database::quote() method, based on the php type of the values in $array. The treatment of null values in $data depends upon the value of the $match parameter. Null values: The treatment to null values in $data depends upon the value of the $match parameter . If $match == 'simple', an empty string is returned if any $value of $data with a key in $data_key is null. If $match == 'partial', the returned SQL expression equates only the relevant non-null values of $data to the values of corresponding database columns. If $match == 'full', the function returns an empty string if all of the relevant values of data are null, and returns a PEAR Error if some of the selected values are null and others are not null.
Parameters:
buildSQL [line 2473]
string buildSQL(
mixed
$sql_key, [
$filter = null], [
$order = null], [
$start = null], [
$count = null])
|
|
Returns SQL select string constructed from sql map array
Parameters:
createTables [line 1950]
mixed createTables(
[mixed
$flag = 'safe'])
|
|
Creates all the tables in a database in a RDBMS Note: this method creates all the tables in a database, but does NOT create the parent database or set it to the current or default database -- the database must exist before the method is called. If creation of any table fails, the method immediately returns the PEAR error returned by DB_Table::create($flag).
Parameters:
delete [line 2334]
mixed delete(
string
$table_name, string
$where)
|
|
Deletes all row(s) of table that match a custom where clause. Implements any required 'on_delete' action on tables that reference the table from which rows are deleted.
Parameters:
deleteLink [line 1801]
void deleteLink(
string
$table1, string
$table2, [string
$link = null])
|
|
Removes a link between two tables from the $_link property If $link is not null, remove table $link from the list of links between $table1 and $table2, if present. If $link is null, delete all links between $table1 and $table2.
Parameters:
deleteRef [line 1542]
void deleteRef(
$ftable
$ftable, $rtable
$rtable)
|
|
Deletes one reference from database model Removes reference from referencing (foreign key) table named $ftable to referenced table named $rtable. Unsets relevant elements of the $ref, $_ref_to, and $_link property arrays, and removes the foreign key columns of $ftable from the $_foreign_col property. Does nothing, silently, if no such reference exists, i.e., if $this->_ref[$ftable][$rtable] is not set.
Parameters:
deleteTable [line 1277]
void deleteTable(
string
$table)
|
|
Deletes a table from $this database object. Removes all dependencies on $table from the database model. The table is removed from $_table and $_primary_key properties. Its columns are removed from the $_col and $_foreign_col properties. References to and from the table are removed from the $_ref, $_ref_to, and $_link properties. Referencing columns are removed from $_foreign_col.
Parameters:
fromXML [line 3413]
Returns a DB_Table_Database object constructed from an XML string Uses the MDB2 XML schema for a database element, including a new syntax for foreign key indices. NOTE: This function requires PHP 5. It throws an error if used with PHP 4.
Parameters:
getCol [line 951]
mixed getCol(
[string
$column_name = null])
|
|
Returns all or part of the $_col property array If $column_name is null, return $_col property array If $column_name is valid, return $_col[$column_name] subarray Returns a PEAR Error with the following DB_TABLE_DATABASE_* error codes if: - $column_name is not a string ( _COL_NOT_STRING )
- $column_name is not valid column name ( _NO_COL )
Parameters:
getDBInstance [line 830]
object reference &getDBInstance(
)
|
|
Return reference to $this->_db DB/MDB2 object
getForeignCol [line 985]
array getForeignCol(
[string
$column_name = null])
|
|
Returns all or part of the $_foreign_col property array If $column_name is null, return $this->_foreign_col property array If $column_name is valid, return $this->_foreign_col[$column_name] Returns a PEAR Error with the following DB_TABLE_DATABASE_* error codes if: - $column_name is not a string ( _COL_NOT_STRING )
- $column_name is not valid foreign column name ( _NO_FOREIGN_COL )
Parameters:
getLink [line 1132]
mixed getLink(
[string
$table1 = null], [string
$table2 = null])
|
|
Returns all or part of the $link two-dimensional property array Returns $this->_link 2D property array if $table1 and $table2 are null. Returns $this->_link[$table1] subarray if only $table2 is null. Returns $this->_link[$table1][$table2] if both parameters are present. Returns null if $table1 is a valid table with links to no others, or if $table1 and $table2 are both valid table names but there is no link between them. Returns a PEAR Error with the following DB_TABLE_DATABASE_* error codes if $table1 or $table2 is not null and: - $table1 or $table2 is not a string ( _TBL_NOT_STRING )
- $table1 or $table2 is not a valid table name ( _NO_TBL )
Parameters:
getPrimaryKey [line 883]
mixed getPrimaryKey(
[
$name = null])
|
|
Returns all or part of the $_primary_key property array If $name is null, return the $this->_primary_key array If $name is a table name, return $this->_primary_key[$name] Returns PEAR Error with the following DB_TABLE_DATABASE_* error codes if: - $name is not a string ( _TBL_NOT_STRING )
- $name is not valid table name ( _NO_TBL )
Parameters:
getRef [line 1025]
mixed getRef(
[string
$table1 = null], [string
$table2 = null])
|
|
Returns all or part of the $ref two-dimensional property array Returns $this->_ref 2D property array if $table1 and $table2 are null. Returns $this->_ref[$table1] subarray if only $table2 is null. Returns $this->_ref[$table1][$table2] if both parameters are present. Returns null if $table1 is a table that references no others, or if $table1 and $table2 are both valid table names, but there is no reference from $table1 to $table2. Returns a PEAR Error with the following DB_TABLE_DATABASE_* error codes if: - $table1 or $table2 is not a string ( _TBL_NOT_STRING )
- $table1 or $table2 is not a valid table name ( _NO_TBL )
Parameters:
getRefTo [line 1086]
mixed getRefTo(
[string
$table_name = null])
|
|
Returns all or part of the $ref_to property array Returns $this->_ref_to property array if $table_name is null. Returns $this->_ref_to[$table_name] if $table_name is not null. Returns a PEAR Error with the following DB_TABLE_DATABASE_* error codes if: - $table_name is not a string ( _TBL_NOT_STRING )
- $table_name is not a valid table name ( _NO_TBL )
Parameters:
getTable [line 850]
mixed getTable(
[
$name = null])
|
|
Returns all or part of $_table property array If $name is absent or null, return entire $_table property array. If $name is a table name, return $this->_table[$name] DB_Table object reference Returns PEAR Error with the following DB_TABLE_DATABASE_* error codes if: - $name is not a string ( *_TBL_NOT_STRING )
- $name is not valid table name ( *_NO_TBL )
Parameters:
getTableSubclass [line 916]
mixed getTableSubclass(
[
$name = null])
|
|
Returns all or part of the $_table_subclass property array If $name is null, return the $this->_table_subclass array If $name is a table name, return $this->_table_subclass[$name] Returns PEAR Error with the following DB_TABLE_DATABASE_* error codes if: - $name is not a string ( _TBL_NOT_STRING )
- $name is not valid table name ( _NO_TBL )
Parameters:
insert [line 2031]
mixed insert(
string
$table_name, array
$data)
|
|
Inserts a single table row Wrapper for insert method of the corresponding DB_Table object.
Parameters:
quote [line 3311]
string quote(
mixed
$value)
|
|
Returns SQL literal string representation of a php value If $value is: - a string, return the string enquoted and escaped
- a number, return cast of number to string, without quotes
- a boolean, return '1' for true and '0' for false
- null, return the string 'NULL'
Parameters:
select [line 2556]
mixed select(
string
$sql_key, [string
$filter = null], [string
$order = null], [int
$start = null], [int
$count = null], [array
$params = array()])
|
|
Selects rows using one of the DB/MDB2 get*() methods.
Parameters:
selectCount [line 2728]
int selectCount(
string
$sql_key, [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.
Parameters:
selectResult [line 2648]
mixed selectResult(
string
$sql_key, [string
$filter = null], [string
$order = null], [int
$start = null], [int
$count = null], [array
$params = array()])
|
|
Selects rows as a DB_Result/MDB2_Result_* object.
Parameters:
setActOnDelete [line 783]
void setActOnDelete(
[bool
$flag = true])
|
|
Turns on (or off) automatic php emulation of on delete actions
Parameters:
setActOnUpdate [line 799]
void setActOnUpdate(
[bool
$flag = true])
|
|
Turns on (or off) automatic php emulation of on update actions
Parameters:
setCheckFKey [line 815]
void setCheckFKey(
[bool
$flag = true])
|
|
Turns on (or off) validation of foreign key values on insert and update
Parameters:
setDBconnection [line 753]
mixed setDBconnection(
&$db, object
$db)
|
|
Set DB/MDB2 connection instance for database and all tables Assign a reference to the DB/MDB2 object $db to $this->_db, set $this->_backend to 'db' or 'mdb2' accordingly, and set the same pair of values for the $db and $backend properties of every DB_Table object in the database. Returns true on success, and PEAR error on failure. Returns error code DB_TABLE_DATABASE_ERR_DB_OBJECT if $db is not a DB or MDB2 object.
Parameters:
setErrorMessage [line 727]
void setErrorMessage(
mixed
$code, [string
$message = null])
|
|
Overwrites one or more error messages, e.g., to internationalize them.
Parameters:
setOnDelete [line 1621]
mixed setOnDelete(
string
$ftable, string
$rtable, string
$action)
|
|
Modifies the on delete action for one foreign key reference. Modifies the value of the on_delete action associated with a reference from $ftable to $rtable. The parameter action may be one of the action strings 'cascade', 'restrict', 'set null', or 'set default', or it may be php null. A null value of $action indicates that no action should be taken upon deletion of a referenced row. Returns true on success, and PEAR error on failure. Returns the error code DB_TABLE_DATABASE_ERR_REF_TRIG_ACTION if $action is a neither a valid action string nor null. Returns true, and does nothing, if $this->_ref[$ftable][$rtable] is not set.
Parameters:
setOnUpdate [line 1650]
mixed setOnUpdate(
string
$ftable, string
$rtable, array
$action)
|
|
Modifies on update action for one foreign key reference. Similar to setOnDelete. See setOnDelete for further details.
Parameters:
setTableSubclassPath [line 1184]
void setTableSubclassPath(
string
$path)
|
|
Sets the $_table_subclass_path property string
Parameters:
throwError [line 700]
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_Database error message based on a DB_Table_Database constant error code.
Parameters:
toXML [line 3390]
string toXML(
[string
$indent = ''])
|
|
Returns XML string representation of database declaration
Parameters:
update [line 2096]
mixed update(
string
$table_name, array
$data, string
$where)
|
|
Updates all row(s) of table that match a custom where clause. Data can be validated before insertion using validUpdate(). Implements any required 'on_update' actions on referencing tables that reference columns of updated rows
Parameters:
validCol [line 1876]
array validCol(
string
$col, [array
$from = null])
|
|
Validates and (if necessary) disambiguates a column name. The parameter $col is a string may be either a column name or a column name qualified by a table name, using the SQL syntax "$table.$column". If $col contains a table name, and is valid, an array($table, $column) is returned. If $col is not qualified by a column name, an array array($table, $column) is returned, in which $table is either the name of one table, or an array containing the names of two or more tables containing a column named $col. The $from parameter, if present, is a numerical array of names of tables with which $col should be associated, if no explicit table name is provided, and if possible. If one or more of the tables in $from contains a column $col, the returned table or set of tables is restricted to those in array $from. If the table name remains ambiguous after testing for tables in the $from set, and $col is not a foreign key in one or more of the remaining tables, the returned table or set of tables is restricted to those in which $col is not a foreign key. Returns a PEAR Error with the following DB_TABLE_DATABASE_ERR_* error codes if: - column $col does not exist in the database ( _NO_COL_DB )
- column $col does not exist in the specified table ( _NO_COL_TBL )
Parameters:
validForeignKeys [line 1982]
bool validForeignKeys(
$table_name
$table_name, @data
$data)
|
|
Check validity of any foreign key values in associative array $data containing values to be inserted or updated in table $table_name. Returns true if each foreign key in $data matches a row in the referenced table, or if there are no foreign key columns in $data. Returns false if any foreign key column in associative array $data (which may contain a full or partial row of $table_name), does not match the the value of the referenced column in any row of the referenced table. Returns any PEAR error thrown by the select method, which is called to implement the required query, or by the buildFilter method.
Parameters:
__sleep [line 3330]
Serializes all table references and sets $db = null, $backend = null
__wakeup [line 3363]
Unserializes child DB_Table objects Immediately after unserialization, a DB_Table_Databse object has null $_db and $_backend properties, and each of its child DB_Table objects has null $db and $backend properties. The DB_Table_Database::setDB method should be called immediately after unserialization to re-establish the database connection, like so:
$db_object->setDB($conn);
Documentation generated on Mon, 11 Mar 2019 14:56:29 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.
|
|
