$Database
$Database : \SmartDatabase
Manages a single row within a table of the database.
It is recommended that you use SmartTable::GetNewRow() and SmartTable::LookupRow() instead of calling the SmartRow constructor explicitly. SmartTable::GetNewRow() provides a bottom-up method for creating new rows (which matches the rest of the SmartDb). SmartTable::LookupRow() provides a method for returning a single row based on the primary key (or, optionally, other columns). Calling this constructor explicitly will work all the same though (ex: "$newrow = new Product($db);" to get a new row, or "$row = new Product($db, 4);" to get the row with id 4)
To invoke this constructor, you can either do:
$row = new SmartRow("YOUR_TABLE_NAME", $Database, [$keyColumnValues=null], [$options=null]);Or extend your own class from the SmartRow. For example:
<?
class YOUR_CLASS_NAME extends SmartRow{
public function __construct($Database, $keyColumnValues=null, $options=null){
parent::__construct('YOUR_TABLE_NAME', $Database, $keyColumnValues, $options);
}
//implement custom functionality using $this
//---------- START EXAMPLE CUSTOM FUNCTIONALITY ------------//
//formats an alpha-numeric "Price" column
//if we have any alpha characters, return the price as is. otherwise, we'll format it up (i.e. could return "$12.43" or "CALL FOR PRICE")
public function GetFormattedPrice(){
$price = $this['Price'](); //$this is the current SmartRow instance, containing our row data for/from the database
if(strlen($price)==0) return "";
foreach(str_split($price) as $char){
if(ctype_alpha($char)){
return $price;
}
}
return '$'.number_format(self::ParseFloat($price), 2);
}
//helper function - turns something like "$12,300.50" or "$12300.50" or "12300.50" into "12300.5", which can then be formatted exactly as needed.
private static function ParseFloat($value){
return floatval(preg_replace('#^([-]*[0-9\.,\' \$]+?)((\.|,){1}([0-9-]{1,2}))*$#e', "str_replace(array('.', ',', \"'\", ' ', '$'), '', '\\1') . '.\\4'", $value));
}
//---------- END EXAMPLE CUSTOM FUNCTIONALITY ------------//
}
?>Or make your own class available to be extended upon further:
<?
class YOUR_CLASS_NAME extends SmartRow{
// There are 2 signatures for this (which allows for extending on this class, but using a different table)
// 1. __construct($Database, $keyColumnValues=null, $options=null) //uses table "YOUR_TABLE_NAME"
// 2. __construct($tableName, $Database, $keyColumnValues=null, $options=null) //uses table $tableName
public function __construct($arg1, $arg2=null, $arg3=null, $arg4=null){
if(is_string($arg1)) parent::__construct($arg1, $arg2, $arg3, $arg4);
else parent::__construct("YOUR_TABLE_NAME", $arg1, $arg2, $arg3);
}
//implement custom functionality using $this
}
?>Note: if creating your own class that extends SmartRow, YOUR_CLASS_NAME should be the same on that is set for SmartTable::$ExtendedByClassName
$Database : \SmartDatabase
$Table : \SmartTable
$DbManager : \DbManager
__construct(string $tableName, \SmartDatabase $Database, mixed $keyColumnValues = null, array $options = null) : \SmartRow
Manages a single row within the table specified in $tableName
If $dbManager is null, exceptions will be thrown anytime this class attempts to access the database. This should almost never be null except under special circumstances when you will not use the database at all, but need an 'in-memory' instance only
If the key column values are not passed to the constructor, the default will be null and this is assumed to be a new row to be inserted into the database.
If the key column values are passed, the row in the database with that key value will be looked up and used.
However, if the table's key is auto-increment and the passed key value does not exist in the database, an exception will be thrown whenever data is read or modified.
$options is an assoc-array, as follows:
$options = array(
'use-default-values'=true, //if set to false, the default values will not be set on any Cell of the new row
);| string | $tableName | |
| \SmartDatabase | $Database | |
| mixed | $keyColumnValues | [optional] If null, this row is assumed to be a new row. If not null: (1) For tables with multiple key columns, must be an assoc-array of columnName=>value of each key column. (2) For tables with 1 key column, this can be a single value of the key column to lookup (though the array will still work) |
| array | $options | [optional] See description |
IsInitialized() : boolean
Returns true if initial column values have been pulled from the database (if the row exist in the database. if it does not, this will return false)
true if initial column values have been pulled from the database (if the row exist in the database. if it does not, this will return false)
Refresh() : boolean
Forces re-initialization of this Row (pulling all values from the database for this id).
Good to use if you are storing a serialized version of this row and need to make sure all DB values are set.
You shouldn't need to use this much; it is mostly for internal use. Initialization is made to be completely automatic.
true if successfully retreived all columns from database, if this row has no key columns, or if this is a new row to insert later.
false if this is not a new row and values were not retreived because the key column(s) was/were not found in database table
HasErrors(array $options = null) : mixed
Returns a string of all current errors that exist within this row, or FALSE if no errors were found.
Row should not be committed to the database until this function returns false.
$options = array(
'ignore-key-errors'=>false, //If true: does not validate the key columns. If false: validates all columns
'only-verify-set-cells'=>false, //If true: only cells that have been set (i.e. isset()==true) will be verified (not recommended if this info will be committed to db). If false: all cells will be verified (should be used if this info will be committed to db).
'error-message-suffix'=>"<br>\n" //appended to each error message
)| array | $options | [optional] See description. |
A string of current errors that exist within this cell, or FALSE if no errors were found
GetColumnsInError(array $options = null) : array
Returns an array of all cells that are currently have an erroneous value or an empty array if no errors exist in any cells. The returned array's Key=$columnName, Value=$Cell.
Row should not be committed to the database until this function returns an empty array.
$options = array(
'ignore-key-errors'=>false, //If true: does not validate the key columns. If false: validates all columns
'only-verify-set-cells'=>false //If true: only cells that have been set (i.e. isset()==true) will be verified (not recommended if this info will be committed to db). If false: all cells will be verified (should be used if this info will be committed to db).
)| array | $options | [optional] See description |
an array of all cells that are currently have an erroneous value or an empty array if no errors exist in any cells. The returned array's Key=$columnName, Value=$Cell.
Column(string $columnName) : \SmartCell
Returns the Cell instance of this row from the specified $columnName. Shortcut: use array notation- $row['YOUR_COLUMN_NAME'] Alias for ->Cell()
| string | $columnName |
The Cell of this row with the given $columnName
SetKeyColumnValues(array $keyColumnValuesAssoc, boolean $updateNewKeyRowIfAlreadyExists, boolean $deleteOldKeyRowIfExists) : boolean
Attempts to get all key columns from the assoc-array (including POST, GET, SESSION, etc.) that belong to this Row/Table and sets them as values in this Row (for columns in which setting is allowed)
NOTE- Any key column that is not set in the array will be set to NULL as part of the key!!!!! So be careful about leaving out key columns.
$keyColumnValuesAssoc structure:
$keyColumnValuesAssoc = array('TableName'=>array('KeyColumn1'=>value, ...))| array | $keyColumnValuesAssoc | The array("TableName"=>array("KeyColumn1"=>"value", "keyColumn2"=>"value",...)) that will be the new key values for this instance. |
| boolean | $updateNewKeyRowIfAlreadyExists | If true: if the newly defined key exists in the database, the row will be updated with the current values of this instance upon calling Commit()... but if the newly defined key does not exist, this row will be inserted as a new row. |
| boolean | $deleteOldKeyRowIfExists | If true: if a row with the old key exists in the database (the one used in this Row prior to calling this method), it will be deleted (NOTE: old key row is deleted immediately if this is true, new row is not created in database until call to Commit()) . |
true if successfully changed the key of this instance, false if key was not changed (only if an existing row has been found for the new key defined and parameter updateNewKeyRowIfAlreadyExists==false)
SetNonKeyColumnValues(array $assocArray)
Attempts to get all NON KEY columns from the assoc-array (including POST, GET, SESSION, etc.) that belong to this Row and sets them as values in this Row (for columns in which setting is allowed)
Any column that is not set in array will not be modified
$assocArray structure:
$assocArray = array('TableName'=>array('ColumnName1'=>value, ...))| array | $assocArray | see function description |
SetColumnValues(array $assocArray, boolean $updateNewKeyRowIfAlreadyExists, boolean $deleteOldKeyRowIfExists)
Attempts to get all key and non-key columns from the assoc-array (including POST, GET, SESSION, etc.) that belong to this Row and sets them as values in this Row (for columns in which setting is allowed)
NOTE- Any non-key column that is not set in the array will not have its value changed, but any key column that is not set in the array will be set to NULL as part of the key!!!!! So be careful about leaving out key columns.
$assocArray structure:
$assocArray = array('TableName'=>array('ColumnName1'=>value, 'ColumnName2'=>value, ...))| array | $assocArray | see function description |
| boolean | $updateNewKeyRowIfAlreadyExists | If true: if the newly defined key exists in the database, the row will be updated with the current values of this instance upon calling Commit()... but if the newly defined key does not exist, this row will be inserted as a new row. |
| boolean | $deleteOldKeyRowIfExists | If true: if a row with the old key exists in the database (the one used in this Row prior to calling this method), it will be deleted (NOTE: old key row is deleted immediately if this is true, new row is not created in database until call to Commit()) . |
GetKeyColumnValues(array $assocArray = null, array $options = null) : array
Returns an array of all KEY columns and thier current values: array("TableName"=>array("ColumnName"=>currentValue,.
..))
| array | $assocArray | [optional] If provided, the column values will be added to this array and returned. Will be populated as such: array("TableName"=>array("ColumnName"=>currentValue,...)) |
| array | $options | [optional] see $options for self::GetColumnValues(); |
columns and values from this Row as an assoc array
GetNonKeyColumnValues(array $assocArray = null, array $options = null) : array
Returns an array of all NON-KEY columns and thier current values: array("TableName"=>array("ColumnName"=>currentValue,.
..)) Internally: forces initialization
| array | $assocArray | [optional] If provided, the column values will be added to this array and returned. Will be populated as such: array("TableName"=>array("ColumnName"=>currentValue,...)) |
| array | $options | [optional] see $options for self::GetColumnValues(); |
columns and values from this Row as an assoc array
GetColumnValues(array $assocArray = null, array $options = null) : array
Returns an array of columns and their current values: array("TableName"=>array("ColumnName"=>currentValue,.
..))
ALL columns are returned by default (keys and non-key columns). Can filter these... see $options below
Options are as follows:
$options = array(
'only-add-set-columns'=>false, //If false, populates the provided assoc-array with ALL get-able key columns. If true, populates the provided assoc-array with only the get-able columns that have been set (i.e. isset()==true)
'get-key-columns'=>true, //if true, key columns are returned in the array. if false, key columns are not returned in the array
'get-non-key-columns'=>true, //if true, non-key columns are returned in the array. if false, non-key columns are not returned in the array
'date-format'=>'' // set this to auto-format date columns. ref formarts that work with php's date() function (http://php.net/date)
)| array | $assocArray | [optional] If provided, the column values will be added to this array and returned. Will be populated as such: array("TableName"=>array("ColumnName"=>currentValue,...)) |
| array | $options | [optional] See description |
columns and values from this Row as an assoc array
LookupKeys(boolean $updateRowIfOneRowFound = true, array $options = null) : mixed
Looks up any column values that have been set on this row and returns an array of the key values that matched, or 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.
'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
)| boolean | $updateRowIfOneRowFound | [optional] If true and only 1 row is found when looking for rows with matching column values, this row instance will be updated to manage the matching row. (if true, take precedence over the 'return-count-only' option) |
| array | $options | [optional] See description |
An array of key values that match the columns that have been set in this Row or if the option 'return-count-only'=true, returns an integer of number of rows selected
GetShallowClone() : \SmartRow
Creates a new row instance with the same column values set as the instance you are cloning (key column values are not set).
A new row instance with the same column values set as the instance you are cloning (key column values are not set).
Commit(boolean $skipErrorChecking = false) : integer
Commits all current column values of this row to the database
| boolean | $skipErrorChecking | [optional] If true: the row will attempt to be committed to the database even if it has errors on the PHP level. Setting this to true is NEVER recommended unless you are absolutely certain you know what's up. |
the number of rows affected by the update call. If the row was not dirty (if column values have not been modified), -1 will be returned
Delete() : boolean
Deletes the row from the database with the key specified in this Row (if exists) Table must have a key column defined to use this function. There is no way we can be certain on which row to delete if no key columns are defined. Must use functions from the Table class to delete rows from tables with no key columns defined.
true if the row was deleted, false if the row does not exist (if more than 1 row was deleted, an exception is thrown. this would indicate a severe problem with data consistency)
__toString() : string
Used for debugging. Allows you to echo this instance directly to get the status. Wraps ToString().
Gets this row's status and columns with current values. Will will need to print/echo to see results.
This row's status and columns with current values. Will will need to print/echo to see results.
ToString(integer $emptyLinesBefore, integer $emptyLinesAfter) : string
Used for debugging.
Gets this row's status and columns with current values. Will will need to print/echo to see results.
| integer | $emptyLinesBefore | optional extra lines for debugging |
| integer | $emptyLinesAfter | optional extra lines for debugging |
This row's status and columns with current values. Will will need to print/echo to see results.
OnBeforeCommit(mixed $callbackFunction, mixed $functionScope = null)
Adds a $callbackFunction to be fired before the row has been committed to database (can be insert or update).
The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)
$eventObject in your $callbackFunction will be the Row instance that is firing the event callback
$eventArgs in your $callbackFunction will have the following keys:
array('cancel-event'=>&false); //setting 'cancel-event' to true within your $callbackFunction will prevent the event from continuing| mixed | $callbackFunction | the name of the function to callback that exists within the given $functionScope |
| mixed | $functionScope | [optional] the scope of the $callbackFunction, this may be an instance reference (a class that the function is within), a string that specifies the name of a class (that contains the static $callbackFunction), , or NULL if the function is in global scope |
OnAfterCommit(mixed $callbackFunction, mixed $functionScope = null)
Adds a $callbackFunction to be fired after the row has been committed to database (can be insert or update).
The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)
$eventObject in your $callbackFunction will be the Row instance that is firing the event callback
$eventArgs in your $callbackFunction will have the following keys:
array();| mixed | $callbackFunction | the name of the function to callback that exists within the given $functionScope |
| mixed | $functionScope | [optional] the scope of the $callbackFunction, this may be an instance reference (a class that the function is within), a string that specifies the name of a class (that contains the static $callbackFunction), , or NULL if the function is in global scope |
OnBeforeInsert(mixed $callbackFunction, mixed $functionScope = null)
Adds a $callbackFunction to be fired before the has been insertted to database (doesnt include update).
The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)
$eventObject in your $callbackFunction will be the Row instance that is firing the event callback
$eventArgs in your $callbackFunction will have the following keys:
array('cancel-event'=>&false); //setting 'cancel-event' to true within your $callbackFunction will prevent the event from continuing| mixed | $callbackFunction | the name of the function to callback that exists within the given $functionScope |
| mixed | $functionScope | [optional] the scope of the $callbackFunction, this may be an instance reference (a class that the function is within), a string that specifies the name of a class (that contains the static $callbackFunction), , or NULL if the function is in global scope |
OnAfterInsert(mixed $callbackFunction, mixed $functionScope = null)
Adds a $callbackFunction to be fired after the row has been insertted to database (doesnt include update).
The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)
$eventObject in your $callbackFunction will be the Row instance that is firing the event callback
$eventArgs in your $callbackFunction will have the following keys:
array();| mixed | $callbackFunction | the name of the function to callback that exists within the given $functionScope |
| mixed | $functionScope | [optional] the scope of the $callbackFunction, this may be an instance reference (a class that the function is within), a string that specifies the name of a class (that contains the static $callbackFunction), , or NULL if the function is in global scope |
OnBeforeUpdate(mixed $callbackFunction, mixed $functionScope = null)
Adds a $callbackFunction to be fired before the row has been updated to database (doesnt include insert).
The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)
$eventObject in your $callbackFunction will be the Row instance that is firing the event callback
$eventArgs in your $callbackFunction will have the following keys:
array('cancel-event'=>&false); //setting 'cancel-event' to true within your $callbackFunction will prevent the event from continuing| mixed | $callbackFunction | the name of the function to callback that exists within the given $functionScope |
| mixed | $functionScope | [optional] the scope of the $callbackFunction, this may be an instance reference (a class that the function is within), a string that specifies the name of a class (that contains the static $callbackFunction), , or NULL if the function is in global scope |
OnAfterUpdate(mixed $callbackFunction, mixed $functionScope = null)
Adds a $callbackFunction to be fired after the row has been updated to database (doesnt include insert).
The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)
$eventObject in your $callbackFunction will be the Row instance that is firing the event callback
$eventArgs in your $callbackFunction will have the following keys:
array();| mixed | $callbackFunction | the name of the function to callback that exists within the given $functionScope |
| mixed | $functionScope | [optional] the scope of the $callbackFunction, this may be an instance reference (a class that the function is within), a string that specifies the name of a class (that contains the static $callbackFunction), , or NULL if the function is in global scope |
OnBeforeDelete(mixed $callbackFunction, mixed $functionScope = null)
Adds a $callbackFunction to be fired before the row has been deleted from database.
The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)
$eventObject in your $callbackFunction will be the Row instance that is firing the event callback
$eventArgs in your $callbackFunction will have the following keys:
array('cancel-event'=>&false); //setting 'cancel-event' to true within your $callbackFunction will prevent the event from continuing| mixed | $callbackFunction | the name of the function to callback that exists within the given $functionScope |
| mixed | $functionScope | [optional] the scope of the $callbackFunction, this may be an instance reference (a class that the function is within), a string that specifies the name of a class (that contains the static $callbackFunction), , or NULL if the function is in global scope |
OnAfterDelete(mixed $callbackFunction, mixed $functionScope = null)
Adds a $callbackFunction to be fired after the row has been deleted from database.
The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)
$eventObject in your $callbackFunction will be the Row instance that is firing the event callback
$eventArgs in your $callbackFunction will have the following keys:
array();| mixed | $callbackFunction | the name of the function to callback that exists within the given $functionScope |
| mixed | $functionScope | [optional] the scope of the $callbackFunction, this may be an instance reference (a class that the function is within), a string that specifies the name of a class (that contains the static $callbackFunction), , or NULL if the function is in global scope |
OnSetColumnValue(mixed $callbackFunction, mixed $functionScope = null)
Adds a $callbackFunction to be fired when <b>ANY</b> column of this row has been set (though not necessarily 'changed')
The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)
$eventObject in your $callbackFunction will be the Row instance that is firing the event callback
$eventArgs in your $callbackFunction will have the following keys:
array(
'cancel-event'=>&false, //setting 'cancel-event' to true within your $callbackFunction will prevent the event from continuing
'Cell'=>&object, //the Cell that fired the event (Cell's contain all Column functionality and properties)
'current-value'=>object, //the current value of this column, BEFORE it has changed to 'new-value'
'new-value'=>&object, //the value that this column is going to be set to, replacing the 'current-value'
);| mixed | $callbackFunction | the name of the function to callback that exists within the given $functionScope |
| mixed | $functionScope | [optional] the scope of the $callbackFunction, this may be an instance reference (a class that the function is within), a string that specifies the name of a class (that contains the static $callbackFunction), , or NULL if the function is in global scope |
OnBeforeColumnValueChanged(mixed $callbackFunction, mixed $functionScope = null)
Adds a $callbackFunction to be fired before <b>ANY</b> column of this row has been changed
The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)
$eventObject in your $callbackFunction will be the Row instance that is firing the event callback
$eventArgs in your $callbackFunction will have the following keys:
array(
'cancel-event'=>&false, //setting 'cancel-event' to true within your $callbackFunction will prevent the event from continuing
'Cell'=>&object, //the Cell that fired the event
'current-value'=>object, //the current value of this column, BEFORE it has changed to 'new-value'
'new-value'=>&object, //the value that this column is going to be set to, replacing the 'current-value'
);| mixed | $callbackFunction | the name of the function to callback that exists within the given $functionScope |
| mixed | $functionScope | [optional] the scope of the $callbackFunction, this may be an instance reference (a class that the function is within), a string that specifies the name of a class (that contains the static $callbackFunction), , or NULL if the function is in global scope |
OnAfterColumnValueChanged(mixed $callbackFunction, mixed $functionScope = null)
Adds a $callbackFunction to be fired after <b>ANY</b> column of this row has been changed The signature of your $callbackFunction should be as follows: yourCallbackFunctionName($eventObject, $eventArgs)
$eventObject in your $callbackFunction will be the Row instance that is firing the event callback
$eventArgs in your $callbackFunction will have the following keys:
array(
'Cell'=>&object, //the Cell that fired the event
'current-value'=>object, //the current value of this column, AFTER it has been changed from 'old-value'
'old-value'=>&object, //the value that this column was set to before it was updated with the 'current-value'
);| mixed | $callbackFunction | the name of the function to callback that exists within the given $functionScope |
| mixed | $functionScope | [optional] the scope of the $callbackFunction, this may be an instance reference (a class that the function is within), a string that specifies the name of a class (that contains the static $callbackFunction), , or NULL if the function is in global scope |
GetPassedValueForCell(string $tableName, string $columnName, array $keyColumnValuesAssoc, \SmartCell $Cell = null) : mixed
Helper function for SetKeyColumnValues() above Get the passed value within $keyColumnValuesAssoc.
.. either matches the real column name or the first found alias (ignores multiple matches)
| string | $tableName | |
| string | $columnName | |
| array | $keyColumnValuesAssoc | |
| \SmartCell | $Cell |
|
The matching object for this $Cell, found within $keyColumnValuesAssoc
TryGetDatabaseValues(boolean $exceptionOnError = true) : boolean
Gets all column values from the database and sets each as a local variable
| boolean | $exceptionOnError | internal - true to throw exception on error, otherwise fails silently |
true if successfully retrieved all columns from database, if this Row/Table has no key columns, or if this is a new row to insert later.
false if this is not a new row and values were not retreived because the key column(s) was/were not found in database table