Menu

## Field extends Ext
in package

Field.php : 65

Field definitions for the DataTables Editor.

Each Database column that is used with Editor can be described with this Field method (both for Editor and Join instances). It basically tells Editor what table column to use, how to format the data and if you want to read and/or write this column.

Field instances are used with the Editor->field() and Join->field() methods to describe what fields should be interacted with by the editable table.

##### Tags

example

  Simply get a column with the name "city". No validation is performed.

        Field::inst( 'city' )

  @example Get a column with the name "first_name" - when edited a value must be given due to the "required" validation from the Validate class.

        Field::inst( 'first_name' )->validator( 'Validate::required' )

  @example Working with a date field, which is validated, and also has get and set formatters.

        Field::inst( 'registered_date' )
            ->validator( 'Validate::dateFormat', 'D, d M y' )
            ->getFormatter( 'Format::date_sql_to_format', 'D, d M y' )
            ->setFormatter( 'Format::date_format_to_sql', 'D, d M y' )

  @example Using an alias in the first parameter

        Field::inst( 'name.first as first_name' )

### Table of Contents

SET_BOTH = 'both'
  Set option flag (`set()`) - write to database on both create and edit
SET_CREATE = 'create'
  Set option flag (`set()`) - write to database only on create
SET_EDIT = 'edit'
  Set option flag (`set()`) - write to database only on edit
SET_NONE = 'none'
  Set option flag (`set()`) - do not set data
__construct() : mixed
  Field instance constructor.
apply() : mixed
  Check to see if a field should be used for a particular action (get or set).
dbField() : mixed
  Get / set the DB field name.
get() : mixed
  Get / set the 'get' property of the field.
getFormatter() : mixed
  Get formatter for the field's data.
getValue() : callable|string|self
  Get / set a get value. If given, then this value is used to send to the client-side, regardless of what value is held by the database.
inst() : Editor|Field|Join|Upload
  Static method to instantiate a new instance of a class (shorthand of 'instantiate').
instantiate() : Editor|Field|Join|Upload
  Static method to instantiate a new instance of a class.
name() : mixed
  Get / set the 'name' property of the field.
options() : Field
  Get a list of values that can be used for the options list in radio, select and checkbox inputs from the database for this field.
searchBuilderOptions() : self
  Get a list of values that can be used for the options list in SearchBuilder
searchPaneOptions() : self
  Get a list of values that can be used for the options list in SearchPanes
set() : mixed
  Get / set the 'set' property of the field.
setFormatter() : mixed
  Set formatter for the field's data.
setValue() : callable|string|self
  Get / set a set value. If given, then this value is used to write to the database regardless of what data is sent from the client-side.
upload() : Upload|self
  Get / set the upload class for this field.
val() : mixed
  Get the value of the field, taking into account if it is coming from the DB or from a POST. If formatting has been specified for this field, it will be applied here.
validator() : mixed
  Get / set the 'validator' of the field.
xss() : Field
  Set a formatting method that will be used for XSS checking / removal.
xssSafety() : string
  Perform XSS prevention on an input.
_getSet() : mixed
  Common getter / setter function for DataTables classes.
_propExists() : bool
  Determine if a property is available in a data set (allowing `null` to be a valid value)
_readProp() : mixed
  Read a value from a data structure, using Javascript dotted object notation. This is the inverse of the `_writeProp` method and provides the same support, matching DataTables' ability to read nested JSON data objects.
_writeProp() : mixed
  Write the field's value to an array structure, using Javascript dotted object notation to indicate JSON data structure. For example `name.first` gives the data structure: `name: { first: ... }`. This matches DataTables own ability to do this on the client-side, although this doesn't implement implement quite such a complex structure (no array / function support).

### Constants

#### SET_BOTH

Field.php : 74

Set option flag (`set()`) - write to database on both create and edit

`public mixed SET_BOTH = 'both'`

#### SET_CREATE

Field.php : 77

Set option flag (`set()`) - write to database only on create

`public mixed SET_CREATE = 'create'`

#### SET_EDIT

Field.php : 80

Set option flag (`set()`) - write to database only on edit

`public mixed SET_EDIT = 'edit'`

#### SET_NONE

Field.php : 71

Set option flag (`set()`) - do not set data

`public mixed SET_NONE = 'none'`

### Methods

#### __construct()

Field.php : 94

Field instance constructor.

`public __construct([mixed $dbField = null ][, string $name = null ]) : mixed`

@param string $dbField Name of the database column

##### Parameters

$dbField : mixed = null
$name : string = null

  Name to use in the JSON output from Editor and the HTTP submit from the client-side when editing. If not given then the $dbField name is used.

##### Return values

mixed —

#### apply()

Field.php : 587

Check to see if a field should be used for a particular action (get or set).

`public apply(string $action[, mixed $data = null ]) : mixed`

Called by the Editor / Join class instances - not expected for general consumption - internal.

##### Parameters

$action : string

  Direction that the data is travelling - 'get' is reading DB data, `create` and `edit` for writing to the DB @param array $data Data submitted from the client-side when setting. @return boolean true if the field should be used in the get / set. @internal

$data : mixed = null

##### Return values

mixed —

#### dbField()

Field.php : 199

Get / set the DB field name.

`public dbField([string $_ = null ]) : mixed`

Note that when used as a setter, an alias can be given for the field using the SQL `as` keyword - for example: `firstName as name`. In this situation the dbField is set to the field name before the `as`, and the field's name (`name()`) is set to the name after the `as`.

As a result of this, the following constructs have identical functionality:

Field::inst( 'firstName as name' ); Field::inst( 'firstName', 'name' );

##### Parameters

$_ : string = null

  Value to set if using as a setter. @return string|self The name of the db field if no parameter is given, or self if used as a setter.

##### Return values

mixed —

#### get()

Field.php : 228

Get / set the 'get' property of the field.

`public get([bool $_ = null ]) : mixed`

A field can be marked as write only when setting the get property to false here.

##### Parameters

$_ : bool = null

  Value to set if using as a setter. @return boolean|self The get property if no parameter is given, or self if used as a setter.

##### Return values

mixed —

#### getFormatter()

Field.php : 254

Get formatter for the field's data.

`public getFormatter([callable|string $_ = null ][, mixed $opts = null ]) : mixed`

When the data has been retrieved from the server, it can be passed through a formatter here, which will manipulate (format) the data as required. This can be useful when, for example, working with dates and a particular format is required on the client-side.

Editor has a number of formatters available with the Format class which can be used directly with this method.

##### Parameters

$_ : callable|string = null

  Value to set if using as a setter. Can be given as a closure function or a string with a reference to a function that will be called with call_user_func(). @param mixed $opts Variable that is passed through to the get formatting function - can be useful for passing through extra information such as date formatting string, or a required flag. The actual options available depend upon the formatter used. @return callable|string|self The get formatter if no parameter is given, or self if used as a setter.

$opts : mixed = null

##### Return values

mixed —

#### getValue()

Field.php : 272

Get / set a get value. If given, then this value is used to send to the client-side, regardless of what value is held by the database.

`public getValue([callable|string|number $_ = null ]) : callable|string|self`

##### Parameters

$_ : callable|string|number = null

  Value to set, or no value to use as a getter

##### Return values

callable|string|self —

Value if used as a getter, or self if used as a setter.

#### inst()

Ext.php : 51

Static method to instantiate a new instance of a class (shorthand of 'instantiate').

`public static inst() : Editor|Field|Join|Upload`

This method performs exactly the same actions as the 'instantiate' static method, but is simply shorter and easier to type!

##### Return values

Editor|Field|Join|Upload —

class @static

#### instantiate()

Ext.php : 32

Static method to instantiate a new instance of a class.

`public static instantiate() : Editor|Field|Join|Upload`

A factory method that will create a new instance of the class that has extended 'Ext'. This allows classes to be instantiated and then chained - which otherwise isn't available until PHP 5.4. If using PHP 5.4 or later, simply create a 'new' instance of the target class and chain methods as normal.

##### Return values

Editor|Field|Join|Upload —

Instantiated class @static

#### name()

Field.php : 289

Get / set the 'name' property of the field.

`public name([string $_ = null ]) : mixed`

The name is typically the same as the dbField name, since it makes things less confusing(!), but it is possible to set a different name for the data which is used in the JSON returned to DataTables in a 'get' operation and the field name used in a 'set' operation.

##### Parameters

$_ : string = null

  Value to set if using as a setter. @return string|self The name property if no parameter is given, or self if used as a setter.

##### Return values

mixed —

#### options()

Field.php : 315

Get a list of values that can be used for the options list in radio, select and checkbox inputs from the database for this field.

`public options([string|callable $table = null ][, string $value = null ][, string $label = null ][, callable $condition = null ][, callable $format = null ][, string $order = null ]) : Field`

Note that this is for simple 'label / value' pairs only. For more complex data, including pairs that require joins and where conditions, use a closure to provide a query

##### Parameters

$table : string|callable = null

  Database table name to use to get the paired data from, or a closure function if providing a method

$value : string = null

  Table column name that contains the pair's value. Not used if the first parameter is given as a closure

$label : string = null

  Table column name that contains the pair's label. Not used if the first parameter is given as a closure

$condition : callable = null

  Function that will add `where` conditions to the query

$format : callable = null

  Function will render each label

$order : string = null

  SQL ordering

##### Return values

Field —

Self for chaining

#### searchBuilderOptions()

Field.php : 388

Get a list of values that can be used for the options list in SearchBuilder

`public searchBuilderOptions([SearchBuilderOptions|callable $sbInput = null ]) : self`

##### Parameters

$sbInput : SearchBuilderOptions|callable = null

  SearchBuilderOptions instance or a closure function if providing a method

##### Return values

self —

#### searchPaneOptions()

Field.php : 361

Get a list of values that can be used for the options list in SearchPanes

`public searchPaneOptions([SearchPaneOptions|callable $spInput = null ]) : self`

##### Parameters

$spInput : SearchPaneOptions|callable = null

  SearchPaneOptions instance or a closure function if providing a method

##### Return values

self —

#### set()

Field.php : 431

Get / set the 'set' property of the field.

`public set([string|bool $_ = null ]) : mixed`

A field can be marked as read only using this option, to be set only during an create or edit action or to be set during both actions. This provides the ability to have fields that are only set when a new row is created (for example a "created" time stamp).

##### Parameters

$_ : string|bool = null

  Value to set when the method is being used as a setter (leave as undefined to use as a getter). This can take the value of:

  - `true` - Same as `Field::SET_BOTH`
  - `false` - Same as `Field::SET_NONE`
  - `Field::SET_BOTH` - Set the database value on both create and edit commands
  - `Field::SET_NONE` - Never set the database value
  - `Field::SET_CREATE` - Set the database value only on create
  - `Field::SET_EDIT` - Set the database value only on edit @return string|self The set property if no parameter is given, or self if used as a setter.

##### Return values

mixed —

#### setFormatter()

Field.php : 464

Set formatter for the field's data.

`public setFormatter([callable|string $_ = null ][, mixed $opts = null ]) : mixed`

When the data has been retrieved from the server, it can be passed through a formatter here, which will manipulate (format) the data as required. This can be useful when, for example, working with dates and a particular format is required on the client-side.

Editor has a number of formatters available with the Format class which can be used directly with this method.

##### Parameters

$_ : callable|string = null

  Value to set if using as a setter. Can be given as a closure function or a string with a reference to a function that will be called with call_user_func(). @param mixed $opts Variable that is passed through to the get formatting function - can be useful for passing through extra information such as date formatting string, or a required flag. The actual options available depend upon the formatter used. @return callable|string|self The set formatter if no parameter is given, or self if used as a setter.

$opts : mixed = null

##### Return values

mixed —

#### setValue()

Field.php : 482

Get / set a set value. If given, then this value is used to write to the database regardless of what data is sent from the client-side.

`public setValue([callable|string|number $_ = null ]) : callable|string|self`

##### Parameters

$_ : callable|string|number = null

  Value to set, or no value to use as a getter

##### Return values

callable|string|self —

Value if used as a getter, or self if used as a setter.

#### upload()

Field.php : 494

Get / set the upload class for this field.

`public upload([Upload $_ = null ]) : Upload|self`

##### Parameters

$_ : Upload = null

  Upload class if used as a setter

##### Return values

Upload|self —

Value if used as a getter, or self if used as a setter.

#### val()

Field.php : 708

Get the value of the field, taking into account if it is coming from the DB or from a POST. If formatting has been specified for this field, it will be applied here.

`public val(string $direction, mixed $data) : mixed`

Called by the Editor / Join class instances - not expected for general consumption - internal.

##### Parameters

$direction : string

  Direction that the data is travelling - 'get' is reading data, and 'set' is writing it to the DB. @param array $data Data submitted from the client-side when setting or the data for the row when getting data from the DB. @return string Value for the field @internal

$data : mixed

##### Return values

mixed —

#### validator()

Field.php : 522

Get / set the 'validator' of the field.

`public validator([callable|string $_ = null ][, mixed $opts = null ]) : mixed`

The validator can be used to check if any abstract piece of data is valid or not according to the given rules of the validation function used.

Multiple validation options can be applied to a field instance by calling this method multiple times. For example, it would be possible to have a 'required' validation and a 'maxLength' validation with multiple calls.

Editor has a number of validation available with the Validate class which can be used directly with this method.

##### Parameters

$_ : callable|string = null

  Value to set if using as the validation method. Can be given as a closure function or a string with a reference to a function that will be called with call_user_func(). @param mixed $opts Variable that is passed through to the validation function - can be useful for passing through extra information such as date formatting string, or a required flag. The actual options available depend upon the validation function used. @return callable|string|self The validation method if no parameter is given, or self if used as a setter.

$opts : mixed = null

##### Return values

mixed —

#### xss()

Field.php : 557

Set a formatting method that will be used for XSS checking / removal.

`public xss(callable|false $xssFormatter) : Field`

This should be a function that takes a single argument (the value to be cleaned) and returns the cleaned value.

Editor will use HtmLawed by default for this operation, which is built into the software and no additional configuration is required, but a custom function can be used if you wish to use a different formatter such as HTMLPurifier.

If you wish to disable this option (which you would only do if you are absolutely confident that your validation will pick up on any XSS inputs) simply provide a closure function that returns the value given to the function. This is not recommended.

##### Parameters

$xssFormatter : callable|false

  XSS cleaner function, use `false` or `null` to disable XSS cleaning.

##### Return values

Field —

Self for chaining.

#### xssSafety()

Field.php : 845

Perform XSS prevention on an input.

`public xssSafety(mixed $val) : string`

##### Parameters

$val : mixed

  Value to be escaped

##### Return values

string —

Safe value

#### _getSet()

Ext.php : 75

Common getter / setter function for DataTables classes.

`protected _getSet(mixed &$prop, mixed $val[, mixed $array = false ]) : mixed`

This getter / setter method makes building getter / setting methods easier, by abstracting everything to a single function call.

##### Parameters

$prop : mixed

  The property to set @param mixed $val The value to set - if given as null, then we assume that the function is being used as a getter. @param boolean $array Treat the target property as an array or not (default false). If used as an array, then values passed in are added to the $prop array. @return self|mixed Class instance if setting (allowing chaining), or the value requested if getting.

$val : mixed
$array : mixed = false

##### Return values

mixed —

#### _propExists()

Ext.php : 105

Determine if a property is available in a data set (allowing `null` to be a valid value)

`protected _propExists(string $name, array<string|int, mixed> $data) : bool`

##### Parameters

$name : string

  Javascript dotted object name to write to

$data : array<string|int, mixed>

  Data source array to read from

##### Tags

private

##### Return values

bool —

true if present, false otherwise

#### _readProp()

Ext.php : 142

Read a value from a data structure, using Javascript dotted object notation. This is the inverse of the `_writeProp` method and provides the same support, matching DataTables' ability to read nested JSON data objects.

`protected _readProp(string $name, array<string|int, mixed> $data) : mixed`

##### Parameters

$name : string

  Javascript dotted object name to write to

$data : array<string|int, mixed>

  Data source array to read from

##### Tags

private

##### Return values

mixed —

The read value, or null if no value found.

#### _writeProp()

Ext.php : 186

Write the field's value to an array structure, using Javascript dotted object notation to indicate JSON data structure. For example `name.first` gives the data structure: `name: { first: ... }`. This matches DataTables own ability to do this on the client-side, although this doesn't implement implement quite such a complex structure (no array / function support).

`protected _writeProp(array<string|int, mixed> &$out, string $name, mixed $value) : mixed`

##### Parameters

$out : array<string|int, mixed>

  Array to write the data to

$name : string

  Javascript dotted object name to write to

$value : mixed

  Value to write

##### Tags

throws
  Exception

  Information about duplicate properties

private

##### Return values

mixed —

## Search results