DB_Table_Database (Constructor) [line 625]
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 1897]
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 1822]
boolean 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 1499]
boolean 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 (for single column keys) or they may both be numerically indexed arrays of corresponding column names (for multi-column keys). If $rkey is null (the default), the referenced key taken to be the primary key of $rtable, if any.
The $on_delete and $on_update parameters may be either be null, or may have string values 'restrict', 'cascade', 'set null', or 'set default' that indicate referentially triggered actions to be taken deletion or updating of referenced row in $rtable. Each of these actions corresponds to a standard SQL action (e.g., cascading delete) that may be taken upon referencing rows of table $ftable when a referenced row of $rtable is deleted or updated. A PHP null value for either parameter (the default) signifies that no such action will be taken upon deletion or updating.
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 1325]
boolean addTable(
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 2507]
void autoInc(
[bool
$flag = true])
|
|
Turns on (or off) php implementation of auto-incrementing on insertion for all tables
Parameters:
autoJoin [line 2780]
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 2489]
void autoRecast(
[bool
$flag = true])
|
|
Turns on (or off) automatic recasting of insert and update data for all tables
Parameters:
autoValidInsert [line 2227]
void autoValidInsert(
[bool
$flag = true])
|
|
Turns on or off automatic validation of inserted data for all tables
Parameters:
autoValidUpdate [line 2289]
void autoValidUpdate(
[bool
$flag = true])
|
|
Turns on (or off) automatic validation of updated data for all tables.
Parameters:
createTables [line 2098]
boolean 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 2531]
boolean delete(
string
$table_name, string
$where)
|
|
Deletes all row(s) of table that match a custom where clause.
Wrapper for insert method of the corresponding DB_Table object.
Implements any required ON DELETE action on tables that reference deleted rows, if on delete actions are enabled.
Parameters:
deleteLink [line 1944]
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 1670]
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 1395]
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 3324]
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 963]
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
The $_col property is an associative array in which each key is the name of a column in the database, and each value is a numerical array containing the names of all tables that contain a column with that name.
Parameters:
getDBInstance [line 790]
object Reference &getDBInstance(
)
|
|
Return reference to $this->db DB/MDB2 object wrapped by $this
getForeignCol [line 1010]
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]
The $_foreign_col property is an associative array in which each key is the name string of a foreign key column, and each value is a sequential array containing the names of all tables that contain a foreign key column with that name.
If a column $column in a referencing table $ftable is part of the foreign key for references to two or more different referenced tables tables, the name $ftable will also appear multiple times in the array $this->_foreign_col[$column].
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 1221]
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.
The $_link property is a two-dimensional associative array with elements of the form $this->_link[$table1][$table2] = array($link1, ...), in which the value is an array containing the names of all tables that `link' tables named $table1 and $table2, and thereby create a many-to-many relationship between these two tables.
The $_link property is used in the autoJoin method to join tables that are related by a many-to-many relationship via a linking table, rather than via a direct foreign key reference. A table that is declared to be linking table for tables $table1 and $table2 must contain foreign keys that reference both of these tables.
Each binary link in a database is listed twice in $_link, in $_link[$table1][$table2] and in $_link[$table2][$table1]. If a linking table contains foreign key references to N tables, with N > 2, each of the resulting binary links is listed separately. For example, a table with references to 3 tables A, B, and C can create three binary links (AB, AC, and BC) and six entries in the link property array (i.e., in $_link[A][B], $_link[B][A], ... ).
Linking tables may be added to the $_link property by using the addLink method or deleted using the delLink method. Alternatively, all possible linking tables can be identified and added to the $_link array at once by the addAllLinks() method.
Parameters:
getPrimaryKey [line 863]
mixed getPrimaryKey(
[string
$name = null])
|
|
Returns all or part of the $_primary_key property array
If $name is null, return the $this->_primary_key property array If $name is a table name, return $this->_primary_key[$name]
The $_primary_key property is an associative array in which each key a table name, and each value is the primary key of that table. Each primary key value may be a column name string, a sequential array of column name strings (for a multi-column key), or null (if no primary key has been declared).
Parameters:
getRef [line 1074]
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.
The $_ref property is a two-dimensional associative array in which the keys are pairs of table names, each value is an array containing information about referenced and referencing keys, and referentially triggered actions (if any). An element of the $_ref array is of the form $ref[$ftable][$rtable] = $reference, where $ftable is the name of a referencing (or foreign key) table and $rtable is the name of a corresponding referenced table. The value $reference is an array $reference = array($fkey, $rkey, $on_delete, $on_update) in which $fkey and $rkey are the foreign (or referencing) and referenced keys, respectively: Foreign key $fkey of table $ftable references key $rkey of table $rtable. The values of $fkey and $rkey must either both be valid column name strings for columns of the same type, or they may both be sequential arrays of column name names, with equal numbers of columns of corresponding types, for multi-column keys. The $on_delete and $on_update values may be either null or string values that indicate actions to be taken upon deletion or updating of a referenced row (e.g., cascading deletes). A null value of $on_delete or $on_update indicates that no referentially triggered action will be taken. See addRef() for further details about allowed values of these action strings.
Parameters:
getRefTo [line 1147]
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.
The $_ref_to property is an associative array in which each key is the name of a referenced table, and each value is a sequential array containing the names of all tables that contain foreign keys that reference that table. Each element is thus of the form $_ref_to[$rtable] = array($ftable1, $ftable2,...), where $ftable1, $ftable2, ... are the names of tables that reference the table named $rtable.
Parameters:
getTable [line 819]
mixed getTable(
[string
$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
The $_table property is an associative array in which keys are table name strings and values are references to DB_Table objects. Each of the referenced objects represents one table in the database.
Parameters:
getTableSubclass [line 920]
mixed getTableSubclass(
[string
$name = null])
|
|
Returns all or part of the $_table_subclass property array
If $name is null, return the $this->_table_subclass property array If $name is a table name, return $this->_table_subclass[$name]
The $_table_subclass property is an associative array in which each key is a table name string, and each value is the name of the corresponding subclass of DB_Table. The value is null if the table is an instance of DB_Table itself.
Subclass names are set within the addTable method by applying the built in get_class() function to a DB_Table object. The class names returned by get_class() are stored unmodified. In PHP 4, get_class converts all class names to lower case. In PHP 5, it preserves the capitalization of the name used in the class definition.
For autoloading of class definitions to work properly in the __wakeup() method, the base name of each subclass definition file (excluding the .php extension) should thus be a identical to the class name in PHP 5, and a lower case version of the class name in PHP 4 or
Parameters:
insert [line 2194]
boolean insert(
string
$table_name, array
$data)
|
|
Inserts a single table row
Wrapper for insert method of the corresponding DB_Table object.
Data will be validated before insertion using validForeignKey(), if foreign key validation in enabled.
Parameters:
onDeleteAction [line 2572]
boolean onDeleteAction(
object
&$table_obj, string
$where)
|
|
Implements ON DELETE actions triggered by deletion of rows of $table_obj that match logical condition $where.
This method is called by the DB_Table::delete() method if the table has a parent DB_Table_Database object, and if ON DELETE actions are enabled in the database object. It is called indirectly by the DB_Table_Database::delete() method, which is simply a wrapper for the DB_Table method.
Parameters:
onUpdateAction [line 2315]
boolean onUpdateAction(
object
&$table_obj, array
$data, string
$where)
|
|
Implements any ON UPDATE actions triggered by updating of rows of $table_obj that match logical condition $where.
This method is called by the DB_Table::update() method if the table has a parent DB_Table_Database object, and if ON UPDATE actions are enabled in the database object. It is called indirectly by the DB_Table_Database::delete() method, which is simply a wrapper for the DB_Table method.
Parameters:
quote [line 3197]
string quote(
mixed
$value)
|
|
Returns SQL literal string representation of a php value
Calls MDB2::quote() or DB_Common::quoteSmart() to enquote and escape string values. 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:
setActOnDelete [line 700]
void setActOnDelete(
[bool
$flag = true])
|
|
Turns on (or off) automatic php emulation of SQL ON DELETE actions
Parameters:
setActOnUpdate [line 719]
void setActOnUpdate(
[bool
$flag = true])
|
|
Turns on (or off) automatic php emulation of ON UPDATE actions
Parameters:
setCheckFKey [line 738]
void setCheckFKey(
[bool
$flag = true])
|
|
Turns on (or off) validation of foreign key values on insert and update
Parameters:
setDBconnection [line 667]
boolean setDBconnection(
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', and set the same pair of values for the $db and $backend properties of every DB_Table object in the database.
Parameters:
setFixCase [line 762]
void setFixCase(
[bool
$flag = false])
|
|
Sets backend option such that column keys in associative array return sets are converted to fixed case, if true, or mixed case, if false.
Sets the DB/MDB2 'portability' option, and sets $this->_fix_case = $flag. Because it sets an option in the underlying DB/MDB2 connection object, this effects the behavior of all objects that share the connection.
Parameters:
setOnDelete [line 1752]
boolean 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 1784]
boolean 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 1295]
void setTableSubclassPath(
string
$path)
|
|
Sets path to a directory containing DB_Table subclass definitions.
This method sets the $_table_subclass_path string property. The value of this property is the path to the directory containing DB_Table subclass definitions, without a trailing directory separator.
This path may be used by the __wakeup(), if necessary, in an attempt to autoload class definitions when unserializing a DB_Table_Database object and its child DB_Table objects. If a DB_Table subclass $subclass_name has not been defined when it is needed in DB_Table_Database::__wakeup(), to unserialize an instance of this class, the __wakeup() method attempts to include a class definition file from this directory, as follows: $dir = $this->_table_subclass_path;
require_once $dir . '/' . $subclass . '.php';
Parameters:
toXML [line 3292]
string toXML(
[string
$indent = ''])
|
|
Returns XML string representation of database declaration
Parameters:
update [line 2256]
boolean update(
string
$table_name, array
$data, string
$where)
|
|
Updates all row(s) of table that match a custom where clause.
Wrapper for insert method of the corresponding DB_Table object.
Data will be validated before insertion using validForeignKey(), if foreign key validation in enabled.
Implements any required ON UPDATE actions on tables that reference updated columns, if on update actions are enabled.
Parameters:
validCol [line 2022]
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 2136]
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 a PEAR_Error 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.
Parameters:
__sleep [line 3219]
Serializes all table references and sets $db = null, $backend = null
__wakeup [line 3262]
Unserializes DB_Table_Database object and all child DB_Table objects
Immediately after unserialization, a DB_Table_Database object has null $db and $backend properties, as do all of its child DB_Table objects. The DB_Table_Database::setDB method should be called immediately after unserialization to re-establish the database connection, like so:
$db_object->setDB($conn);
This method unserializes all of the child DB_Table objects of a DB_Table_Database object. It must thus have access to the definitions of the associated DB_Table subclasses. These are listed in the $_table_subclass property. If a required subclass named $subclass is not defined, the __wakeup() method attempts to autoload a file "$subclass.php" in the directory specified by $this->table_subclass_path.
