\Dewdrop\FieldsFieldAbstract

This class serves as a base for both custom and DB fields in Dewdrop.

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()
No public properties found
AUTHORIZATION_ALLOW_ALL
No protected methods found
$note
$fieldsSet
$visible
$sortable
$filterable
$editable
$customHelperCallbacks
$helperFilters
N/A
allowPermissionForRole()
forbidPermissionForRole()
checkPermissionForUser()
setPermission()
No private properties found
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

The setting for this field's visibility. See the top-level docblock for this class for info on how this is stored.

Type

array

$sortable

$sortable : array

The setting for this field's sortability. See the top-level docblock for this class for info on how this is stored.

Type

array

$filterable

$filterable : array

The setting for this field's filterability. See the top-level docblock for this class for info on how this is stored.

Type

array

$editable

$editable : array

The setting for this field's editability. See the top-level docblock for this class for info on how this is stored.

Type

array

$customHelperCallbacks

$customHelperCallbacks : array

Any custom helper callbacks assigned to this field.

Type

array

$helperFilters

$helperFilters : array

Type

array

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

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