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


Classes:
DB_Table
   example
DB_Table
DB_Table_Manager
DB_Table_QuickForm
DB_Table_Valid
Files:
bogotest.php
Manager.php
QuickForm.php
Table.php
Valid.php

Class: DB_Table

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

Class Overview




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




Author(s):






    
            

Version:


    
  
  • @package_version@
    • 








Variables






Methods
















Child classes:






example

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









Inherited Variables





Inherited Methods














Class Details



[line 351]

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



	
	

	
$col = array()

	
[line 390]

  Associative array of column definitions.


    

  • Access: public
    • 





  

	

  

    

      Type:  
      array
    

      

	



	
[ Top ]


	
	

	
$db =  null

	
[line 364]

  The PEAR DB object that connects to the database.


    

  • Access: public
    • 





  

	

  

    

      Type:  
      object
    

      

	



	
[ Top ]


	
	

	
$error =  null

	
[line 493]

  If there is an error on instantiation, this captures that error.
This property is used only for errors encountered in the constructor  at instantiation time.  To check if there was an instantiation error...

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

  

	

  

    

      Type:  
      object PEAR_Error
    

      

	



	
[ Top ]


	
	

	
$fetchmode =  null

	
[line 457]

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


    

  • Access: public
    • 





  

	

  

    

      Type:  
      int
    

      

	



	
[ Top ]


	
	

	
$fetchmode_object_class =  null

	
[line 472]

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


    

  • Access: public
    • 





  

	

  

    

      Type:  
      string
    

      

	



	
[ Top ]


	
	

	
$idx = array()

	
[line 403]

  Associative array of index definitions.


    

  • Access: public
    • 





  

	

  

    

      Type:  
      array
    

      

	



	
[ Top ]


	
	

	
$sql = array()

	
[line 416]

  Baseline SELECT maps for select(), selectResult(), selectCount().


    

  • Access: public
    • 





  

	

  

    

      Type:  
      array
    

      

	



	
[ Top ]


	
	

	
$table =  null

	
[line 377]

  The table or view in the database to which this object binds.


    

  • Access: public
    • 





  

	

  

    

      Type:  
      string
    

      

	



	
[ Top ]










Method Detail



	
	
DB_Table (Constructor)   [line 567]

	

    

    

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

    


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


    

  • Access: public
    • 








        
Parameters:

    

    

          

        object  
        &$db  
        —
          A PEAR DB 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, or  'drop' to drop any existing table with the same name  and re-create it.
      

        

    


        
[ Top ]

  

  
  
	
	
addFormElements   [line 2013]

	

    

    

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

    


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








        
Parameters:

    

    

          

        object  
        &$form  
        —
          An HTML_QuickForm object.
      

          

        array  
        $columns  
        —
          A sequential array of column names to use in  the form; if null, uses all columns.
      

          

        string  
        $array_name  
        —
          By default, the form will use the names  of the columns as the names of the form elements.  If you pass  $array_name, the column names will become keys in an array named  for this parameter.
      

        

    


        
[ Top ]

  

  
  
	
	
autoRecast   [line 1506]

	

    

    

		void autoRecast(
[bool
$flag = true])
    

    


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


    

  • Access: public
    • 








        
Parameters:

    

    

          

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

        

    


        
[ Top ]

  

  
  
	
	
autoValidInsert   [line 1195]

	

    

    

		void autoValidInsert(
[bool
$flag = true])
    

    


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


    

  • Access: public
    • 








        
Parameters:

    

    

          

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

        

    


        
[ Top ]

  

  
  
	
	
autoValidUpdate   [line 1320]

	

    

    

		void autoValidUpdate(
[bool
$flag = true])
    

    


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


    

  • Access: public
    • 








        
Parameters:

    

    

          

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

        

    


        
[ Top ]

  

  
  
	
	
buildSQL   [line 1061]

	

    

    

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

    


	
		Builds the SQL command from a specified $this->sql element.


    

  • Return: A PEAR_Error on failure, or an SQL command string on  success.
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $sqlkey  
        —
          The $this->sql key to use as the basis for the  SQL query string.
      

          

        string  
        $filter  
        —
          A filter to add to the WHERE clause of the  defined SELECT in $this->sql.
      

          

        string  
        $order  
        —
          An ORDER clause to override the defined order  in $this->sql.
      

          

        int  
        $start  
        —
          The row number to start listing from in the  result set.
      

          

        int  
        $count  
        —
          The number of rows to list in the result set.
      

        

    


        
[ Top ]

  

  
  
	
	
create   [line 1768]

	

    

    

		mixed create(
mixed
$flag)
    

    


	
		Creates the table based on $this->col and $this->idx.


    

  • Return: Boolean false if there was no attempt to create the  table, boolean true if the attempt succeeded, or a PEAR_Error if  the attempt failed.
    • 

  • See: DB_Table_Manager::create()
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        mixed  
        $flag  
        —
          Boolean false to abort the create attempt from  the start, 'drop' to drop the existing table and  re-create it, or 'safe' to only create the table if it  does not exist in the database.
      

        

    


        
[ Top ]

  

  
  
	
	
delete   [line 1403]

	

    

    

		mixed delete(
string
$where)
    

    


	
		Deletes table rows matching a custom WHERE clause.


    

  • Return: Void on success or a PEAR_Error object on failure.
    • 

  • See: DB::query()
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $where  
        —
          The WHERE clause for the delete command.
      

        

    


        
[ Top ]

  

  
  
	
	
getBlankRow   [line 1479]

	

    

    

		array getBlankRow(
)
    

    


	
		Returns a blank row array based on the column map.
The array keys are the column names, and all values are set to null.


    

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

  • Access: public
    • 








        
[ Top ]

  

  
  
	
	
getColumns   [line 640]

	

    

    

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

	

    

    

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

	

    

    

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

	

    

    

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

    


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








        
Parameters:

    

    

          

        string  
        $cols  
        —
          Array of DB_Table column names
      

          

        string  
        $array_name  
        —
          The name to use for the generated QuickForm  elements.
      

        

    


        
[ Top ]

  

  
  
	
	
getFormGroup   [line 2047]

	

    

    

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

	

    

    

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

    


	
		Returns all or part of the $this->idx property array.


    

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

  • Access: public
    • 








        
Parameters:

    

    

          

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

        

    


        
[ Top ]

  

  
  
	
	
insert   [line 1163]

	

    

    

		mixed insert(
array
$data)
    

    


	
		Inserts a single table row after validating through validInsert().


    

  • Return: Void on success, a PEAR_Error object on failure.
    • 

  • See: DB::autoExecute()
    • 

  • See: DB_Table::validInsert()
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

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

        

    


        
[ Top ]

  

  
  
	
	
isRequired   [line 1918]

	

    

    

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

	

    

    

		boolean isValid(
array
$val, array
$col)
    

    


	
		Checks if a value validates against the DB_Table data type for a  given column. This only checks that it matches the data type; it  does not do extended validation.


    

  • Return: True if the value validates (matches the  data type), false if not.
    • 

  • See: DB_Table_Valid
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        array  
        $val  
        —
          A value to check against the column's DB_Table  data type.
      

          

        array  
        $col  
        —
          A column name from $this->col.
      

        

    


        
[ Top ]

  

  
  
	
	
nextID   [line 1423]

	

    

    

		integer nextID(
[string
$seq_name = null])
    

    


	
		Generates a sequence value; sequence name defaults to the table name.


    

  • Return: The next value in the sequence.
    • 

  • See: DB::nextID()
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $seq_name  
        —
          The sequence name; defaults to table_id.
      

        

    


        
[ Top ]

  

  
  
	
	
quote   [line 1460]

	

    

    

		string quote(
mixed
$val)
    

    


	
		Escapes and enquotes a value for use in an SQL query.
Helps makes user input safe against SQL injection attack.


    

  • Return: The value with quotes escaped, and inside single quotes.
    • 

  • See: DB_Common::quoteSmart()
    • 

  • Access: public
    • 








        
[ Top ]

  

  
  
	
	
recast   [line 1539]

	

    

    

		void recast(
array
&$data)
    

    


	
		Forces array elements to the proper types for their columns.
This will not valiate the data, and will forcibly change the data  to match the recast-type.
The date, time, and timestamp recasting has special logic for  arrays coming from an HTML_QuickForm object so that the arrays  are converted into properly-formatted strings.


    

  • Access: public
    • 

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








        
Parameters:

    

    

          

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

        

    


        
[ Top ]

  

  
  
	
	
select   [line 767]

	

    

    

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

    


	
		Selects rows from the table using one of the 'DB::get*()' methods.


    

  • Return: An array of records from the table (if anything but  'getOne'), a single value (if 'getOne'), or a PEAR_Error object.
    • 

  • See: DB::getRow()
    • 

  • See: DB_Table::_swapModes()
    • 

  • See: DB::getOne()
    • 

  • See: DB::getCol()
    • 

  • See: DB::getAll()
    • 

  • See: DB::getAssoc()
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $sqlkey  
        —
          The name of the SQL SELECT to use from the  $this->sql property array.
      

          

        string  
        $filter  
        —
          Ad-hoc SQL snippet to AND with the default  SELECT WHERE clause.
      

          

        string  
        $order  
        —
          Ad-hoc SQL snippet to override the default  SELECT ORDER BY clause.
      

          

        int  
        $start  
        —
          The row number to start listing from in the  result set.
      

          

        int  
        $count  
        —
          The number of rows to list in the result set.
      

          

        array  
        $params  
        —
          Parameters to use in placeholder substitutions (if  any).
      

        

    


        
[ Top ]

  

  
  
	
	
selectCount   [line 941]

	

    

    

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

    


	
		Counts the number of rows which will be returned by a query.
This function works identically to select(), but it  returns the number of rows returned by a query instead of the  query results themselves.
This makes using DB_Table with Pager easier, since you can pass the  return value of this to Pager as totalItems, then select only the  rows you need to display on a page.








        
Parameters:

    

    

          

        string  
        $sqlkey  
        —
          The name of the SQL SELECT to use from the  $this->sql property array.
      

          

        string  
        $filter  
        —
          Ad-hoc SQL snippet to AND with the default  SELECT WHERE clause.
      

          

        string  
        $order  
        —
          Ad-hoc SQL snippet to override the default  SELECT ORDER BY clause.
      

          

        int  
        $start  
        —
          The row number to start listing from in the  result set.
      

          

        int  
        $count  
        —
          The number of rows to list in the result set.
      

          

        array  
        $params  
        —
          Parameters to use in placeholder substitutions (if  any).
      

        

    


        
[ Top ]

  

  
  
	
	
selectResult   [line 860]

	

    

    

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

    


	
		Selects rows from the table as a DB_Result object.


    

  • Return: A PEAR_Error on failure, or a DB_Result object on  success.
    • 

  • See: DB_Table::_swapModes()
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $sqlkey  
        —
          The name of the SQL SELECT to use from the  $this->sql property array.
      

          

        string  
        $filter  
        —
          Ad-hoc SQL snippet to add to the default  SELECT WHERE clause.
      

          

        string  
        $order  
        —
          Ad-hoc SQL snippet to override the default  SELECT ORDER BY clause.
      

          

        int  
        $start  
        —
          The record number to start listing from in the  result set.
      

          

        int  
        $count  
        —
          The number of records to list in the result set.
      

          

        array  
        $params  
        —
          Parameters to use in placeholder substitutions (if  any).
      

        

    


        
[ Top ]

  

  
  
	
	
supported   [line 616]

	

    

    

		bool supported(
string
$phptype)
    

    


	
		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.
      

        

    


        
[ Top ]

  

  
  
	
	
throwError   [line 529]

	

    

    

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

    


	
		Specialized version of throwError() modeled on PEAR_Error.
Throws a PEAR_Error with a DB_Table error message based on a  DB_Table constant error code.


    

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $code  
        —
          A DB_Table error code constant.
      

          

        string  
        $extra  
        —
          Extra text for the error (in addition to the  regular error message).
      

        

    


        
[ Top ]

  

  
  
	
	
update   [line 1288]

	

    

    

		mixed update(
array
$data, string
$where)
    

    


	
		Updates table row(s) matching a custom WHERE clause, after checking  against validUpdate().


    

  • Return: Void on success, a PEAR_Error object on failure.
    • 

  • See: DB::autoExecute()
    • 

  • See: DB_Table::validUpdate()
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        array  
        $data  
        —
          An associative array of key-value pairs where  the key is the column name and the value is the column value.  These  are the columns that will be updated with new values.
      

          

        string  
        $where  
        —
          An SQL WHERE clause limiting which records  are to be updated.
      

        

    


        
[ Top ]

  

  
  
	
	
validInsert   [line 1223]

	

    

    

		mixed validInsert(
array
&$data)
    

    


	
		Validates an array for insertion into the table.


    

  • Return: Boolean true on success, a PEAR_Error object on  failure.
    • 

  • See: DB_Table::insert()
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

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

        

    


        
[ Top ]

  

  
  
	
	
validUpdate   [line 1348]

	

    

    

		mixed validUpdate(
array
&$data)
    

    


	
		Validates an array for updating the table.


    

  • Return: Boolean true on success, a PEAR_Error object on  failure.
    • 

  • See: DB_Table::update()
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

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

        

    


        
[ Top ]

  

  
  
	
	
_getFormColDefs   [line 2126]

	

    

    

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

    


	
		Creates a column definition array suitable for DB_Table_QuickForm.


    

  • Return: An array of columne defintions suitable for passing  to DB_Table_QuickForm.
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

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

        

    


        
[ Top ]

  

  
  



        

		    

		    Documentation generated on Tue, 13 Sep 2005 11:00:11 -0400 by phpDocumentor 1.2.3. PEAR Logo Copyright ©  PHP Group 2004.