CRUDKit api-doc [Developer]

TableDescriptor
in package

Definition of a database table.

Examples for usage are provided in the documentation for CrudkitServiceProvider. Important: all methods marked with "@stackable" (like the constructor and all set methods) can be used like this

$page = new TableDesriptor(...)
		->addColumn(...)
		->setSoftDeleteColumn(...)
		->...

...easy

Tags
see
CrudkitServiceProvider

Table of Contents

$columns  : array<string|int, SQLColumn>
__construct()  : mixed
Constructor
addColumn()  : mixed
Adds a sql column to this table.
createRecord()  : array<string|int, mixed>
Creates a record in the DB
defineCustomColumnAjax()  : TableDescriptor
Defines a column where you can handle what is displayed, and what the user can enter via ajax select search. Be carefull - you have to take care of the data!
defineManyToOneColumn()  : TableDescriptor
Example: book.author_id is a many to one column. Related table.field is author.id Example code: see CrudkitServiceProvider doc
defineManyToOneColumnAjax()  : TableDescriptor
See defineManyToOneColumn() - same, but rendered as an ajax selectbox (search for values).
deleteRecord()  : mixed
fetchAllColumns()  : mixed
This method fetches $allColumns via Doctrine\DBAL (get extended information about columns)
getAllColumns()  : array<string|int, string>|array<string|int, mixed>
Returns an array of this tables columns, including extended information from Doctrine DBAL.
getColumns()  : array<string|int, string>|array<string|int, SQLColumn>
Returns an array of this tables columns
getCustomAjaxValues()  : mixed
getEmptyRecord()  : array<string|int, mixed>
Creates an empty records from this table for the create-update View.
getHasAutoincrementKey()  : bool
getManyToOneColumnValues()  : array<string|int, mixed>
Returns values for each many-to-one column of this table (values from related tables)
getName()  : string
getPrimaryKeyColumns()  : array<string|int, string>|array<string|int, SQLColumn>
Returns an array of this tables primary key columns
getSoftDeleteColumn()  : string
getSoftDeletedValue()  : mixed
getSoftNotDeletedValue()  : mixed
hasColumn()  : bool
Checks if a column with a specific name exists in this table.
postProcess()  : array<string|int, mixed>
Shortcut for `(new DataProcessor($table))->postProcess(...);`
readRecordRaw()  : array<string|int, mixed>
Reads a record from the DB.
readRecordsRaw()  : array<string|int, mixed>
Reads multiple records from the DB.
setColumnPosition()  : mixed
Sets the position of a column (display order)
setOrderBy()  : mixed
setSoftDeleteColumn()  : mixed
Defines a column as an indicator if the record is deleted or not.
updateRecord()  : array<string|int, mixed>
Updates a record in DB
allColumnsFromCache()  : bool
Tries fetch all columns from cache. Returns TRUE, if they were cached, FALSE if not.
allColumnsToCache()  : mixed
getDbSpecificBlobLengthFunction()  : string
Gets the DB specific functions for the size of a blob field (lentgh).
getDbSpecificColumnNameWithDelimiter()  : string
Gets the SQL column name sourrounded with the DB specififc field delimiter. (defined in crudkit-db.config)
getDbSpecificLikeCondition()  : string
Gets the DB specific like condition for a given expression (search term)

Properties

Methods

__construct()

Constructor

public __construct(string $name, array<string|int, string> $primaryKeyColumns[, bool $hasAutoincrementKey = false ]) : mixed
Parameters
$name : string

Name of the table (as defined in the database)

$primaryKeyColumns : array<string|int, string>

String array of column names, which define the primary key of this table, or at least identify a single record. Remember: if no column is a PK, every column is a PK!

$hasAutoincrementKey : bool = false

(default = false) Set this to TRUE if you have a column like and integer ID, which will be generated (MySQL Auto increment, MSSQL identity)

Return values
mixed —

addColumn()

Adds a sql column to this table.

public addColumn(string $name, string $label, string $type[, array<string|int, mixed> $options = [] ]) : mixed

You dont need to add every column that exists in the table, only those you need.

Parameters
$name : string

The name of the column like its defined in the Database

$label : string

The label to display the column on UI.

$type : string

The datatype - for details see SQLColumn Class doc

$options : array<string|int, mixed> = []

(optional) - for details see SQLColumn Class doc

Tags
see
SQLColumn
Return values
mixed —

createRecord()

Creates a record in the DB

public createRecord(array<string|int, mixed> $recordData) : array<string|int, mixed>
Parameters
$recordData : array<string|int, mixed>

(preprocessed)

Tags
internal
Return values
array<string|int, mixed> —

The primary key values

defineCustomColumnAjax()

Defines a column where you can handle what is displayed, and what the user can enter via ajax select search. Be carefull - you have to take care of the data!

public defineCustomColumnAjax(string $name, callable $onLoadCallback, callable $onSearchCallback[, AjaxOptions $ajaxOptions = null ]) : TableDescriptor 
//Example for $result object if success (Json encoded):
{type : "result", data : {results : [{'id' : '23', 'text' => 'Joe Smith', 'img' => 'base64imageData'}, {id : '...'}]}}
//Example for $result object if error (Json encoded):
{type : "error", message : "404 not found" data : "some error data which will be logged by the Javascript console..."}
//Helper methods in CHelper class:
CHelper::getAjaxErrorResult();
CHelper::getAjaxResult();
Parameters
$name : string

Name of the existing column. Cannot be a many to one column.

$onLoadCallback : callable

Callback function for preparing the data which is displayed in the field. Params are: &$value, &$text, $record, $table, $page, $column. You can change &$value and &$text as you wish. $value already holds the fields current value (after select). $text is an additionl info text

$onSearchCallback : callable

Callback function for when the user begins to type for searching data. Params are: &$results, $input, $table, $page, $column. You have to populate $results (see example above);

$ajaxOptions : AjaxOptions = null
Tags
stackable
Return values
TableDescriptor —

defineManyToOneColumn()

Example: book.author_id is a many to one column. Related table.field is author.id Example code: see CrudkitServiceProvider doc

public defineManyToOneColumn(string $name, string $toTableName, string $columnName[, array<string|int, mixed> $secondaryColumnNames = [] ][, string $page = '' ][, array<string|int, mixed> $filterDefinitions = [] ][, bool $manualInput = false ]) : TableDescriptor
Parameters
$name : string

Name of the column to defines as many to one

$toTableName : string

Related table name

$columnName : string

A column from the related table

$secondaryColumnNames : array<string|int, mixed> = []

Secondary clolumn names from the related table. These are shown to the user when selecting the value (more = slower)

$page : string = ''

A drilldown page if you want to display this relation as a link

$filterDefinitions : array<string|int, mixed> = []

Additional filters to limit the relation

$manualInput : bool = false

Allows the user to input custom data manually (without checking)

Tags
stackable
Return values
TableDescriptor —

defineManyToOneColumnAjax()

See defineManyToOneColumn() - same, but rendered as an ajax selectbox (search for values).

public defineManyToOneColumnAjax(string $name, string $toTableName, string $columnName[, array<string|int, mixed> $secondaryColumnNames = [] ][, string $page = '' ][, array<string|int, mixed> $filterDefinitions = [] ][, bool $manualInput = false ][, AjaxOptions|null $ajaxOptions = null ]) : TableDescriptor
Parameters
$name : string

Name of the column to defines as many to one

$toTableName : string

Related table name

$columnName : string

A column from the related table

$secondaryColumnNames : array<string|int, mixed> = []

Secondary clolumn names from the related table. These are shown to the user when selecting the value (more = slower)

$page : string = ''

A drilldown page if you want to display this relation as a link

$filterDefinitions : array<string|int, mixed> = []

Additional filters to limit the relation

$manualInput : bool = false

Allows the user to input custom data manually (without checking)

$ajaxOptions : AjaxOptions|null = null

additional options to control the ajax behavior

Tags
stackable
Return values
TableDescriptor —

deleteRecord()

public deleteRecord(array<string|int, mixed> $primaryKeyValues) : mixed
Parameters
$primaryKeyValues : array<string|int, mixed>
Return values
mixed —

fetchAllColumns()

This method fetches $allColumns via Doctrine\DBAL (get extended information about columns)

public fetchAllColumns([bool $force = false ]) : mixed

This is a compute intensive workload - so it should only be used by CRUDKit internally, and only when needed. The result from Doctrine\DBAL is also stored in the cache to increase performance.

Parameters
$force : bool = false
Tags
internal
Return values
mixed —

getAllColumns()

Returns an array of this tables columns, including extended information from Doctrine DBAL.

public getAllColumns([bool $namesOnly = false ]) : array<string|int, string>|array<string|int, mixed>

Make sure to call fetchAllColumns() at least once before calling this method.

Parameters
$namesOnly : bool = false

(default = FALSE) TRUE = retruns string[] array with the column names, FALSE = return and array of SQLColumn[] objects

Return values
array<string|int, string>|array<string|int, mixed> —

getColumns()

Returns an array of this tables columns

public getColumns([bool $namesOnly = false ]) : array<string|int, string>|array<string|int, SQLColumn>
Parameters
$namesOnly : bool = false

(default = FALSE) TRUE = retruns string[] array with the column names, FALSE = return and array of SQLColumn[] objects

Return values
array<string|int, string>|array<string|int, SQLColumn> —

getEmptyRecord()

Creates an empty records from this table for the create-update View.

public getEmptyRecord([bool $setDbDefaultValues = true ]) : array<string|int, mixed>
Parameters
$setDbDefaultValues : bool = true

Set the default values which are definded in the Database

Return values
array<string|int, mixed> —

getHasAutoincrementKey()

public getHasAutoincrementKey() : bool
Return values
bool —

getManyToOneColumnValues()

Returns values for each many-to-one column of this table (values from related tables)

public getManyToOneColumnValues([mixed $record = [] ][, bool $onlyCurrentValue = false ]) : array<string|int, mixed> 
['column-name-1' => ['value-1', 'value-2'], 'column-name-2' => [...]]
Parameters
$record : mixed = []
$onlyCurrentValue : bool = false
Return values
array<string|int, mixed> —

getName()

public getName() : string
Return values
string —

Name of the table (as defined in the database)

getPrimaryKeyColumns()

Returns an array of this tables primary key columns

public getPrimaryKeyColumns([bool $namesOnly = false ]) : array<string|int, string>|array<string|int, SQLColumn>
Parameters
$namesOnly : bool = false

(default = FALSE) TRUE = retruns string[] array with the column names, FALSE = return and array of SQLColumn[] objects

Return values
array<string|int, string>|array<string|int, SQLColumn> —

getSoftDeleteColumn()

public getSoftDeleteColumn() : string
Return values
string —

Name of the soft delte column (soft delete is a pseudo delete)

getSoftDeletedValue()

public getSoftDeletedValue() : mixed
Return values
mixed —

Value of the soft delete Column that indicates that the record IS deleted

getSoftNotDeletedValue()

public getSoftNotDeletedValue() : mixed
Return values
mixed —

Value of the soft delete Column that indicates that the record is NOT deleted.

hasColumn()

Checks if a column with a specific name exists in this table.

public hasColumn(string $columnName) : bool
Parameters
$columnName : string

The name of the column to check

Return values
bool —

postProcess()

Shortcut for `(new DataProcessor($table))->postProcess(...);`

public postProcess(mixed $records[, bool $singleRecord = false ][, bool $formaDateAndTime = true ][, mixed $formatBool = true ][, mixed $formatDec = true ][, mixed $formatBinary = true ]) : array<string|int, mixed>
Parameters
$records : mixed
$singleRecord : bool = false
$formaDateAndTime : bool = true
$formatBool : mixed = true
$formatDec : mixed = true
$formatBinary : mixed = true
Tags
see
DataProcessor
Return values
array<string|int, mixed> —

readRecordRaw()

Reads a record from the DB.

public readRecordRaw(array<string|int, string> $primaryKeyValues[, array<string|int, Filter> $filters = [] ][, mixed $throwErrorIfNotFound = true ]) : array<string|int, mixed>
Parameters
$primaryKeyValues : array<string|int, string>
$filters : array<string|int, Filter> = []
$throwErrorIfNotFound : mixed = true
Return values
array<string|int, mixed> —

Raw unprocessed record as an assoc array: ['column1' => value, 'column2' => value, ...]

readRecordsRaw()

Reads multiple records from the DB.

public readRecordsRaw([int $pageNumber = 1 ][, string $searchColumnName = '' ][, string $searchText = '' ][, array<string|int, Filter> $filters = [] ][, bool $trimText = true ][, int $itemsPerPage = -1 ]) : array<string|int, mixed>
Parameters
$pageNumber : int = 1

Pagination offset

$searchColumnName : string = ''

The column name to apply the $searchText (if existing)

$searchText : string = ''

The search text (if existing)

$filters : array<string|int, Filter> = []
$trimText : bool = true

Trim text >50 chars

$itemsPerPage : int = -1
Return values
array<string|int, mixed> —

Raw unprocessed records as an array: [0 => ['column1' => value, 'column2' => value, ...], 1 => [], 2 => [], ...]

setColumnPosition()

Sets the position of a column (display order)

public setColumnPosition( $columnName,  $where,  $referenceColumnName) : mixed 
$table->setColumnPosition('name', 'after', 'id'); //easy
Parameters
$columnName :

Defines the column to be set to a specific position.

$where :

Is either 'before' or 'after'

$referenceColumnName :

Before or after this Column the $columnName will be placed

Return values
mixed —

setOrderBy()

public setOrderBy(string $columnName[, string $direction = 'asc' ]) : mixed
Parameters
$columnName : string
$direction : string = 'asc'
Return values
mixed —

setSoftDeleteColumn()

Defines a column as an indicator if the record is deleted or not.

public setSoftDeleteColumn(string $name[, mixed $deleted = true ][, mixed $notDeleted = false ]) : mixed

Important: the soft delete column must not be added as normal column to the table, cause this will make things hard (espcially for users) When a soft delete column is defined, and a user deletes a record on the webpage, the record wont be deleted. Only thing happen is that the value of the soft delete column will be changed, and crudkit wont display this record anymore. - Cool, isnt it?

Parameters
$name : string

The name of the column

$deleted : mixed = true

(default = FALSE) The value of this column that indicates the record is NOT delteted

$notDeleted : mixed = false
Return values
mixed —

updateRecord()

Updates a record in DB

public updateRecord(array<string|int, mixed> $primaryKeyValues, array<string|int, mixed> $columnValues) : array<string|int, mixed>
Parameters
$primaryKeyValues : array<string|int, mixed>

(preprocessed)

$columnValues : array<string|int, mixed>

(preprocessed)

Tags
internal
Return values
array<string|int, mixed> —

The (maybe) new primary key values

allColumnsFromCache()

Tries fetch all columns from cache. Returns TRUE, if they were cached, FALSE if not.

private allColumnsFromCache() : bool
Tags
internal
Return values
bool —

allColumnsToCache()

private allColumnsToCache() : mixed
Tags
internal
Return values
mixed —

getDbSpecificBlobLengthFunction()

Gets the DB specific functions for the size of a blob field (lentgh).

private getDbSpecificBlobLengthFunction(string $columnNameWithDelimiter) : string
Parameters
$columnNameWithDelimiter : string

The name of the SQL column (already sorrounded by delimiters)

Tags
internal
Return values
string —

getDbSpecificColumnNameWithDelimiter()

Gets the SQL column name sourrounded with the DB specififc field delimiter. (defined in crudkit-db.config)

private getDbSpecificColumnNameWithDelimiter(string $columnName) : string
Parameters
$columnName : string

The name of the SQL column

Tags
internal
Return values
string —

getDbSpecificLikeCondition()

Gets the DB specific like condition for a given expression (search term)

private getDbSpecificLikeCondition(string $type, string $expression) : string
Parameters
$type : string

Either "contains"|"startswith"|"endswith"

$expression : string

The "search term"

Tags
internal
Return values
string —

Search results