Properties

$Database

$Database : \SmartDatabase

Type

\SmartDatabase — The Database that contains this Table

$TableName

$TableName : \SmartTable

Type

\SmartTable — The name of the Table

$IsAbstract

$IsAbstract : boolean

Type

boolean — Defaults to false. If true, this table will not actually be created in the database, but will be available to be inherited from using the $table->InheritColumnsFromTable() method.

$AutoCommit

$AutoCommit : boolean

Type

boolean — Defaults to false. If true, anytime a column value is set within this table, the row is automatically committed ( $row->Commit() ). Otherwise, you need to commit by hand.

$ExtendedByClassName

$ExtendedByClassName : string

Type

string — The class that extends from a row within this table to implement custom functionality

$AutoRefresh

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

Type

boolean

$_columns

$_columns : 

Type

$_columnAliases

$_columnAliases : 

Type

$_keyColumns

$_keyColumns : 

Type

$_nonKeyColumns

$_nonKeyColumns : 

Type

$_autoIncrementKeyColumns

$_autoIncrementKeyColumns : 

Type

$_nonAutoIncrementKeyColumns

$_nonAutoIncrementKeyColumns : 

Type

$_storedDbManagers

$_storedDbManagers : 

Type

$_primaryKeyExists

$_primaryKeyExists : 

Type

$_primaryKeyIsComposite

$_primaryKeyIsComposite : 

Type

$_primaryKeyIsNonComposite

$_primaryKeyIsNonComposite : 

Type

$_primaryKeyIsNonCompositeAutoIncrement

$_primaryKeyIsNonCompositeAutoIncrement : 

Type

$_primaryKeyIsNonCompositeNonAutoIncrement

$_primaryKeyIsNonCompositeNonAutoIncrement : 

Type

$_inheritsTableNames

$_inheritsTableNames : string

If this table inherits other tables, this array will contain the names of the other table

Type

string — The name of the table that $this table inherits from.

$_arrayMaxDepth

$_arrayMaxDepth : 

Type

Methods

__construct()

__construct(string  $tableName) : \SmartTable

Constructor

Parameters

string $tableName

The name of the table

Returns

\SmartTable

GetAllColumns()

GetAllColumns() : array

Returns an assoc of all Columns. The returned array's key=$columnName, value=$Column

Returns

array —

An assoc of all Columns. The returned array's key=$columnName, value=$Column

GetAllColumnAliases()

GetAllColumnAliases() : array

Returns an assoc of all column aliases. The returned array's key=$columnAlias, value=$realColumnName

Returns

array —

An assoc of all column aliases. The returned array's key=$columnAlias, value=$realColumnName

GetKeyColumns()

GetKeyColumns() : array

Returns an assoc of all key columns. The returned array's key=$columnAlias, value=$realColumnName

Returns

array

GetNonKeyColumns()

GetNonKeyColumns() : array

Returns an assoc of all non key columns. The returned array's key=$columnAlias, value=$realColumnName

Returns

array

PrimaryKeyExists()

PrimaryKeyExists() : boolean

Returns TRUE if this table contains a primary key, FALSE otherwise.

Returns

boolean —

TRUE if this table contains a primary key, FALSE otherwise.

Refresh()

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

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

Parameters

\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?

Returns

boolean —

True if the column was added successfully, false otherwise (may happen if the column exists and $replaceExisting == false)

GetColumn()

GetColumn(string  $columnName) : \SmartColumn

Returns the $columnName Column. Shortcut: use array notation- $table['YOUR_COLUMN_NAME']

Parameters

string $columnName

The name of the column to get.

Returns

\SmartColumn

The column requested.

RemoveColumn()

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

Parameters

string $columnName

The name of the column to remove.

Returns

boolean —

Always returns true. If the given $columnName does not exist, an exception is thrown.

ColumnExists()

ColumnExists(string  $columnName) : boolean

Returns true if the column exists, false otherwise.

Parameters

string $columnName

Returns

boolean —

true if the column exists, false otherwise.

GetInheritedTableNames()

GetInheritedTableNames() : array

If this table inherits other tables, the returned array will contain the names of the other table.

Will be an empty array if no inheritance

Returns

array —

The name of the table that $this table inherits from.

InheritColumnsFromTable()

InheritColumnsFromTable(\SmartTable  $Table) 

All columns (and relations associated with those columns) from the given $Table are added to this $Table (structure only, no data!)

Parameters

\SmartTable $Table

count()

count() : integer

For the Countable interface, this allows us to do count($table) to return the number of rows in the table.

Returns

integer —

The number of rows in this table.

LookupRows()

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
)

Parameters

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

Returns

mixed —

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

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

Parameters

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

Returns

\SmartRow

A Row instance matching the criteria of $lookupVals. The returned row may or may not Exist

LookupColumnValues()

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
}

Parameters

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

Returns

mixed —

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

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

Parameters

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)

Returns

mixed —

The value of the column found, or FALSE if no row exists matching the criteria of $lookupAssoc

DeleteRow()

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

Parameters

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

Returns

integer —

number of rows deleted (1 or 0)

DeleteRows()

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

Parameters

array $lookupAssoc

An assoc-array of column=>value to lookup. For example: array("column1"=>"lookupVal", "column2"=>"lookupVal", ...)

array $options

[optional] See description

Returns

integer —

the number of rows deleted

DeleteAllRows()

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

Parameters

array $options

[optional] See description

Returns

integer —

the number of rows deleted

GetAllRows()

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
 }

Parameters

array $options

[optional] See description

Returns

mixed —

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

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

Returns

\SmartRow

A new row from this table

ReturnSmartRows()

ReturnSmartRows(  $sqlResult,   $keyColumnName,   $returnAssoc = false,   $returnNextRow = false) 

Parameters

$sqlResult
$keyColumnName
$returnAssoc
$returnNextRow

FlattenLookupAssoc()

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

Parameters

array $flattenedLookupAssoc

internal

string $key

internal

mixed $val

internal

string $column

internal

string $condition

internal

string $operator

internal

string $first

internal

Throws

\Exception

throws exception if an invalid column name is included