Editor PHP 2.3.2

Editor extends Ext
in package

Application

DataTables Editor base class for creating editable tables.

Editor class instances are capable of servicing all of the requests that DataTables and Editor will make from the client-side - specifically:

Get data
Create new record
Edit existing record
Delete existing records

The Editor instance is configured with information regarding the database table fields that you wish to make editable, and other information needed to read and write to the database (table name for example!).

This documentation is very much focused on describing the API presented by these DataTables Editor classes. For a more general overview of how the Editor class is used, and how to install Editor on your server, please refer to the Editor manual.

Constants

ACTION_CREATE = 'create': Request type - create
ACTION_DELETE = 'remove': Request type - delete
ACTION_EDIT = 'edit': Request type - edit
ACTION_READ = 'read': Request type - read
ACTION_UPLOAD = 'upload': Request type - upload

Properties

$version : string

Methods

__construct() : mixed: Constructor.
_ssp_field() : string: Convert a column index to a database field name - used for server-side processing requests.
action() : static::ACTION_*: Determine the request type from an HTTP request.
actionName() : mixed: Get / set the action name to read in HTTP parameters. This can be useful to set if you are using a framework that uses the default name of `action` for something else (e.g. WordPress).
data() : array<string|int, mixed>: Get the data constructed in this instance.
db() : mixed: Get / set the DB connection instance.
debug() : mixed: Get / set debug mode and set a debug message.
field() : mixed: Get / set field instance.
fields() : mixed: Get / set field instances.
idPrefix() : mixed: Get / set the DOM prefix.
inData() : array<string|int, mixed>: Get the data that is being processed by the Editor instance. This is only useful once the `process()` method has been called, and is available for use in validation and formatter methods.
inst() : static: Static method to instantiate a new instance of a class (shorthand of 'instantiate').
instantiate() : static: Static method to instantiate a new instance of a class.
join() : mixed: Get / set join instances. Note that for the majority of use cases you will want to use the `leftJoin()` method. It is significantly easier to use if you are just doing a simple left join!
json() : mixed: Get the JSON for the data constructed in this instance.
jsonp() : $this: Echo out JSONP for the data constructed and processed in this instance.
leftJoin() : $this: Add a left join condition to the Editor instance, allowing it to operate over multiple tables. Multiple `leftJoin()` calls can be made for a single Editor instance to join multiple tables.
leftJoinRemove() : mixed: Indicate if a remove should be performed on left joined tables when deleting from the parent row. Note that this is disabled by default and will be removed completely in v2. Use `ON DELETE CASCADE` in your database instead.
on() : $this: Add an event listener. The `Editor` class will trigger an number of events that some action can be taken on.
pkey() : mixed: Get / set the primary key.
pkeyToArray() : array<string|int, mixed>: Convert a primary key combined value to an array of field values.
pkeyToValue() : string: Convert a primary key array of field values to a combined value.
process() : $this: Process a request from the Editor client-side to get / set data.
readTable() : mixed: The CRUD read table name. If this method is used, Editor will create from the table name(s) given rather than those given by `Editor->table()`. This can be a useful distinction to allow a read from a VIEW (which could make use of a complex SELECT) while writing to a different table.
table() : mixed: Get / set the table name.
transaction() : mixed: Get / set transaction support.
tryCatch() : mixed: Enable / try catch when `process()` is called. Disabling this can be useful for debugging, but is not recommended for production.
validate() : bool: Perform validation on a data set.
validator() : mixed: Get / set a global validator that will be triggered for the create, edit and remove actions performed from the client-side. Multiple validators can be added.
where() : mixed: Where condition to add to the query used to get data from the database.
whereSet() : mixed: Get / set if the WHERE conditions should be included in the create and edit actions.
write() : mixed
_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).

ACTION_CREATE

Request type - create


    public
        mixed
    ACTION_CREATE
    = 'create'

ACTION_DELETE

Request type - delete


    public
        mixed
    ACTION_DELETE
    = 'remove'

ACTION_EDIT

Request type - edit


    public
        mixed
    ACTION_EDIT
    = 'edit'

ACTION_READ

Request type - read


    public
        mixed
    ACTION_READ
    = 'read'

ACTION_UPLOAD

Request type - upload


    public
        mixed
    ACTION_UPLOAD
    = 'upload'

$version


    public
        string
    $version
     = '2.3.2'

__construct()

Constructor.


    public
                    __construct([Database $db = null ][, string|array<string|int, mixed> $table = null ][, string|array<string|int, mixed> $pkey = null ]) : mixed

Parameters

$db : Database = null: An instance of the DataTables Database class that we can use for the DB connection. Can be given here or with the 'db' method.
$table : string|array<string|int, mixed> = null: The table name in the database to read and write information from and to. Can be given here or with the 'table' method.
$pkey : string|array<string|int, mixed> = null: Primary key column name in the table given in the $table parameter. Can be given here or with the 'pkey' method.

_ssp_field()

Convert a column index to a database field name - used for server-side processing requests.


    public
                    _ssp_field(array<string|int, mixed> $http, int $index) : string

Parameters

$http : array<string|int, mixed>: HTTP variables (i.e. GET or POST)
$index : int: Index in the DataTables' submitted data

Return values

string —

DB field name

action()

Determine the request type from an HTTP request.


    public
            static        action(array<string|int, mixed> $http[, string $name = 'action' ]) : static::ACTION_*

Parameters

$http : array<string|int, mixed>: Typically $_POST, but can be any array used to carry an Editor payload
$name : string = 'action': The parameter name that the action should be read from.

Return values

static::ACTION_* —

Editor::ACTION_READ, Editor::ACTION_CREATE, Editor::ACTION_EDIT or Editor::ACTION_DELETE indicating the request type.

actionName()

Get / set the action name to read in HTTP parameters. This can be useful to set if you are using a framework that uses the default name of `action` for something else (e.g. WordPress).


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

Parameters

$_ : string = null: Value to set. If not given, then used as a getter.

Return values

mixed —

Value.

data()

Get the data constructed in this instance.


    public
                    data() : array<string|int, mixed>

This will get the PHP array of data that has been constructed for the command that has been processed by this instance. Therefore only useful after process has been called.

Return values

array<string|int, mixed> —

Processed data array.

db()

Get / set the DB connection instance.


    public
                    db([Database $_ = null ]) : mixed

Parameters

$_ : Database = null: DataTable's Database class instance to use for database connectivity. If not given, then used as a getter.

Return values

mixed —

The Database connection instance if no parameter is given.

debug()

Get / set debug mode and set a debug message.


    public
                    debug([bool|mixed $_ = null ][, string $path = null ]) : mixed

It can be useful to see the SQL statements that Editor is using. This method enables that ability. Information about the queries used is automatically added to the output data array / JSON under the property name debugSql.

This method can also be called with a string parameter, which will be added to the debug information sent back to the client-side. This can be useful when debugging event listeners, etc.

Parameters

$_ : bool|mixed = null: Debug mode state. If not given, then used as a getter. If given as anything other than a boolean, it will be added to the debug information sent back to the client.
$path : string = null: Set an output path to log debug information

Return values

mixed —

Debug mode state if no parameter is given.

field()

Get / set field instance.


    public
                    field([Field|string $_ = null ]) : mixed

The list of fields designates which columns in the table that Editor will work with (both get and set).

Parameters

$_ : Field|string = null

This parameter effects the return value of the function:

null - Get an array of all fields assigned to the instance
string - Get a specific field instance whose 'name' matches the field passed in
Field - Add a field to the instance's list of fields. This can be as many fields as required (i.e. multiple arguments)
array - An array of Field instances to add to the list of fields.

Return values

mixed —

The selected field, an array of fields, depending on the input parameter.

fields()

Get / set field instances.


    public
                    fields([Field|array<string|int, Field> $_ = null ]) : mixed

An alias of field, for convenience.

Parameters

$_ : Field|array<string|int, Field> = null: Instances of the Field class, given as a single instance of Field, an array of Field instances, or multiple Field instance parameters for the function.

Return values

mixed —

Array of fields.

idPrefix()

Get / set the DOM prefix.


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

Typically primary keys are numeric and this is not a valid ID value in an HTML document - is also increases the likelihood of an ID clash if multiple tables are used on a single page. As such, a prefix is assigned to the primary key value for each row, and this is used as the DOM ID, so Editor can track individual rows.

Parameters

$_ : string = null: Primary key's name. If not given, then used as a getter.

Return values

mixed —

Primary key value if no parameter is given.

inData()

Get the data that is being processed by the Editor instance. This is only useful once the `process()` method has been called, and is available for use in validation and formatter methods.


    public
                    inData() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Data given to process().

inst()

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


    public
            static        inst() : static

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

Return values

static —

class

instantiate()

Static method to instantiate a new instance of a class.


    public
            static        instantiate() : static

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

static —

Instantiated class

join()

Get / set join instances. Note that for the majority of use cases you will want to use the `leftJoin()` method. It is significantly easier to use if you are just doing a simple left join!


    public
                    join([Join $_ = null ]) : mixed

The list of Join instances that Editor will join the parent table to (i.e. the one that the Editor->table() and Editor->fields methods refer to in this class instance).

Parameters

$_ : Join = null: Instances of the Join class, given as a single instance of Join, an array of Join instances, or multiple Join instance parameters for the function.

Return values

mixed —

Array of joins.

json()

Get the JSON for the data constructed in this instance.


    public
                    json([bool $print = true ][, int $options = 0 ]) : mixed

Basically the same as the Editor->data() method, but in this case we echo, or return the JSON string of the data.

Parameters

$print : bool = true: Echo the JSON string out (true, default) or return it (false).
$options : int = 0: JSON encode option https://www.php.net/manual/en/json.constants.php

Return values

mixed —

JSON representation of the processed data if false is given as the first parameter.

jsonp()

Echo out JSONP for the data constructed and processed in this instance.


    public
                    jsonp([string $callback = null ]) : $this

This is basically the same as Editor->json() but wraps the return in a JSONP callback.

Parameters

$callback : string = null: The callback function name to use. If not given or null, then $_GET['callback'] is used (the jQuery default).

Return values

$this

leftJoin()

Add a left join condition to the Editor instance, allowing it to operate over multiple tables. Multiple `leftJoin()` calls can be made for a single Editor instance to join multiple tables.


    public
                    leftJoin(string $table, string $field1[, string $operator = null ][, string $field2 = null ]) : $this

A left join is the most common type of join that is used with Editor so this method is provided to make its use very easy to configure. Its parameters are basically the same as writing an SQL left join statement, but in this case Editor will handle the create, update and remove requirements of the join for you:

Create - On create Editor will insert the data into the primary table and then into the joined tables - selecting the required data for each table.
Edit - On edit Editor will update the main table, and then either update the existing rows in the joined table that match the join and edit conditions, or insert a new row into the joined table if required.
Remove - On delete Editor will remove the main row and then loop over each of the joined tables and remove the joined data matching the join link from the main table.

Please note that when using join tables, Editor requires that you fully qualify each field with the field's table name. SQL can result table names for ambiguous field names, but for Editor to provide its full CRUD options, the table name must also be given. For example the field first_name in the table users would be given as users.first_name.

Parameters

$table : string: Table name to do a join onto
$field1 : string: Field from the parent table to use as the join link
$operator : string = null: Join condition (=, '<`, etc)
$field2 : string = null: Field from the child table to use as the join link

Return values

$this

leftJoinRemove()

Indicate if a remove should be performed on left joined tables when deleting from the parent row. Note that this is disabled by default and will be removed completely in v2. Use `ON DELETE CASCADE` in your database instead.


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

Parameters

$_ : bool = null: Value to set. If not given, then used as a getter.

Return values

mixed —

Value if no parameter is given.

on()

Add an event listener. The `Editor` class will trigger an number of events that some action can be taken on.


    public
                    on(string $name, mixed $callback) : $this

Parameters

$name : string: Event name
$callback : mixed

Return values

$this

pkey()

Get / set the primary key.


    public
                    pkey([string|array<string|int, string> $_ = null ]) : mixed

The primary key must be known to Editor so it will know which rows are being edited / deleted upon those actions. The default value is ['id'].

Parameters

$_ : string|array<string|int, string> = null: Primary key's name. If not given, then used as a getter. An array of column names can be given to allow composite keys to be used.

Return values

mixed —

Primary key value if no parameter is given.

pkeyToArray()

Convert a primary key combined value to an array of field values.


    public
                    pkeyToArray(string $value[, bool $flat = false ][, array<string|int, string> $pkey = null ]) : array<string|int, mixed>

Parameters

$value : string: The id that should be split apart
$flat : bool = false: Flag to indicate if the returned array should be flat (useful for where conditions) or nested for join tables.
$pkey : array<string|int, string> = null: The primary key name - will use the instance value if not given

Return values

array<string|int, mixed> —

Array of field values that the id was made up of.

pkeyToValue()

Convert a primary key array of field values to a combined value.


    public
                    pkeyToValue(array<string|int, mixed> $row[, bool $flat = false ]) : string

Parameters

$row : array<string|int, mixed>: The row of data that the primary key value should be extracted from.
$flat : bool = false: Flag to indicate if the given array is flat (useful for where conditions) or nested for join tables.

Return values

string —

The created primary key value.

process()

Process a request from the Editor client-side to get / set data.


    public
                    process(array<string|int, mixed> $data) : $this

Parameters

$data : array<string|int, mixed>: Typically $_POST or $_GET as required by what is sent by Editor

Return values

$this

readTable()

The CRUD read table name. If this method is used, Editor will create from the table name(s) given rather than those given by `Editor->table()`. This can be a useful distinction to allow a read from a VIEW (which could make use of a complex SELECT) while writing to a different table.


    public
                    readTable([string|array<string|int, mixed> $_ = null ]) : mixed

Parameters

$_ : string|array<string|int, mixed> = null: Read table names given as a single string, an array of strings or multiple string parameters for the function.

Return values

mixed —

Array of read tables names.

table()

Get / set the table name.


    public
                    table([string|array<string|int, mixed> $_ = null ]) : mixed

The table name designated which DB table Editor will use as its data source for working with the database. Table names can be given with an alias, which can be used to simplify larger table names. The field names would also need to reflect the alias, just like an SQL query. For example: users as a.

Parameters

$_ : string|array<string|int, mixed> = null: Table names given as a single string, an array of strings or multiple string parameters for the function.

Return values

mixed —

Array of tables names.

transaction()

Get / set transaction support.


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

When enabled (which it is by default) Editor will use an SQL transaction to ensure data integrity while it is performing operations on the table. This can be optionally disabled using this method, if required by your database configuration.

Parameters

$_ : bool = null: Enable (true) or disabled (false) transactions. If not given, then used as a getter.

Return values

mixed —

Transactions enabled flag.

tryCatch()

Enable / try catch when `process()` is called. Disabling this can be useful for debugging, but is not recommended for production.


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

Parameters

$_ : bool = null: true to enable (default), otherwise false to disable

Return values

mixed —

Value if used as a getter.

validate()

Perform validation on a data set.


    public
                    validate(array<string|int, mixed> &$errors, array<string|int, mixed> $data) : bool

Note that validation is performed on data only when the action is create or edit. Additionally, validation is performed on the wire data - i.e. that which is submitted from the client, without formatting. Any formatting required by setFormatter is performed after the data from the client has been validated.

Parameters

$errors : array<string|int, mixed>: Output array to which field error information will be written. Each element in the array represents a field in an error condition. These elements are themselves arrays with two properties set; name and status.
$data : array<string|int, mixed>: The format data to check

Return values

bool —

true if the data is valid, false if not.

validator()

Get / set a global validator that will be triggered for the create, edit and remove actions performed from the client-side. Multiple validators can be added.


    public
                    validator([mixed $_ = null ]) : mixed

Parameters

$_ : mixed = null

Return values

mixed —

The validator function.

where()

Where condition to add to the query used to get data from the database.


    public
                    where([mixed $key = null ][, string $value = null ][, string $op = '=' ]) : mixed

Can be used in two different ways:

Simple case: where( field, value, operator )
Complex: where( fn )

The simple case is fairly self explanatory, a condition is applied to the data that looks like field operator value (e.g. name = 'Allan'). The complex case allows full control over the query conditions by providing a closure function that has access to the database Query that Editor is using, so you can use the where(), or_where(), and_where() and where_group() methods as you require.

Please be very careful when using this method! If an edit made by a user using Editor removes the row from the where condition, the result is undefined (since Editor expects the row to still be available, but the condition removes it from the result set).

Parameters

$key : mixed = null
$value : string = null: Single field value.
$op : string = '=': Condition operator: <, >, = etc

Return values

mixed —

Where condition array.

whereSet()

Get / set if the WHERE conditions should be included in the create and edit actions.


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

Parameters

$_ : bool = null: Include (true), or not (false)

Return values

mixed —

Current value

write()


    public
                    write([bool $_writeVal = null ]) : mixed

Parameters

$_writeVal : bool = null

_getSet()

Common getter / setter function for DataTables classes.


    protected
                    _getSet(mixed &$prop, mixed $val[, bool $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
$val : mixed: The value to set - if given as null, then we assume that the function is being used as a getter.
$array : bool = false: 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.

_propExists()

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

Return values

bool —

true if present, false otherwise

_readProp()

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

Return values

mixed —

The read value, or null if no value found.

_writeProp()

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

Editor extends Ext in package Application

Tags

Table of Contents

Constants

Properties

Methods

Constants

ACTION_CREATE

ACTION_DELETE

ACTION_EDIT

ACTION_READ

ACTION_UPLOAD

Properties

$version

Methods

__construct()

Parameters

_ssp_field()

Parameters

Tags

Return values

action()

Parameters

Return values

actionName()

Parameters

Return values

data()

Return values

db()

Parameters

Return values

debug()

Parameters

Return values

field()

Parameters

Tags

Return values

fields()

Parameters

Tags

Return values

idPrefix()

Parameters

Return values

inData()

Return values

inst()

Return values

instantiate()

Return values

join()

Parameters

Return values

json()

Parameters

Return values

jsonp()

Parameters

Return values

leftJoin()

Parameters

Tags

Return values

leftJoinRemove()

Parameters

Tags

Return values

on()

Parameters

Return values

pkey()

Parameters

Return values

pkeyToArray()

Parameters

Return values

pkeyToValue()

Parameters

Editor extends Ext
in package

Application