Properties

$Table

$Table : \SmartTable

Type

\SmartTable — The Table that contains this Column

$ColumnName

$ColumnName : string

Type

string — The name of the column

$IsAlias

$IsAlias : boolean

Type

boolean — True if the column is an alias for another column, false if this is an actual column

$DisplayName

$DisplayName : string

Type

string — The column's friendly display name

$DataType

$DataType : string

Type

string — The SQL data type of this column. Check XmlSchema.xsd for all possible values of this column. Last I checked, it was: "char|varchar|text|mediumtext|longtext|blob|mediumblob|longblob|tinyint|smallint|mediumint|int|bigint|float|double|decimal|date|datetime|timestamp|time|binary|enum\((\s*'[ a-zA-Z0-9/_-]+'\s*,)*(\s*'[ a-zA-Z0-9/_-]+'\s*)\)|array|object";

$Collation

$Collation : string

Type

string — The SQL collation for this column (ie "latin1_swedish_ci", "utf8_general_ci", "utf8mb4_unicode_ci", etc)

$IsDateColumn

$IsDateColumn : boolean

Type

boolean — True if this is a date column, false otherwise. Should be computed based of the $DataType at Database initialization

$IsTimezoneColumn

$IsTimezoneColumn : boolean

Type

boolean — True Mostly for internal use, if this is a date column that supports timezones, false otherwise. Should be computed based of the $DataType at Database initialization.

$DefaultTimezone

$DefaultTimezone : string

Type

string — If this is a date column and a TimeZone is set on this column (or the database-level), then ALL dates values stored in this column will be converted to UTC time for storing in the DB, then returned in the set timezone. Empty will use system time and won't touch dates (not recommended) There is a SmartDatabase level $DefaultTimezone, and also a SmartColumn $DefaultTimezone. If both values are set, the column's default will take precedence.

$IsSerializedColumn

$IsSerializedColumn : boolean

Type

boolean — True if this is a serialized or compressed column, false otherwise. Should be computed based of the $DataType

$PossibleValues

$PossibleValues : array

Type

array — An array of all possible values that this column accepts. null or empty array means no values are restricted. In theory, the column does NOT have to be an 'enum' data type for this to work... it will work with any column data type... but why would you do that?

$MinSize

$MinSize : integer

Type

integer — The minimum number of characters allowed for this column. Can be null.

$MaxSize

$MaxSize : mixed

Type

mixed — The size of the column. For DataType=="decimal" columns, this is "PRECISION,SCALE" (ie "14,4"). For other columns, this represents the maximum number of characters allowed for this column. Can be null.

$AllowGet

$AllowGet : boolean

Type

boolean — Default it true. Controls access to retrieving values from this column (defaults to true in XmlSchema.xsd if using an xml schema as your db structure)

$AllowSet

$AllowSet : boolean

Type

boolean — Default it true. Controls access to setting values from this column (defaults to true in XmlSchema.xsd if using an xml schema as your db structure)

$TrimAndStripTagsOnSet

$TrimAndStripTagsOnSet : boolean

Type

boolean — If true, will trim() and strip_tags() anytime a value is set in this column (defaults to false in XmlSchema.xsd if using an xml schema as your db structure)

$AllowLookup

$AllowLookup : boolean

Type

boolean — Default it true. Controls access to looking up values from this column (defaults to true in XmlSchema.xsd if using an xml schema as your db structure)

$AllowGetAll

$AllowGetAll : boolean

Type

boolean — Default it true. Controls access to getting all values from this column (defaults to false in XmlSchema.xsd if using an xml schema as your db structure (why false?))

$DefaultValue

$DefaultValue : mixed

Type

mixed — The default value for this column. Can be null.

$Example

$Example : mixed

Type

mixed — The example value for this column. Can be null. Used for form object "placeholders"

$IsUnique

$IsUnique : boolean

Type

boolean — True if this column is specified as UNIQUE

$IsPrimaryKey

$IsPrimaryKey : boolean

Type

boolean — True if this column is a primary key column

$IsAutoIncrement

$IsAutoIncrement : boolean

Type

boolean — True if this column is an auto-increment column

$FulltextIndex

$FulltextIndex : boolean

Type

boolean — True if this column is specified as a fulltext index for searching

$NonuniqueIndex

$NonuniqueIndex : boolean

Type

boolean — True if this column is specified as a non-unique index for searching

$DefaultFormType

$DefaultFormType : string

Type

string — Default it "text". See XmlSchema.xsd for possible values (Last I checked, it was: "text", "password", "checkbox", "radio", "select", "textarea", "hidden", "colorpicker", "datepicker", "slider" ... the last 3, are for use with jQuery UI)

$IsRequired

$IsRequired : boolean

Type

boolean — True if data is required for this column, false if null is an acceptable value

$IsRequiredMessage

$IsRequiredMessage : string

Type

string — The error message to show if the field is required. If null, a decent default message will be used (i.e. "Phone Number" is required.).

$RegexCheck

$RegexCheck : string

Type

string — Regex the value of this column must match against. Can be null. Uses preg_match() in PHP... automatically wraps it with slashes in PHP (i.e. preg_match('/'.$this->RegexCheck.'/i')) and javascript error checking (SmartFormValidation_jQueryValidate.php)... so don't wrap your own! Both php and javascript can only do case-insensitive matching at the moment, but both are supported with a single value here.

$RegexFailMessage

$RegexFailMessage : string

Type

string — The error message to show if the column value does not match against $RegexCheck. If null, a decent default message will be used (i.e. Invalid value for "Phone Number").

$SortOrder

$SortOrder : integer

Type

integer — Mostly for internal/backend nitty-gritties. This value represents where this column's position is in comparison with other columns in the table. Used when Synchronizing with the database. 1 is the first column, 2 is the second, etc.

Methods

GetMaxLength()

GetMaxLength() : integer

Uses the column's $MaxSize property to determine what that maximum number of characters that are allowed in this column, regardless of data type (i.e. decimals are different than regular MaxSize)

Returns

integer —

Returns the maximum number of characters this column can hold. If no MaxSize is set, returns null.

__construct()

__construct(string  $columnName) : \SmartColumn

Constructor

Parameters

string $columnName

The name of the column. You should never really call this explicitly. Instead, do a $SmartDatabase['TABLE_NAME']['COLUMN_NAME'] to get the column (i.e. $db['Products']['Price']).

Returns

\SmartColumn

GetRelations()

GetRelations() : array

Returns an array of all relations. array($key=tableName => $val=array($key=>columnName, $val=true);

Returns

array —

All relations of this Column

AddRelation()

AddRelation(string  $tableName, string  $columnName, boolean  $addRelationOnRelatedColumn = true) : boolean

Adds a relation to this column. Returns true if success, false if the relation already exists.

Parameters

string $tableName

The related table's name

string $columnName

The related column's name

boolean $addRelationOnRelatedColumn

[optional] If true (default), the related column will be updated with the relation too. If false, you will need to add this relation to the related column by hand.

Returns

boolean —

true if success, false if the relation already existed.

RemoveRelation()

RemoveRelation(string  $tableName, string  $columnName, boolean  $removeRelationOnRelatedColumn = true) : boolean

Removes a relation from this column. Returns true if success, false if the column was not found as a current relation.

Parameters

string $tableName

The related table's name

string $columnName

The related column's name

boolean $removeRelationOnRelatedColumn

[optional] If true (default), the related column will have this relation removed as well. If false, you will need to remove the relation on the related column by hand.

Returns

boolean —

true if success, false if the column was not found as a current relation.

HasRelation()

HasRelation(string  $tableName, string  $columnName) : boolean

Returns true if a relation exists between this column and the passed $tableName, $columnName. false otherwise

Parameters

string $tableName
string $columnName

Returns

boolean —

true if a relation exists between this column and the passed $tableName, $columnName. false otherwise

GetAliases()

GetAliases(array  $options = null) : array

Returns an array of all aliases. array($key=alias => $val=true);

    $options = array(
        'names-only' => false, //if true, the returned array will just be an array of alias names
    )

Parameters

array $options

[optional] See description

Returns

array —

All aliases of this Column

AddAlias()

AddAlias(string  $alias) : boolean

Removes an alias from the column. Returns true if success, false if the column alias does not currently exist.

Parameters

string $alias

An alias for this column

Returns

boolean —

true if success, false if the alias already exists

RemoveAlias()

RemoveAlias(string  $alias) : boolean

Removes an alias from the column. Returns true if success, false if the column alias does not currently exist.

Parameters

string $alias

The alias to remove from this column

Returns

boolean —

true if success, false if the column alias does not exist.

HasAlias()

HasAlias(string  $alias) : boolean

Returns true if a this column is alised by the given $alias, false otherwise.

Parameters

string $alias

The alias to check

Returns

boolean —

true if a this column is alised by the given $alias, false otherwise.

NormalizeValue()

NormalizeValue(mixed  $value) : mixed

If the column is a special data type, the value from the database may need to be normalized for use.

Serialized Columns are unserialized. Timestamp Columns will have the timestamp abbreviation appended to the database value (only if a $DefaultTimezone is set on the Database or Column level).

Parameters

mixed $value

Returns

mixed —

the normalized value based on the Column's data type

AppendTimezone()

AppendTimezone(  $value) 

Parameters

$value

GetAllValues()

GetAllValues(array  $options = null) : mixed

Gets all values in all rows for this column, 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 and the row as its value. ie array("2"=>$row,...) instead of just array($row,...);
    '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

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.

GetMaxValue()

GetMaxValue(array  $lookupAssoc = null, array  $options = null) : mixed

Returns the maximum value for this column as stored in the db. returns null if no rows are in the table. Shortcut for GetAggregate('max',.

..)

Parameters

array $lookupAssoc

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

array $options

[optional] (none yet)

Returns

mixed —

The maximum value of the column, optionally filtered by $lookupAssoc

GetMinValue()

GetMinValue(array  $lookupAssoc = null, array  $options = null) : mixed

Returns the minimum value for this column as stored in the db. returns null if no rows are in the table. Shortcut for GetAggregate('min',.

..)

Parameters

array $lookupAssoc

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

array $options

[optional] (none yet)

Returns

mixed —

The minimum value of the column, optionally filtered by $lookupAssoc

GetAggregateValue()

GetAggregateValue(string  $aggregateFunction, array  $lookupAssoc = null, array  $options = null) : mixed

Runs an aggregate function over a column and returns the value. Function names include: "max", "min", "sum", "avg", "count-distinct" TODO: Currently has hard coded SQL for MySQL.

.. need to move this to the DbManager at some point, somehow

Parameters

string $aggregateFunction

The function to run on the column: "max", "min", "sum", "avg", "num-distinct"

array $lookupAssoc

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

array $options

[optional] (none yet)

Returns

mixed —

The aggregate value of the column, optionally filtered by $lookupAssoc

LookupRows()

LookupRows(mixed  $value, array  $options = null) : mixed

Looks up an array of all Row instances that match the given column $value, or an empty array if there is no match. Alternatively, 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.
    '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,...);
    '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-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

mixed $value

The $value to lookup in this column

array $options

[optional] See description

Returns

mixed —

Gets an array of all Row instances that match the given $value, or an empty array if there is no match. Alternatively, if the option 'return-count-only'=true, returns an integer of number of rows selected.

LookupRow()

LookupRow(mixed  $value) : \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 column=>value 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.

Parameters

mixed $value

The $value to lookup in this column

Returns

\SmartRow

Looks up an a row instance 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 column=>value set by default (excluding auto-increment primary key columns when the row does not exist)

DeleteRows()

DeleteRows(mixed  $value, array  $options = null) : integer

Deletes all rows with where the column value matches the passed $value

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

the value to look-up in this column

array $options

[optional] See description

Returns

integer —

the number of rows deleted

SetAllValues()

SetAllValues(mixed  $value, array  $options = null) : integer

Sets the given $value to the column for every row in the table. Returns the number of rows affected.

Options are as follows:

$options = array(
    'skip-callbacks'=>false, //If true, all row-level callbacks AND error-checking will be skipped. This can substantially improve the performance on very large tables.
    'skip-error-checking'=>false //Only available in conjunction with 'skip-callbacks'=true. If both of these options are true, all row-level error checking will be skipped when each updated Row is Commit()'ed.
}

Parameters

mixed $value

The scalar value to set in this column for every row in the table

array $options

[optional] See description

Returns

integer —

the number of rows affected

VerifyValueType()

VerifyValueType(object  $value,   $options = null) : \nothing.

Anytime we set the value of this cell, we need to fix boolean types to '1' and '0' and make sure we're not setting to an object.

Options are as follows:

$options = array(
    'skip-serialized-data'=>false, //If true, serialized data will be left as-is (i.e. for using strings in lookup assocs)
}

Parameters

object $value

modifies this value BY REFERENCE

$options

Returns

\nothing.

GetSerializedValue()

GetSerializedValue(mixed  $value) : \the

If the data type serializes data (array, object), this function convers the given $value to the serialized data

Parameters

mixed $value

the value to serialize

Returns

\the —

serialized value

GetUnserializedValue()

GetUnserializedValue(mixed  $value) : \the

If the data type unserializes data (array, object), this function convers the given $value to the unserialized data

Parameters

mixed $value

the value to unserialize

Returns

\the —

unserialized value

SerializeArray()

SerializeArray(array  $array) : \the

Serializes the given $array

Parameters

array $array

the array to serialize

Returns

\the —

serialized array

SerializeObject()

SerializeObject(object  $object) : \the

Serializes the given $object

Parameters

object $object

the object to serialize

Returns

\the —

serialized object

UnserializeArray()

UnserializeArray(array  $serializedArray) : \the

Unserializes the given $array

Parameters

array $serializedArray

the array to unserialize

Returns

\the —

unserialized array

UnserializeObject()

UnserializeObject(object  $serializedObject) : \the

Unserializes the given $object

Parameters

object $serializedObject

the object to unserialize

Returns

\the —

unserialized object

GetDefaultFormObjectName()

GetDefaultFormObjectName(string  $nameSuffix = '') : string

Returns the default html name attribute that will be used when getting a form object for this cell

Parameters

string $nameSuffix

[optional] A suffix to add the the end of the column name

Returns

string —

The default html name attribute that will be used when getting a form object for this cell

GetDefaultFormObjectId()

GetDefaultFormObjectId(string  $nameSuffix = '') : string

Returns the default html ID attribute that will be used when getting a form object for this cell

Parameters

string $nameSuffix

[optional] A suffix to add the the end of the column name

Returns

string —

The default name html ID attribute that will be used when getting a form object for this cell