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

Class: DB_Table_Database

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

Class Overview

DB_Table_Base
   |
   --DB_Table_Database

Relational database 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 416]
Relational database abstraction class

DB_Table_Database is an abstraction class for a relational database. It is a layer built on top of DB_Table, in which each table in a database is represented as an instance of DB_Table. It provides:

  • an object-oriented representation of the database schema
  • automated construction of SQL commands for simple joins
  • an API for insert, update, and select commands very similar to that of DB_Table, with optional emulation of standard SQL foreign key integrity checks and referential triggered actions such as cascading deletes.
  • Serialization and unserialization of the database schema via either php serialization or XML, using the MDB2 XML schema.



[ Top ]


Class Variables

$name =  null

[line 427]

Name of the database
  • Access: public

Type:   string


[ Top ]



Method Detail

DB_Table_Database (Constructor)   [line 625]

object DB_Table_Database DB_Table_Database( object &$db, string $name)

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.

  • Access: public

Parameters:

object   &$db     DB/MDB2 database connection object
string   $name     the database name

[ Top ]

addAllLinks   [line 1897]

void addAllLinks( )

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.

  • Access: public

[ Top ]

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 )

  • Return: true on success (PEAR_Error on failure)
  • Access: public

Parameters:

string   $table1     name of 1st linked table
string   $table2     name of 2nd linked table
string   $link     name of linking/association table.

[ Top ]

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 )

  • Return: true on success (PEAR_Error on failure)
  • Access: public

Parameters:

string   $ftable     name of foreign/referencing table
mixed   $fkey     foreign key in referencing table
string   $rtable     name of referenced table
mixed   $rkey     referenced key in referenced table
string   $on_delete     action upon delete of a referenced row.
string   $on_update     action upon update of a referenced row.

[ Top ]

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 )

  • Return: true on success (PEAR_Error on failure)
  • Access: public

Parameters:

object   &$table_obj     the DB_Table object (reference)

[ Top ]

autoInc   [line 2507]

void autoInc( [bool $flag = true])

Turns on (or off) php implementation of auto-incrementing on insertion for all tables
  • Access: public

Parameters:

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

[ Top ]

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.

  • Return: sql query array for select statement
  • Access: public

Parameters:

array   $cols     sequential array of column names
array   $tables     sequential array of table names
array   $filter     SQL logical expression to be added (ANDed) to the where clause

[ Top ]

autoRecast   [line 2489]

void autoRecast( [bool $flag = true])

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

Parameters:

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

[ Top ]

autoValidInsert   [line 2227]

void autoValidInsert( [bool $flag = true])

Turns on or off automatic validation of inserted data for all tables
  • Access: public

Parameters:

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

[ Top ]

autoValidUpdate   [line 2289]

void autoValidUpdate( [bool $flag = true])

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

Parameters:

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

[ Top ]

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

  • Return: true on sucess (PEAR_Error on failure of any table)
  • See: DB_Table::create()
  • Access: public

Parameters:

mixed   $flag     The automatic database creation mode, which is applied to each table in the database. It can have values:
  • 'safe' to create a table only if it does not exist
  • 'drop' to drop and recreate any existing table

[ Top ]

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.

  • Return: true on success (PEAR_Error on failure)
  • Access: public

Parameters:

string   $table_name     name of table from which to delete
string   $where     SQL WHERE clause that limits the set of records to delete

[ Top ]

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.

  • Access: public

Parameters:

string   $table1     name of 1st linked table
string   $table2     name of 2nd linked table
string   $link     name of linking table

[ Top ]

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.

  • Access: public

Parameters:

$ftable   $ftable     name of referencing (foreign key) table
$rtable   $rtable     name of referenced table

[ Top ]

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.

  • Access: public

Parameters:

string   $table     name of table to be deleted

[ Top ]

fromXML   [line 3324]

object DB_Table_Database fromXML( string $xml_string, $conn)

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.

  • Return: object on success (PEAR_Error on failure)
  • Throws: PEAR_Error if:
    • PHP version is not >= 5.0.0 (...DATABASE_ERR_PHP_VERSION )
    • Parsing by simpleXML fails (...DATABASE_ERR_XML_PARSE )
  • Access: public

Parameters:

string   $xml_string     XML string representation
   $conn     

[ Top ]

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.

  • Return: property array or $this->_col[$column_name] (PEAR_Error on failure)
  • Throws: PEAR_Error if:
    • $column_name is not a string (DB_TABLE_DATABASE_ERR_COL_NOT_STRING)
    • $column_name is not valid column name (DB_TABLE_DATABASE_NO_COL)
  • Access: public

Parameters:

string   $column_name     a column name string

[ Top ]

getDBInstance   [line 790]

object Reference &getDBInstance( )

Return reference to $this->db DB/MDB2 object wrapped by $this
  • Return: to DB/MDB2 object
  • Access: public

[ Top ]

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 )

  • Return: property array
  • Access: public

Parameters:

string   $column_name     column name string for foreign key column

[ Top ]

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.

  • Return: property array, sub-array, or value
  • Throws: PEAR_Error:
    • $table1 or $table2 is not a string (..DATABASE_ERR_TBL_NOT_STRING)
    • $table1 or $table2 is not a table name (..DATABASE_ERR_NO_TBL)
  • Access: public

Parameters:

string   $table1     name of linked table
string   $table2     name of linked table

[ Top ]

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

  • Return: array or $this->_primary_key[$name] (PEAR_Error on failure)
  • Throws: PEAR_Error if:
    • $name is not a string ( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING )
    • $name is not valid table name ( DB_TABLE_DATABASE_ERR_NO_TBL )
  • Access: public

Parameters:

string   $name     Name of table

[ Top ]

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.

  • Return: property array, sub-array, or value
  • Throws: a PEAR_Error if:
    • $table1 or $table2 is not a string (.._DATABASE_ERR_TBL_NOT_STRING)
    • $table1 or $table2 is not a table name (.._DATABASE_ERR_NO_TBL)
  • Access: public

Parameters:

string   $table1     name of referencing table
string   $table2     name of referenced table

[ Top ]

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.

  • Return: property array or subarray (PEAR_Error on failure)
  • Throws: PEAR_Error if:
    • $table_name is not a string ( .._DATABASE_ERR_TBL_NOT_STRING )
    • $table_name is not a table name ( .._DATABASE_ERR_NO_TBL )
  • Access: public

Parameters:

string   $table_name     name of table

[ Top ]

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.

  • Return: property, or one element of $_table (PEAR_Error on failure)
  • Throws: PEAR_Error if:
    • $name is not a string ( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING )
    • $name is not valid table name ( DB_TABLE_DATABASE_ERR_NO_TBL )
  • Access: public

Parameters:

string   $name     Name of table

[ Top ]

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

  • Return: array or $this->_table_subclass[$name] (PEAR_Error on failure)
  • Throws: PEAR_Error if:
    • $name is not a string ( DB_TABLE_DATABASE_TBL_NOT_STRING )
    • $name is not valid table name ( DB_TABLE_DATABASE_NO_TBL )
  • Access: public

Parameters:

string   $name     Name of table

[ Top ]

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.

  • Return: true on success (PEAR_Error on failure)
  • Access: public

Parameters:

string   $table_name     Name of table into which to insert data
array   $data     Associative array, in which each key is a column name and each value is that column's value. This is the data that will be inserted into the table. Data is checked against the column names and data types for validity.

[ Top ]

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.

  • Return: true on success (PEAR_Error on failure)
  • Access: public

Parameters:

object   &$table_obj     Reference to a DB_Table object
string   $where     SQL logical condition for deleted rows

[ Top ]

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.

  • Return: true on success (PEAR_Error on failure)
  • Access: public

Parameters:

object   &$table_obj     Reference to a DB_Table object
array   $data     Data to updated, column name keys, data values
string   $where     SQL logical condition for updated rows

[ Top ]

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'

  • Return: Representation of value as an SQL literal
  • See: MDB2::quote()
  • See: DB_Common::quoteSmart()
  • Access: public

Parameters:

mixed   $value     

[ Top ]

setActOnDelete   [line 700]

void setActOnDelete( [bool $flag = true])

Turns on (or off) automatic php emulation of SQL ON DELETE actions
  • Access: public

Parameters:

bool   $flag     True to enable action, false to disable

[ Top ]

setActOnUpdate   [line 719]

void setActOnUpdate( [bool $flag = true])

Turns on (or off) automatic php emulation of ON UPDATE actions
  • Access: public

Parameters:

bool   $flag     True to enable action, false to disable

[ Top ]

setCheckFKey   [line 738]

void setCheckFKey( [bool $flag = true])

Turns on (or off) validation of foreign key values on insert and update
  • Access: public

Parameters:

bool   $flag     True to enable foreign key validation, false to disable

[ Top ]

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.

  • Return: True on success (PEAR_Error on failure)
  • Throws: PEAR_Error if $db is not a DB or MDB2 object(DB_TABLE_DATABASE_ERR_DB_OBJECT)
  • Access: public

Parameters:

object   &$db     DB/MDB2 connection object

[ Top ]

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.

  • Access: public

Parameters:

bool   $flag     True for fixed lower case, false for mixed

[ Top ]

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.

  • Return: true on normal completion (PEAR_Error on failure)
  • Access: public

Parameters:

string   $ftable     name of referencing (foreign key) table
string   $rtable     name of referenced table
string   $action     on delete action (action string or null)

[ Top ]

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.

  • Return: true on normal completion (PEAR_Error on failure)
  • Access: public

Parameters:

string   $ftable     name of referencing (foreign key) table
string   $rtable     name of referenced table
array   $action     on update action (action string or null)

[ Top ]

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:

  1.      $dir $this->_table_subclass_path;
  2.      require_once $dir '/' $subclass '.php';
See the getTableSubclass() docblock for a discusion of capitalization conventions in PHP 4 and 5 for subclass file names.


Parameters:

string   $path     path to directory containing class definitions

[ Top ]

toXML   [line 3292]

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

Returns XML string representation of database declaration
  • Return: XML string representation
  • Access: public

Parameters:

string   $indent     string of whitespace, prefix to each line

[ Top ]

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.

  • Return: true on success (PEAR_Error on failure)
  • Access: public

Parameters:

string   $table_name     name of table to update
array   $data     associative array in which keys are names of columns to be updated values are new values.
string   $where     SQL WHERE clause that limits the set of records to update.

[ Top ]

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 )

  • Return: array($table, $column), or PEAR_Error on failure $column is a string, $table is a string or array
  • Access: public

Parameters:

string   $col     column name, optionally qualified by a table name
array   $from     array of tables from which $col should be chosen, if possible.

[ Top ]

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.

  • Return: true if all foreign keys are valid, returns PEAR_Error if foreign keys are invalid or if an error is thrown by a required query
  • Throws: PEAR error if:
    • Error thrown by _buildFKeyFilter method (bubbles up)
    • Error thrown by select method for required query (bubbles up)
  • Access: public

Parameters:

$table_name   $table_name     name of the referencing table containing $data
@data   $data     associative array containing all or part of a row of data of $table_name, with column name keys.

[ Top ]

__sleep   [line 3219]

array __sleep( )

Serializes all table references and sets $db = null, $backend = null
  • Return: names of all properties
  • Access: public

[ Top ]

__wakeup   [line 3262]

void __wakeup( )

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:

  1.     $db_object unserialize($serialized_db);
  2.     $db_object->setDB($conn);
where $conn is a DB/MDB2 object. This establishes a DB/MDB2 connection for both the parent database and all child tables.

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.

  • Access: public

[ Top ]


Documentation generated on Thu, 25 Dec 2008 15:00:19 -0500 by phpDocumentor 1.4.0. PEAR Logo Copyright © PHP Group 2004.