$Database
$Database : \SmartDatabase
Tables contain table properties and Columns (which contain column properties). No user/db data is on a Table level. See Rows and Cells.
$Database : \SmartDatabase
$TableName : \SmartTable
$AutoRefresh : boolean
Mostly for internal use. If true, Refresh() will be called automatically whenever a column is added or removed to this table.
As an optimization, you may want to disable $AutoRefresh when you are adding/removing bulk columns to a table, then make a single call to Refresh() once all column management is complete.
__construct(string $tableName) : \SmartTable
Constructor
| string | $tableName | The name of the table |
Refresh()
Mostly for internal use. Re-computes column aliases, key columns, and etc from $this->_columns.
This function gets called automatically from AddColumn() and RemoveColumn() unless $AutoRefresh is set to false (in which case, you'll need to call this function yourself when you have finished adding/removing columns).
As an optimization, you may want to disable AutoRefresh when you are adding/removing bulk columns to a table, then make a single call to Refresh() once all column management is complete.
AddColumn(\SmartColumn $Column, boolean $replaceExisting = true) : boolean
Adds a column to be managed by this Table. Replaces any column with the same name.
If adding bulk columns, you may want to disable $AutoRefresh until all columns have been added, then make a single call to Refresh()
| \SmartColumn | $Column | The Column to add. |
| boolean | $replaceExisting | If a column with the same name already exists on this table, should we replace it with this new Column? |
True if the column was added successfully, false otherwise (may happen if the column exists and $replaceExisting == false)
GetColumn(string $columnName) : \SmartColumn
Returns the $columnName Column. Shortcut: use array notation- $table['YOUR_COLUMN_NAME']
| string | $columnName | The name of the column to get. |
The column requested.
RemoveColumn(string $columnName) : boolean
Removes a column from this table. If the given $columnName does not exist, an exception is thrown.
If removing bulk columns, you may want to disable $AutoRefresh until all column management is complete, then make a single call to Refresh()
| string | $columnName | The name of the column to remove. |
Always returns true. If the given $columnName does not exist, an exception is thrown.
InheritColumnsFromTable(\SmartTable $Table)
All columns (and relations associated with those columns) from the given $Table are added to this $Table (structure only, no data!)
| \SmartTable | $Table |
LookupRows(array $lookupAssoc = null, array $options = null) : mixed
Returns an array of all Row instances that match the given $lookupAssoc column values, or an empty array if there are no matches. If the option 'return-count-only'=true, returns an integer of number of rows selected. To execute this function, this table must have a primary key.
Options are as follows:
$options = array(
'sort-by'=>null, //Either a string of the column to sort ASC by, or an assoc array of "ColumnName"=>"ASC"|"DESC" to sort by. An exception will be thrown if a column does not exist.
'callback'=>null, //function - if set, this function will be invoked for each row and the full result set will NOT be returned- only the LAST ROW in the set will be returned (if there is one). the function's signature should be function($row, $i){} where $row is the actual SmartRow, and $i is the 1-based index of the row being returned
'return-assoc'=>false, //if true, the returned assoc-array will have the row's primary key column value as its key (if a non-composite primary key exists on the table. otherwise this option is ignored) and the Row instance as its value. ie array("2"=>$row,...) instead of just array($row,...);
'return-next-row'=>null, //OUT variable. integer. if you set this parameter in the $options array, then this function will return only 1 row of the result set at a time. If there are no rows selected or left to iterate over, null is returned.
// THIS PARAMETER MUST BE PASSED BY REFERENCE - i.e. array( "return-next-row" => &$curCount ) - the incoming value of this parameter doesn't matter and will be overwritten)
// After this function is executed, this OUT variable will be set with the number of rows that have been returned thus far.
// Each consecutive call to this function with the 'return-next-row' option set will return the next row in the result set, and also increment the 'return-next-row' variable to the number of rows that have been returned thus far
'limit'=>null, // With one argument (ie $limit="10"), the value specifies the number of rows to return from the beginning of the result set
// With two arguments (ie $limit="100,10"), the first argument specifies the offset of the first row to return, and the second specifies the maximum number of rows to return. The offset of the initial row is 0 (not 1):
'return-count'=>null, //OUT variable only. integer. after this function is executed, this variable will be set with the number of rows being returned. Usage ex: array('return-count'=>&$count)
'return-count-only'=>false, //if true, the return-count will be returned instead of the rows. A good optimization if you dont need to read any data from the rows and just need the rowcount of the search
)| array | $lookupAssoc | [optional] An assoc-array of column=>value to lookup. For example: array("column1"=>"lookupVal", "column2"=>"lookupVal", ...). If this is left null or empty array, all rows will be returned. |
| array | $options | [optional] See description |
An array of all Row instances matching the criteria of $lookupAssoc, or if the option 'return-count-only'=true, returns an integer of number of rows selected
LookupRow(mixed $lookupVals) : \SmartRow
Looks up an a row that matches the given column $value. If there is no match, an instance is still returned but ->Exists() will be false. The returned row will have the searched columns=>values set by default (excluding auto-increment primary key columns) To execute this function, this table must have a primary key. Throws an exception if more than 1 row is returned.
As a shortcut, invoking the SmartTable directly will call LookupRow, i.e., $smartdb'tablename' instead of $smartdb['tablename']->LookupRow(212) or $smartdb['tablename']->LookupRow(array('id'=>212))
| mixed | $lookupVals | Either 1) An assoc-array of column=>value to lookup. For example: array("column1"=>"lookupVal", "column2"=>"lookupVal", ...). OR 2) As a shorthand, if the table contains a single primary key column, $lookupVals can be the value of that column to lookup instead of an array, ie 421 |
A Row instance matching the criteria of $lookupVals. The returned row may or may not Exist
LookupColumnValues(string $returnColumn = null, array $lookupAssoc = null, array $options = null) : mixed
Gets all values in all rows for the given $returnColumn, optionally unique and sorted. Optionally in an assoc with the primary key column value as the assoc's key value. Alternatively, if the option 'return-count-only'=true, returns an integer of number of rows selected.
Options are as follows:
$options = array(
'sort-by'=>null, //Either a string of the column to sort ASC by, or an assoc array of "ColumnName"=>"ASC"|"DESC" to sort by. An exception will be thrown if a column does not exist.
'get-unique'=>false, //If true, only unique values will be returned. Note: array keys in the returned array will NOT be the key column when this is true)
'return-assoc'=>false, //if true, the returned assoc-array will have the row's primary key column value as its key (if a non-composite primary key exists on the table. otherwise this option is ignored) and the $returnColumn's value as its value. ie array("2"=>$returnColumnValue,...) instead of just array($returnColumnValue,...);
'limit'=>null, // With one argument (ie $limit="10"), the value specifies the number of rows to return from the beginning of the result set
// With two arguments (ie $limit="100,10"), the first argument specifies the offset of the first row to return, and the second specifies the maximum number of rows to return. The offset of the initial row is 0 (not 1):
'return-count'=>null, //OUT variable only. integer. after this function is executed, this variable will be set with the number of values being returned. Usage ex: array('return-count'=>&$count)
'return-count-only'=>false, //if true, the return-count will be returned instead of the rows. A good optimization if you dont need to read any data from the rows and just need the rowcount of the search
}| string | $returnColumn | The name of the column to return the values of (can be null only for reverse compatibility) |
| array | $lookupAssoc | [optional] An assoc-array of column=>value to lookup. For example: array("column1"=>"lookupVal", "column2"=>"lookupVal", ...). If this is left null or empty array, all column values for all rows will be returned. |
| array | $options | [optional] See description |
An array of key-value pairs. The keys are either 1: nothing, or 2: the primary key (if 'return-assoc' option is TRUE and 'get-unique' option is false and the table has a primary key), and the values are the actual column values. Alternatively, if the option 'return-count-only'=true, returns an integer of number of rows selected.
LookupColumnValue(string $returnColumn, array $lookupAssoc = null) : mixed
Returns the value of the column found, or FALSE if no row exists matching the criteria of $lookupAssoc Note: this function will throw an exception if more than 1 row is found matching the criteria of $lookupAssoc
| string | $returnColumn | The name of the column to return the value of |
| array | $lookupAssoc | [optional] An assoc-array of column=>value to lookup. For example: array("column1"=>"lookupVal", "column2"=>"lookupVal", ...). If empty, nothing is filtered (an exception is thrown if more than 1 value is returned) |
The value of the column found, or FALSE if no row exists matching the criteria of $lookupAssoc
DeleteRow(mixed $lookupAssoc, array $options = null) : integer
Deletes the row instance matching the criteria of $lookupVals. Returns number of rows deleted (1 or 0) NOTE: any columns in $lookupAssoc must be a key or unique!!! We need to ensure that we'll only have 1 row.
Throws an exception if more than 1 row is returned.
Options are as follows:
$options = array(
'skip-callbacks'=>false //If true, all row-level "Delete" callbacks will be skipped. This can substantially improve the performance of very large bulk deletions.
)| mixed | $lookupAssoc | Either 1) An assoc-array of column=>value to lookup. For example: array("column1"=>"lookupVal", "column2"=>"lookupVal", ...). OR 2) As a shorthand, if the table contains a single primary key column, $lookupVals can be the value of that column to lookup instead of an array, ie 421 |
| array | $options | [optional] See description |
number of rows deleted (1 or 0)
DeleteRows(array $lookupAssoc, array $options = null) : integer
Deletes all rows with where the column values matches the passed $lookupAssoc
Options are as follows:
$options = array(
'skip-callbacks'=>false //If true, all row-level "Delete" callbacks will be skipped. This can substantially improve the performance of very large bulk deletions.
)| array | $lookupAssoc | An assoc-array of column=>value to lookup. For example: array("column1"=>"lookupVal", "column2"=>"lookupVal", ...) |
| array | $options | [optional] See description |
the number of rows deleted
DeleteAllRows(array $options = null) : integer
Deletes all rows in the table
Options are as follows:
$options = array(
'skip-callbacks'=>false //If true, all row-level "Delete" callbacks will be skipped. This can substantially improve the performance of very large bulk deletions.
)| array | $options | [optional] See description |
the number of rows deleted
GetAllRows(array $options = null) : mixed
Looks up an array of all Row instances that belong to this table, or an empty array if there are no matches. The returned array's keys=0-indexed iterator (or if the 'return-assoc' option is true, keys are the row's primary key value), value=$Row. If the option 'return-count-only'=true, returns an integer of number of rows selected. To execute this function, this table must have a primary key, but this could probably be changed.
Options are as follows:
$options = array(
'sort-by'=>null, //Either a string of the column to sort ASC by, or an assoc array of "ColumnName"=>"ASC"|"DESC" to sort by. An exception will be thrown if a column does not exist.
'callback'=>null, //function - if set, this function will be invoked for each row and the full result set will NOT be returned- only the LAST ROW in the set will be returned (if there is one). the function's signature should be function($row, $i){} where $row is the actual SmartRow, and $i is the 1-based index of the row being returned
'return-assoc'=>false, //if true, the returned assoc-array will have the row's primary key column value as its key and the row as its value. ie array("2"=>$row,...) instead of just array($row,...);
'return-next-row'=>null, //OUT variable. integer. if you set this parameter in the $options array, then this function will return only 1 row of the result set at a time. If there are no rows selected or left to iterate over, null is returned.
// THIS PARAMETER MUST BE PASSED BY REFERENCE - i.e. array( "return-next-row" => &$curCount ) - the incoming value of this parameter doesn't matter and will be overwritten)
// After this function is executed, this OUT variable will be set with the number of rows that have been returned thus far.
// Each consecutive call to this function with the 'return-next-row' option set will return the next row in the result set, and also increment the 'return-next-row' variable to the number of rows that have been returned thus far
'limit'=>null, // With one argument (ie $limit="10"), the value specifies the number of rows to return from the beginning of the result set
// With two arguments (ie $limit="100,10"), the first argument specifies the offset of the first row to return, and the second specifies the maximum number of rows to return. The offset of the initial row is 0 (not 1):
'return-count'=>null, //OUT variable only. integer. after this function is executed, this variable will be set with the number of rows being returned. Usage ex: array('return-count'=>&$count)
'return-count-only'=>false, //if true, the return-count will be returned instead of the rows. A good optimization if you dont need to read any data from the rows and just need the rowcount of the search
}| array | $options | [optional] See description |
An array of Row instances that belong to this table, or an empty array if there are no matches. The returned array's keys=$primaryKeyValue, value=$Row. If the option 'return-count-only'=true, returns an integer of number of rows selected. To execute this function, this table must have a primary key, but this could probably be changed.
GetNewRow() : \SmartRow
Returns a new row from this table that can be added to the table by ->Commit(). Equivalent to creating a new instance of $this->ExtendedByClassName (if defined) or "new SmartRow($this->TableName, $this->Database);" As a shortcut, invoking the SmartTable directly with no parameters will call GetNewRow, i.e., $smartdb['tablename']() instead of $smartdb['tablename']->GetNewRow()
A new row from this table
FlattenLookupAssoc(array $flattenedLookupAssoc, string $key, mixed $val, string $column = '', string $condition = '=', string $operator = 'AND', string $first = true)
Takes a lookupAssoc array and flattens it to an array of just columnName => value for all elements of the array Only sets columnName => value if the given lookupAssoc sets the column equal to a particular value. if it sets the column to a condition or tries to lookup multiple values, the final returned array will not include that column
| array | $flattenedLookupAssoc | internal |
| string | $key | internal |
| mixed | $val | internal |
| string | $column | internal |
| string | $condition | internal |
| string | $operator | internal |
| string | $first | internal |
throws exception if an invalid column name is included