\Dewdrop\DbField

Field objects provide a way to leverage database metadata throughout your application and establish a centralized source of information about how the field should be labeled, any notes that should be displayed with it, any validators that should be included, etc.

It implements the helper callback assignment and permissions management of FieldInterface, leaving the ID/label handling up to the sub-classes (i.e. \Dewdrop\Db\Field and \Dewdrop\Fields\Field). ID/label handling differs quite a lot in the 2 primary types of fields. For DB fields, sane default are available from the DB metadata, whereas for custom fields, all this information must be defined manually.

Note that in the case of custom fields, all capabilities (visibility, sortability, filterability, and editability) are forbidden by default. In DB fields, on the other hand, these capabilities are all enabled by default. Similarly the situation with ID/label handling, we do this because database fields can provide sane default by leveraging information from the schema. Custom fields, though, need to be thought out and configured manually.

To support the storage of the permissions settings for this field, a scheme using arrays is deployed:

1) If the permissions/capability array contains only \Dewdrop\Fields\FieldAbstract::AUTHORIZATION_ALLOW_ALL, it is allowed for everyone.

2) If it contains nothing, it is forbidden for everyone.

3) Otherwise, it will contains one ore more "roles" which can be any value that can be passed along to the UserInterface object to see if the current user can use that capability.

Summary

Methods
Properties
Constants
setNote()
getNote()
setOptions()
resetFieldsSet()
setFieldsSet()
add()
setVisible()
getVisibleSetting()
isVisible()
allowVisibilityForRole()
forbidVisibilityForRole()
setSortable()
getSortableSetting()
isSortable()
allowSortingForRole()
forbidSortingForRole()
setFilterable()
getFilterableSetting()
isFilterable()
allowFilteringForRole()
forbidFilteringForRole()
setEditable()
getEditableSetting()
isEditable()
allowEditingForRole()
forbidEditingForRole()
assignHelperCallback()
hasHelperCallback()
getHelperCallback()
removeHelperCallback()
getHelperFilters()
addHelperFilter()
getAllHelperCallbacks()
applyTemplate()
__construct()
getTable()
setRequired()
isRequired()
setRow()
hasRow()
getRow()
setValue()
getValue()
getName()
setId()
getId()
setLabel()
getLabel()
setControlName()
getControlName()
setGroupName()
getGroupName()
setHtmlId()
getHtmlId()
getQueryStringId()
getInputFilter()
setInputFilterBuilder()
getInputFilterBuilder()
getOptionPairs()
getOptionGroups()
getOptionPairsReference()
getValidatorChain()
getFilterChain()
isType()
No public properties found
AUTHORIZATION_ALLOW_ALL
isTypeString()
isTypeBoolean()
isTypeNumeric()
isTypeInteger()
isTypeFloat()
isTypeReference()
isTypeManytomany()
$note
$fieldsSet
$visible
$sortable
$filterable
$editable
$customHelperCallbacks
$helperFilters
$optionPairs
$optionGroups
$table
$row
$required
$name
N/A
allowPermissionForRole()
forbidPermissionForRole()
checkPermissionForUser()
setPermission()
inflectLabel()
$label
$groupName
$metadata
$controlName
$htmlId
$inputFilter
$inputFilterBuilder
$id
N/A

Constants

AUTHORIZATION_ALLOW_ALL

AUTHORIZATION_ALLOW_ALL

A placeholder used to signify that a capability is available to everyone, even if no UserInterface object is supplied to test against.

Properties

$note

$note : string

Any notes that should be displayed along with this field when it is displayed to users.

Type

string

$fieldsSet

$fieldsSet : \Dewdrop\Fields

The Fields object this field is associated with. This is really only used to enable our streamlined method chaining.

Type

\Dewdrop\Fields

$visible

$visible : array

All field capabilities are enabled by default for DB (whereas all are disabled by default in custom fields).

Type

array

$sortable

$sortable : array

All field capabilities are enabled by default for DB (whereas all are disabled by default in custom fields).

Type

array

$filterable

$filterable : array

All field capabilities are enabled by default for DB (whereas all are disabled by default in custom fields).

Type

array

$editable

$editable : array

All field capabilities are enabled by default for DB (whereas all are disabled by default in custom fields).

Type

array

$customHelperCallbacks

$customHelperCallbacks : array

Any custom helper callbacks assigned to this field.

Type

array

$helperFilters

$helperFilters : array

Type

array

$optionPairs

$optionPairs : \Dewdrop\Fields\OptionPairs

A \Dewdrop\Fields\OptionPairs object for use in retrieving key-value pair options for a foreign key field.

Type

\Dewdrop\Fields\OptionPairs

$optionGroups

$optionGroups : \Dewdrop\Fields\OptionGroups

A \Dewdrop\Fields\OptionGroups object for use in retrieving key-value pair groups for a foreign key field.

Type

\Dewdrop\Fields\OptionGroups

$table

$table : \Dewdrop\Db\Table

The table this field is associated with.

Type

\Dewdrop\Db\Table

$row

$row : \Dewdrop\Db\Row

The row this field is associated with. There will not always be a row associated with the field. The getValue() and setValue() methods will not be functional unless a row is present.

Type

\Dewdrop\Db\Row

$required

$required : boolean

Whether this field is required or not

Type

boolean

$name

$name : string

The name of the column this field represents.

Type

string

$label

$label : string

How this field should be labeled when included in UI such as form fields or table headers.

Type

string

$groupName

$groupName : string

Typically, DB fields use IDs that are composed of the table name followed by a separator and then the field name. If you have a naming conflict, though, you can set an alternate group name for the field.

Type

string

$metadata

$metadata : array

The metadata related to this column. The metadata includes the following fields:

  • SCHEMA_NAME
  • TABLE_NAME
  • COLUMN_NAME
  • COLUMN_POSITION
  • DATA_TYPE
  • DEFAULT
  • NULLABLE
  • LENGTH
  • SCALE
  • PRECISION
  • UNSIGNED
  • PRIMARY
  • PRIMARY_POSITION
  • IDENTITY

Type

array

$controlName

$controlName : string

An identifier for this field when it is associated with input controls or other UI elements. This can be changed manually to disambiguate fields when multiple instances of a model and its fields are used on a single request.

By default, this property with have the value of:

table_name:column_name

Type

string

$htmlId

$htmlId : string

An identifier suitable for use in an HTML ID attribute.

Type

string

$inputFilter

$inputFilter : \Zend\InputFilter\Input

The \Zend\InputFilter\Input instance used to validate and filter this field.

Type

\Zend\InputFilter\Input

$inputFilterBuilder

$inputFilterBuilder : \Dewdrop\Db\Field\InputFilterBuilder

Object used to populate this field's input filter based upon its type.

Type

\Dewdrop\Db\Field\InputFilterBuilder

$id

$id : string

The ID for this field. Used when interacting with the \Dewdrop\Fields APIs.

Type

string

Methods

setNote()

setNote(string  $note) : \Dewdrop\Fields\FieldAbstract

Set a note that will be displayed alongside this field when it is used in a UI.

Parameters

string $note

Returns

\Dewdrop\Fields\FieldAbstract

getNote()

getNote() : string

Get the note associated with this field.

Returns

string

setOptions()

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

Set multiple options at once on this field using an array of option names and their values.

Parameters

array $options

Throws

\Dewdrop\Fields\Exception

Returns

\Dewdrop\Fields\FieldAbstract

resetFieldsSet()

resetFieldsSet() : \Dewdrop\Fields\FieldAbstract

Can be used to break the association between this field and the set it was originally added to so that it can be associated with a different set.

Returns

\Dewdrop\Fields\FieldAbstract

setFieldsSet()

setFieldsSet(\Dewdrop\Fields  $fieldsSet) : \Dewdrop\Fields\FieldAbstract

Set the FieldsSet that contains this FieldAbstract object. Note that once this is set, it cannot be changed without first calling resetFieldsSet().

This is done to ensure that when chaining calls between this field and its containing set, the same set is always used. This avoids inconsistent or unpredictable cases where the field is added to one set but later customized on a derivitive set.

Parameters

\Dewdrop\Fields $fieldsSet

Returns

\Dewdrop\Fields\FieldAbstract

add()

add(mixed  $field, string  $modelName = null) : mixed

When calling add() on this field, it will delegate the call back up to the associated \Dewdrop\Fields object. This allows for a very fluid method chaining style when defining a large set of fields.

Parameters

mixed $field
string $modelName

Throws

\Dewdrop\Fields\Exception

Returns

mixed

setVisible()

setVisible(mixed  $visible) : \Dewdrop\Fields\FieldAbstract

Set whether this field should be visible. Can supply either a boolean, in which case true means globally allowed and false means globally forbidden, or an array of roles/capabilities for which it is allowed.

Parameters

mixed $visible

Returns

\Dewdrop\Fields\FieldAbstract

getVisibleSetting()

getVisibleSetting() : array

Get the current setting for this field's visibility. Will return an empty array if completely forbidden, an array containing only \Dewdrop\Fields\FieldAbstract::AUTHORIZATION_ALLOW_ALL if completely allowed, or an array containing 1 or more roles if a custom setting is applied.

Returns

array

isVisible()

isVisible(\Dewdrop\Fields\UserInterface  $user = null) : boolean

Check to see if this field is visible. If no user is supplied, this method will only return true when the field is visible globally. Otherwise, it will check to see if the user has a matching role/capability.

Parameters

\Dewdrop\Fields\UserInterface $user

Returns

boolean

allowVisibilityForRole()

allowVisibilityForRole(mixed  $role) : \Dewdrop\Fields\FieldAbstract

Enable visibility for a specific role. You can call this multiple times to configure the field for all roles, or call setVisible() once with an array of roles.

Parameters

mixed $role

Returns

\Dewdrop\Fields\FieldAbstract

forbidVisibilityForRole()

forbidVisibilityForRole(mixed  $role) : \Dewdrop\Fields\FieldAbstract

Forbid visibility for a specific role.

Parameters

mixed $role

Returns

\Dewdrop\Fields\FieldAbstract

setSortable()

setSortable(mixed  $sortable) : \Dewdrop\Fields\FieldAbstract

Set whether this field should be sortable. Can supply either a boolean, in which case true means globally allowed and false means globally forbidden, or an array of roles/capabilities for which it is allowed.

Parameters

mixed $sortable

Returns

\Dewdrop\Fields\FieldAbstract

getSortableSetting()

getSortableSetting() : array

Get the current setting for this field's sortability. Will return an empty array if completely forbidden, an array containing only \Dewdrop\Fields\FieldAbstract::AUTHORIZATION_ALLOW_ALL if completely allowed, or an array containing 1 or more roles if a custom setting is applied.

Returns

array

isSortable()

isSortable(\Dewdrop\Fields\UserInterface  $user = null) : boolean

Check to see if this field is sortable. If no user is supplied, this method will only return true when the field is visible globally. Otherwise, it will check to see if the user has a matching role/capability.

Parameters

\Dewdrop\Fields\UserInterface $user

Returns

boolean

allowSortingForRole()

allowSortingForRole(mixed  $role) : \Dewdrop\Fields\FieldAbstract

Enable sorting for a specific role. You can call this multiple times to configure the field for all roles, or call setSortable() once with an array of roles.

Parameters

mixed $role

Returns

\Dewdrop\Fields\FieldAbstract

forbidSortingForRole()

forbidSortingForRole(mixed  $role) : \Dewdrop\Fields\FieldAbstract

Forbid sorting for a specific role.

Parameters

mixed $role

Returns

\Dewdrop\Fields\FieldAbstract

setFilterable()

setFilterable(mixed  $filterable) : \Dewdrop\Fields\FieldAbstract

Set whether this field should be filterable. Can supply either a boolean, in which case true means globally allowed and false means globally forbidden, or an array of roles/capabilities for which it is allowed.

Parameters

mixed $filterable

Returns

\Dewdrop\Fields\FieldAbstract

getFilterableSetting()

getFilterableSetting() : array

Get the current setting for this field's filterability. Will return an empty array if completely forbidden, an array containing only \Dewdrop\Fields\FieldAbstract::AUTHORIZATION_ALLOW_ALL if completely allowed, or an array containing 1 or more roles if a custom setting is applied.

Returns

array

isFilterable()

isFilterable(\Dewdrop\Fields\UserInterface  $user = null) : boolean

Check to see if this field is filterable. If no user is supplied, this method will only return true when the field is visible globally. Otherwise, it will check to see if the user has a matching role/capability.

Parameters

\Dewdrop\Fields\UserInterface $user

Returns

boolean

allowFilteringForRole()

allowFilteringForRole(mixed  $role) : \Dewdrop\Fields\FieldAbstract

Enable filtering for a specific role. You can call this multiple times to configure the field for all roles, or call setFilterable() once with an array of roles.

Parameters

mixed $role

Returns

\Dewdrop\Fields\FieldAbstract

forbidFilteringForRole()

forbidFilteringForRole(mixed  $role) : \Dewdrop\Fields\FieldAbstract

Forbid filtering for a specific role.

Parameters

mixed $role

Returns

\Dewdrop\Fields\FieldAbstract

setEditable()

setEditable(mixed  $editable) : \Dewdrop\Fields\FieldAbstract

Set whether this field should be editable. Can supply either a boolean, in which case true means globally allowed and false means globally forbidden, or an array of roles/capabilities for which it is allowed.

Parameters

mixed $editable

Returns

\Dewdrop\Fields\FieldAbstract

getEditableSetting()

getEditableSetting() : array

Get the current setting for this field's editability. Will return an empty array if completely forbidden, an array containing only \Dewdrop\Fields\FieldAbstract::AUTHORIZATION_ALLOW_ALL if completely allowed, or an array containing 1 or more roles if a custom setting is applied.

Returns

array

isEditable()

isEditable(\Dewdrop\Fields\UserInterface  $user = null) : boolean

Check to see if this field is editable. If no user is supplied, this method will only return true when the field is visible globally. Otherwise, it will check to see if the user has a matching role/capability.

Parameters

\Dewdrop\Fields\UserInterface $user

Returns

boolean

allowEditingForRole()

allowEditingForRole(mixed  $role) : \Dewdrop\Fields\FieldAbstract

Enable editing for a specific role. You can call this multiple times to configure the field for all roles, or call setEditable() once with an array of roles.

Parameters

mixed $role

Returns

\Dewdrop\Fields\FieldAbstract

forbidEditingForRole()

forbidEditingForRole(mixed  $role) : \Dewdrop\Fields\FieldAbstract

Forbid editing for a specific role.

Parameters

mixed $role

Returns

\Dewdrop\Fields\FieldAbstract

assignHelperCallback()

assignHelperCallback(string  $helperName, callable  $callable) : \Dewdrop\Fields\FieldAbstract

Assing a custom callback for use with the named field helper.

Parameters

string $helperName
callable $callable

Returns

\Dewdrop\Fields\FieldAbstract

hasHelperCallback()

hasHelperCallback(string  $helperName) : boolean

Check to see if this field has a custom callback defined for the supplied helper name.

Parameters

string $helperName

Returns

boolean

getHelperCallback()

getHelperCallback(string  $helperName) : callable

Get the callback assigned to this field for the supplied helper name.

Parameters

string $helperName

Returns

callable

removeHelperCallback()

removeHelperCallback(string  $helperName) : \Dewdrop\Fields\FieldAbstract

Remove the custom callback with the supplied helper name.

Parameters

string $helperName

Throws

\Dewdrop\Fields\Exception

Returns

\Dewdrop\Fields\FieldAbstract

getHelperFilters()

getHelperFilters(string  $helperName) : array

Get any filters supplied for the given helper name.

Parameters

string $helperName

Returns

array

addHelperFilter()

addHelperFilter(string  $helperName, callable  $filter) : $this

Parameters

string $helperName
callable $filter

Returns

$this

getAllHelperCallbacks()

getAllHelperCallbacks() : array

Get all helper callbacks that have been assigned to this field.

The returned array with have helper names as keys and the callables themselves as values. Mostly useful in debugging/introspection contexts.

Returns

array

applyTemplate()

applyTemplate(callable  $template) : $this

Apply a template to this field.

Parameters

callable $template

Returns

$this

__construct()

__construct(\Dewdrop\Db\Table  $table, string  $name, array  $metadata) 

Create new field with a reference to the table that instantiated it, the name of the DB column it represents and metadata from the DB about its type, constraints, etc.

Parameters

\Dewdrop\Db\Table $table
string $name
array $metadata

getTable()

getTable() : \Dewdrop\Db\Table

Get a reference to the table that generated this field object.

Returns

\Dewdrop\Db\Table

setRequired()

setRequired(boolean  $required) : \Dewdrop\Db\Field

Manually override the default setting regarding whether this field is required

Parameters

boolean $required

Returns

\Dewdrop\Db\Field

isRequired()

isRequired() : boolean

Check whether this field is required. If setRequired() has not been called, then we look to the DB metadata to determine whether the field is required. When the metadata says the column is not NULLABLE, then it is marked as being required.

Returns

boolean

setRow()

setRow(\Dewdrop\Db\Row  $row) : \Dewdrop\Db\Field

Associate a row with this field object so that it can be used to retrieve and/or set the value of the associated column in the row.

Parameters

\Dewdrop\Db\Row $row

Returns

\Dewdrop\Db\Field

hasRow()

hasRow() : boolean

Check to see if this field has an associated row.

Returns

boolean

getRow()

getRow() : \Dewdrop\Db\Row

Get the row associated with this field.

Returns

\Dewdrop\Db\Row

setValue()

setValue(mixed  $value) : \Dewdrop\Db\Field

Set the value of this field on the associated row, if available.

Parameters

mixed $value

Returns

\Dewdrop\Db\Field

getValue()

getValue() : mixed

Retrieve the value of this field for the associated row, if available.

Throws

\Dewdrop\Exception

Returns

mixed

getName()

getName() : string

Get the name of the DB column associated with this field.

Returns

string

setId()

setId(string  $id) : \Dewdrop\Db\Field

Set the ID of this field. If no ID is set on database fields, we'll fall back to getControlName().

Parameters

string $id

Returns

\Dewdrop\Db\Field

getId()

getId() : string

Get this field's ID. When no ID is set on a DB field, we fall back to getControlName().

Returns

string

setLabel()

setLabel(string  $label) : \Dewdrop\Db\Field

Manually specify a label for this field, overriding the default inflection-based naming.

Parameters

string $label

Returns

\Dewdrop\Db\Field

getLabel()

getLabel() : string

Get the label for this field, inflecting it from the DB column name if one hasn't be assigned explicitly.

Returns

string

setControlName()

setControlName(string  $controlName) : \Dewdrop\Db\Field

Manually override the default control name for this field.

This can be useful and necessary if you are using multiple instances of the same model and field on a single page and you need to disambiguate them.

Parameters

string $controlName

Returns

\Dewdrop\Db\Field

getControlName()

getControlName() : string

Get the control name, using the default of "table_name:column_name" if no control name has been set explicitly.

Returns

string

setGroupName()

setGroupName(string  $groupName) : \Dewdrop\Db\Field

Set an alternative group name for this field. Typically, DB fields are by their table name, but if you have fields from multiple instances of the same model on a single request, that might cause conflicts. In those cases, altnative group names can be used to resolve the naming conflict.

Parameters

string $groupName

Returns

\Dewdrop\Db\Field

getGroupName()

getGroupName() : string

Get the group name for this field, typically the table name, unless an alternative has been set.

Returns

string

setHtmlId()

setHtmlId(string  $htmlId) : $this

Override the default HTML ID for this field.

Parameters

string $htmlId

Returns

$this

getHtmlId()

getHtmlId() : string

Get a version of the control name using underscores as word separators to be more friendly in CSS selectors, etc.

Returns

string

getQueryStringId()

getQueryStringId() : string

Get a version of the control name using "+" for the model/field separator to be more friendly to query strings.

Returns

string

getInputFilter()

getInputFilter() : \Zend\InputFilter\Input

Get the \Zend\InputFilter\Filter object associated with this field. This object allows us to easily filter and validate values assigned to the field.

Returns

\Zend\InputFilter\Input

setInputFilterBuilder()

setInputFilterBuilder(\Dewdrop\Db\Field\InputFilterBuilder  $inputFilterBuilder) : $this

Provide an alternative input filter build, if you'd like to use different validators and filters for your field objects by default.

Parameters

\Dewdrop\Db\Field\InputFilterBuilder $inputFilterBuilder

Returns

$this

getInputFilterBuilder()

getInputFilterBuilder() : \Dewdrop\Db\Field\InputFilterBuilder

Get the InputFilterBuilder that can be used to create default validators and filters for the field.

Returns

\Dewdrop\Db\Field\InputFilterBuilder

getOptionPairs()

getOptionPairs() : \Dewdrop\Fields\OptionPairs

Get an OptionPairs object for this field. Allows you to easily fetch key-value option pairs for foreign keys.

Returns

\Dewdrop\Fields\OptionPairs

getOptionGroups()

getOptionGroups() : \Dewdrop\Fields\OptionGroups

Get an OptionGroups object for this field. Allows you to easily fetch key-value option pairs for foreign keys.

Returns

\Dewdrop\Fields\OptionGroups

getOptionPairsReference()

getOptionPairsReference() : array

Get the reference that can be used to retrieve option pairs. How we retrieve this will vary for one-to-many vs many-to-many contexts.

Returns

array

getValidatorChain()

getValidatorChain() : \Zend\Validator\ValidatorChain

Convenience method that lets you access the validator chain directly instead of first having to retrieve the input filter.

Returns

\Zend\Validator\ValidatorChain

getFilterChain()

getFilterChain() : \Zend\Filter\FilterChain

Convenience method that lets you access the filter chain directly instead of first having to retrieve the input filter.

Returns

\Zend\Filter\FilterChain

isType()

isType() : boolean

Check whether the field is of the specified type. One or more types can be provided as individual arguments to this method.

If the field matches any of the supplied types, this method will return true.

Returns

boolean

isTypeString()

isTypeString() : boolean

Convenience method for checking for common string types. You can call isType('string') to check that your field matches one of the common MySQL string types.

Returns

boolean

isTypeBoolean()

isTypeBoolean() : boolean

Convenience method to check if the field is a boolean. You can call isType('boolean') and isType() will in turn call this method to see if the field is a boolean.

Returns

boolean

isTypeNumeric()

isTypeNumeric() : boolean

Check to see if this field is numeric, either integer or float. Calling isType('numeric') will delegate to this method automatically.

Returns

boolean

isTypeInteger()

isTypeInteger() : boolean

Check to see if this field matches any of the common MySQL integer types.

Calling isType('integer') will automatically delegate to this method.

Returns

boolean

isTypeFloat()

isTypeFloat() : boolean

Check to see if this field matches any of the common MySQL float types.

Calling isType('float') will automatically delegate to this method.

Returns

boolean

isTypeReference()

isTypeReference() : boolean

Check to see if this field is a foreign key. Calling isType('reference') will automatically delegate to this method.

Returns

boolean

isTypeManytomany()

isTypeManytomany() : boolean

Check to see if this is a many-to-many field. Always false here, always true when Dewdrop\Db\ManyToMany\Field sub-classes.

Returns

boolean

allowPermissionForRole()

allowPermissionForRole(string  $permissionProperty, mixed  $role) : \Dewdrop\Fields\FieldAbstract

Allow the permission for the specified role.

Parameters

string $permissionProperty
mixed $role

Returns

\Dewdrop\Fields\FieldAbstract

forbidPermissionForRole()

forbidPermissionForRole(string  $permissionProperty, mixed  $role) : \Dewdrop\Fields\FieldAbstract

Forbid the permission for the specified role.

Parameters

string $permissionProperty
mixed $role

Returns

\Dewdrop\Fields\FieldAbstract

checkPermissionForUser()

checkPermissionForUser(string  $permissionProperty, \Dewdrop\Fields\UserInterface  $user = null) : boolean

Check to see if the UserInterface can use the specific capability.

We return true if the capability is available to everyone or if the user has a role allowed for that permission/capability.

Parameters

string $permissionProperty
\Dewdrop\Fields\UserInterface $user

Returns

boolean

setPermission()

setPermission(string  $permissionProperty, mixed  $value) : \Dewdrop\Fields\FieldAbstract

Set the permission. If true, it's allowed for everyone. If false, it's forbidden for everyone. Otherwise, we expect an array of roles for which the capability is allowed.

Parameters

string $permissionProperty
mixed $value

Throws

\Dewdrop\Fields\Exception

Returns

\Dewdrop\Fields\FieldAbstract

inflectLabel()

inflectLabel() : string

Generate a label for this field based up the underlying database column's name.

Returns

string