\DewdropFields

The Fields API is at the core of many of Dewdrop's abstractions. It has two primary goals:

1) Leverage metadata from the database (e.g. information about various constraints, data-types, etc.) to make working with database fields in various contexts simpler and less error-prone.

2) To allow the definition of non-DB-related fields as well, so that the Fields API can be used to inject customizable pieces of code into logic and rendering loops in a clean way.

Adding fields is possible in a few different ways. You can add a DB field directly from a \Dewdrop\Db\Table model:

$fields->add($model->field('my_field'));

You can add a custom field by passing an ID string to the add() method and then customizing the field:

$fields->add('my_custom_field_id')
    ->setLabel('Just a Custom Field')
    ->setVisible(true)
    ->assignHelperCallback(
        'TableCell.Content',
        function ($helper, array $rowData) {
            return 'Hello, world';
        }
    );

Or, you can instantiate and add the field object directly:

$field = new \Dewdrop\Fields\Field();

$field
    ->setId('my_custom_field_id')
    ->setLabel('Just a Custom Field')
    ->setVisible(true)
    ->assignHelperCallback(
        'TableCell.Content',
        function ($helper, array $rowData) {
            return 'Hello, world';
        }
    );

$fields->add($field);

Once added, you can get your fields back in a number of different ways:

1) The DOM-like get(), has(), and remove() methods all take a field ID.

2) The getAll(), getVisibleFields(), getSortableFields(), getFilterableFields() and getEditableFields() objects all will return new \Dewdrop\Fields objects that contain only the fields allowed by the method you called. When calling any of this methods, you can pass any number of \Dewdrop\Fields\Filter objects as well to further sort or limit the fields you get back.

3) You can iterate over the Fields object just like an array.

Many other objects in Dewdrop can receive a Fields collection and use it to make decisions. For example, notable view helpers such as Table can use a collection of fields to render their headers and cells.

Summary

Methods
Properties
Constants
__construct()
getIterator()
insertAfter()
count()
offsetSet()
offsetGet()
offsetExists()
offsetUnset()
setUser()
getUser()
has()
get()
getByQueryStringId()
add()
prepend()
append()
remove()
getAll()
getVisibleFields()
getSortableFields()
getEditableFields()
getFilterableFields()
getModelsByName()
No public properties found
No constants found
handleModelsForDbField()
getFieldsPassingMethodCheck()
applyFilters()
No protected properties found
N/A
prepareFieldForAdding()
$fields
$modelInstances
$modelsByName
$user
N/A

Properties

$fields

$fields : array

The fields currently contained in this collection.

Type

array

$modelInstances

$modelInstances : array

The model instances associated with added DB fields.

Type

array

$modelsByName

$modelsByName : array

The models associated with added DB fields by name (typically the table name, but could be different if a custom name is provided when calling add()).

Type

array

$user

$user : 

An object implementing the \Dewdrop\Fields\UserInterface interface, which can be used to take advantage of the authorization features in the \Dewdrop\Fields API.

Type

Methods

__construct()

__construct(array  $fields = null, \Dewdrop\Fields\UserInterface  $user = null) 

Optionally supply an array of fields that can be used as an initial set for this collection.

Parameters

array $fields
\Dewdrop\Fields\UserInterface $user

getIterator()

getIterator() : \Dewdrop\Fields\FieldsIterator

Iterate over this Fields set using a FieldsIterator. You typically don't call this directly, you just do a foreach over the Fields object.

Returns

\Dewdrop\Fields\FieldsIterator

insertAfter()

insertAfter(\Dewdrop\Fields\FieldInterface|string  $field, \Dewdrop\Fields\FieldInterface|string  $after, string  $modelName = null) : \Dewdrop\Fields\FieldInterface

Add the supplied field to this collection after another specified field already in the collection. Can be a FieldInterface object or a string, in which case a new custom field will be added with the supplied string as its ID.

The newly added FieldInterface object is returned from this method so that it can be further customized immediately, using method chaining. Once you've completed calling methods on the FieldInterface object itself, you can call any \Dewdrop\Fields methods to return execution to that context.

Parameters

\Dewdrop\Fields\FieldInterface|string $field
\Dewdrop\Fields\FieldInterface|string $after
string $modelName

Throws

\Dewdrop\Exception

Returns

\Dewdrop\Fields\FieldInterface

count()

count() : integer

Count the number of fields in this collection.

Returns

integer

offsetSet()

offsetSet(string  $offset, mixed  $value) : void

Allow addition/replacement of Field objects on this collection via array syntax:

$fields['id'] = $field;

This is part of the ArrayAccess interface built into PHP.

Parameters

string $offset
mixed $value

Throws

\Dewdrop\Exception

offsetGet()

offsetGet(string  $offset) : mixed

Get a field by its ID using ArrayAccess syntax.

echo $fields['id']->getLabel();

This method is part of the ArrayAccess interface built into PHP.

Parameters

string $offset

Returns

mixed

offsetExists()

offsetExists(string  $offset) : boolean

Test to see if the specified field ID exists in this Fields collection using isset():

isset($fields['id']);

This method is part of the ArrayAccess interface built into PHP.

Parameters

string $offset

Returns

boolean

offsetUnset()

offsetUnset(string  $offset) : void

Allow removal of a field via ArrayAccess syntax:

unset($fields['id']);

Parameters

string $offset

setUser()

setUser(\Dewdrop\Fields\UserInterface  $user) : \Dewdrop\Fields

Set the UserInterface object that can be used by the authorization-related features in \Dewdrop\Fields.

Parameters

\Dewdrop\Fields\UserInterface $user

Returns

\Dewdrop\Fields

has()

has(string  $id, integer  $position = null) : boolean

Check to see if a field with the given ID exists in this collection. If the identified field does exist, then the $position output parameter is populated with the position of the field in the collection, starting at 0.

Parameters

string $id
integer $position

Returns

boolean

get()

get(string  $id) : \Dewdrop\Fields\FieldInterface

Get the field matching the supplied ID from this collection.

Parameters

string $id

Returns

\Dewdrop\Fields\FieldInterface

getByQueryStringId()

getByQueryStringId(string  $id) : \Dewdrop\Fields\FieldInterface

Get the field matching the supplied query string ID from this collection.

Parameters

string $id

Returns

\Dewdrop\Fields\FieldInterface

add()

add(mixed  $field, string  $modelName = null) : \Dewdrop\Fields\FieldInterface

Add the supplied field to this collection. Can be a FieldInterface object or a string, in which case a new custom field will be added with the supplied string as its ID.

The newly added FieldInterface object is returned from this method so that it can be further customized immediately, using method chaining. Once you've completed calling methods on the FieldInterface object itself, you can call any \Dewdrop\Fields methods to return execution to that context.

Parameters

mixed $field
string $modelName

Throws

\Dewdrop\Exception

Returns

\Dewdrop\Fields\FieldInterface

prepend()

prepend(mixed  $field, string|null  $modelName = null) : \Dewdrop\Fields\FieldInterface

Prepend the supplied field (or custom field ID) to the field set.

Parameters

mixed $field
string|null $modelName

Returns

\Dewdrop\Fields\FieldInterface

append()

append(mixed  $field, string|null  $modelName = null) : \Dewdrop\Fields\FieldInterface

An alias to add(). Just here because it's odd to have prepend() and not append().

Parameters

mixed $field
string|null $modelName

Returns

\Dewdrop\Fields\FieldInterface

remove()

remove(string  $id) : \Dewdrop\Fields

Remove the field with the given ID from this collection.

Parameters

string $id

Returns

\Dewdrop\Fields

getAll()

getAll(mixed  $filters = null) : \Dewdrop\Fields

Get all the fields currently in this collection.

Parameters

mixed $filters

Returns

\Dewdrop\Fields

getVisibleFields()

getVisibleFields(mixed  $filters = null) : \Dewdrop\Fields

Get any fields that are visible and pass the supplied filters. Note that you can either pass a single \Dewdrop\Fields\Filter or an array of them.

Parameters

mixed $filters

Returns

\Dewdrop\Fields

getSortableFields()

getSortableFields(mixed  $filters = null) : \Dewdrop\Fields

Get any fields that are sortable and pass the supplied filters. Note that you can either pass a single \Dewdrop\Fields\Filter or an array of them.

Parameters

mixed $filters

Returns

\Dewdrop\Fields

getEditableFields()

getEditableFields(mixed  $filters = null) : \Dewdrop\Fields

Get any fields that are editable and pass the supplied filters. Note that you can either pass a single \Dewdrop\Fields\Filter or an array of them.

Parameters

mixed $filters

Returns

\Dewdrop\Fields

getFilterableFields()

getFilterableFields(mixed  $filters = null) : \Dewdrop\Fields

Get any fields that are filterable and pass the supplied filters. Note that you can either pass a single \Dewdrop\Fields\Filter or an array of them.

Parameters

mixed $filters

Returns

\Dewdrop\Fields

getModelsByName()

getModelsByName() : array

Get all the model instances associated with added DB fields, indexed by name.

Returns

array

handleModelsForDbField()

handleModelsForDbField(\Dewdrop\Db\Field  $field, string  $modelName) 

Handle the model (\Dewdrop\Db\Table) objects for the supplied newly added DB field. We allow custom model names for situations where you need to add fields from two different instances of the same model (e.g. you have an two Addresses model instances on your fields set because you have both a billing and a shipping address).

Parameters

\Dewdrop\Db\Field $field
string $modelName

Throws

\Dewdrop\Exception

getFieldsPassingMethodCheck()

getFieldsPassingMethodCheck(string  $fieldMethodName, mixed  $filters) : \Dewdrop\Fields

Get any fields that return true when the supplied method is called and pass the supplied filters. Note that you can either pass a single \Dewdrop\Fields\Filter or an array of them.

Parameters

string $fieldMethodName
mixed $filters

Returns

\Dewdrop\Fields

applyFilters()

applyFilters(\Dewdrop\Fields  $fields, mixed  $filters) : \Dewdrop\Fields

Apply the supplied filters to the Fields. You can pass no filters, a single filter, or an array of filters.

Parameters

\Dewdrop\Fields $fields
mixed $filters

Returns

\Dewdrop\Fields

prepareFieldForAdding()

prepareFieldForAdding(mixed  $field, string|null  $modelName = null) : \Dewdrop\Fields\FieldInterface

Prepare to add a field for the supplied arguments. If $field is a string we'll create a new CustomField. Otherwise, we'll just directly add the field object itself.

Parameters

mixed $field
string|null $modelName

Throws

\Dewdrop\Exception

Returns

\Dewdrop\Fields\FieldInterface