\Dewdrop\FieldsOptionPairs

The OptionPairs class makes it easy to retrieve a list of key-value pairs for use as options for a field's value, typically a foreign key.

Summary

Methods
Properties
Constants
__construct()
getTableName()
getTitleColumn()
detectTitleColumn()
setOptions()
setTableName()
setValueColumn()
setTitleColumn()
getSelect()
setSelect()
getStmt()
setStmt()
fetch()
fetchJsonWrapper()
No public properties found
No constants found
formatJsonWrapper()
generateStmt()
getSelectColumns()
hasTitleColumn()
findTitleColumnFromMetadata()
findValueColumnFromMetadata()
filterStmt()
orderStmt()
loadTableMetadata()
$dbAdapter
$tableName
$valueColumn
$titleColumn
$stmt
N/A
No private methods found
No private properties found
N/A

Properties

$dbAdapter

$dbAdapter : \Dewdrop\Db\Adapter

The database adapter that will be used to retrieve the options.

Type

\Dewdrop\Db\Adapter

$tableName

$tableName : string

The name of the table from which the options will be retrieved.

Type

string

$valueColumn

$valueColumn : string

The name of the column that should be used for the value.

Type

string

$titleColumn

$titleColumn : \Dewdrop\Db\Expr|string

The name of the column that should be used for the option's title.

A \Dewdrop\Db\Expr can also be used for the title column, if you'd like to concatenate multiple columns or format them.

Type

\Dewdrop\Db\Expr|string

$stmt

$stmt : \Dewdrop\Db\Select

The \Dewdrop\Db\Select that will be used to retrieve the options.

Type

\Dewdrop\Db\Select

Methods

__construct()

__construct(\Dewdrop\Db\Adapter  $dbAdapter) 

Create new OptionPairs object using supplied DB adapter.

Parameters

\Dewdrop\Db\Adapter $dbAdapter

getTableName()

getTableName() : string

Get the table name.

Returns

string

getTitleColumn()

getTitleColumn() : \Dewdrop\Db\Expr|string

Get the title column.

Returns

\Dewdrop\Db\Expr|string

detectTitleColumn()

detectTitleColumn() 

setOptions()

setOptions(array  $options) : \Dewdrop\Fields\OptionPairs

Set one more options on this object. If a setter is not available for the option designated by keys in your options array, an exception will be thrown.

Parameters

array $options

Throws

\Dewdrop\Exception

Returns

\Dewdrop\Fields\OptionPairs

setTableName()

setTableName(string  $tableName) : \Dewdrop\Fields\OptionPairs

Set the name of the table where options can be found.

Parameters

string $tableName

Returns

\Dewdrop\Fields\OptionPairs

setValueColumn()

setValueColumn(string  $valueColumn) : \Dewdrop\Fields\OptionPairs

Set the name of the column that should be used for the value of each option.

Parameters

string $valueColumn

Returns

\Dewdrop\Fields\OptionPairs

setTitleColumn()

setTitleColumn(\Dewdrop\Db\Expr|string  $titleColumn) : \Dewdrop\Fields\OptionPairs

Set the name of the column that should be used for the title of each option. You can also use a \Dewdrop\Db\Expr here, if you'd like to do any special formatting or concatenate multiple columns.

Parameters

\Dewdrop\Db\Expr|string $titleColumn

Returns

\Dewdrop\Fields\OptionPairs

getSelect()

getSelect() : \Dewdrop\Db\Select

An alias for getStmt().

Returns

\Dewdrop\Db\Select

getStmt()

getStmt() : \Dewdrop\Db\Select

Get the \Dewdrop\Db\Select that will be used for retrieving options. If one isn't already available, it will be generated using the other properties on this object. You can call this method to get a good starting point for your SQL and manipulate it from there to apply any specials filters or sorts.

Returns

\Dewdrop\Db\Select

setStmt()

setStmt(\Dewdrop\Db\Select  $stmt) : \Dewdrop\Fields\OptionPairs

Manually set the \Dewdrop\Db\Select that will be used to retrieve options. This can be useful if you'd prefer to skip the default SQL generation logic completely.

Parameters

\Dewdrop\Db\Select $stmt

Returns

\Dewdrop\Fields\OptionPairs

fetch()

fetch() : array

Fetch the option pairs using the DB adapter.

Returns

array

fetchJsonWrapper()

fetchJsonWrapper() : array

Fetch the option pairs and wrap them in an array that will preserve their sort order when passed by to the client in JSON. If you just use a normal key-value array here, like you'd get from fetch(), the options will be sorted by their numeric key value in JSON/JavaScript rather than by the sort order defined in the option Select statement.

Returns an array where each element is another associated array containing "value" and "title" keys.

Returns

array

formatJsonWrapper()

formatJsonWrapper(array  $options) 

Parameters

array $options

generateStmt()

generateStmt() : \Dewdrop\Db\Select

Generate a \Dewdrop\Db\Select object for retrieving options using the metadata of the option table. Prior to this method being called, at least the $tableName property must be set. We will attempt to guess the value and title columns, if they are not set, but the table is needed to retrieve the other metadata.

Returns

\Dewdrop\Db\Select

getSelectColumns()

getSelectColumns() 

hasTitleColumn()

hasTitleColumn() : boolean

Check to see if a title column has been set.

Returns

boolean

findTitleColumnFromMetadata()

findTitleColumnFromMetadata(array  $columns) : string

This method is called when no title column has been set prior to the generateStmt() method being called. If the options table has a "name" or "title" column, those will be used. If not, we'll use the first CHAR or VARCHAR column found in the table metadata. If we still have not found a suitable candidate, an exception will be thrown telling the developer to manually specify the title column.

Parameters

array $columns

The "columns" portion of the table metadata.

Throws

\Dewdrop\Fields\OptionPairs\TitleColumnNotDetectedException

Returns

string

findValueColumnFromMetadata()

findValueColumnFromMetadata(array  $columns) : string

This method is called if now value column has been set by the time generateStmt() is called. We'll attempt to use the first column from the options table that is part of the primary key. If no primary key column is found (what have you done!?), we'll throw an exception asking the developer to manually specify the value column.

Parameters

array $columns

Throws

\Dewdrop\Exception

Returns

string

filterStmt()

filterStmt(array  $columns, \Dewdrop\Db\Select  $stmt) : \Dewdrop\Db\Select

Attempt to apply some default filters to a generated options statement. Dewdrop supported two similar conventions here: "active" columns and "deleted" columns. If your options table has an "active" column, only options for which "active" is true will be included.

If your options table has a "deleted" column, options with that column set as true will be excluded.

Parameters

array $columns

The columns portion of the table metadata.

\Dewdrop\Db\Select $stmt

Returns

\Dewdrop\Db\Select

orderStmt()

orderStmt(array  $columns, \Dewdrop\Db\Select  $stmt) : \Dewdrop\Db\Select

Attempt to order the options statement using the options table metadata. Dewdrop supports two manual sorting columns by convention: sort_index and sort_order. If either of those columns is present in your options table, the options will be sorted by them. Otherwise, we'll sort by the title column.

Parameters

array $columns

The columns portion of the table metadata.

\Dewdrop\Db\Select $stmt

Returns

\Dewdrop\Db\Select

loadTableMetadata()

loadTableMetadata() : array

Load the metadata for the options table.

Throws

\Dewdrop\Exception

Returns

array