KMP PHP API Reference

GridViewConfig
in package

Configuration validator and normalizer for grid views.

Provides validation, normalization, and utility methods for grid view configs. Supports both flat filters (legacy AND conditions) and nested expression trees (OR/AND combinations).

Tags
see

/docs/9.3-dataverse-grid-complete-guide.md For grid configuration options

Table of Contents

Constants

DEFAULT_PAGE_SIZE  = 25
Default page size
MAX_PAGE_SIZE  = 100
Maximum page size
MIN_PAGE_SIZE  = 10
Minimum page size
VALID_DIRECTIONS  = ['asc', 'desc']
Valid sort directions
VALID_OPERATORS  = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'contains', 'startsWith', 'endsWith', 'in', 'notIn', 'isNull', 'isNotNull', 'dateRange']
Valid filter operators

Methods

createDefault()  : array<string, mixed>
Create a default config from column metadata
extractColumnConfiguration()  : array<string, array{visible: bool, order: int}>
Extract all columns from config with their order and visibility
extractExpression()  : QueryExpression|null
Extract nested OR/AND expression tree from config
extractFilters()  : array<string, mixed>
Extract ORM-compatible filter conditions from config
extractPageSize()  : int
Extract page size from config
extractSort()  : array<string, string>
Extract sort order from config
extractVisibleColumns()  : array<string|int, string>
Extract visible columns from config in display order
normalize()  : array<string, mixed>
Normalize a config array to ensure consistent structure
validate()  : array<string|int, string>
Validate a config array
buildExpression()  : QueryExpression
Recursively build QueryExpression from expression tree
buildLeafCondition()  : array<string, mixed>
Build CakePHP condition array from a leaf condition
isValidFilter()  : bool
Check if a filter definition is valid
isValidSort()  : bool
Check if a sort definition is valid

Constants

DEFAULT_PAGE_SIZE

Default page size

public mixed DEFAULT_PAGE_SIZE = 25

MAX_PAGE_SIZE

Maximum page size

public mixed MAX_PAGE_SIZE = 100

VALID_DIRECTIONS

Valid sort directions

public mixed VALID_DIRECTIONS = ['asc', 'desc']

VALID_OPERATORS

Valid filter operators

public mixed VALID_OPERATORS = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'contains', 'startsWith', 'endsWith', 'in', 'notIn', 'isNull', 'isNotNull', 'dateRange']

Methods

createDefault()

Create a default config from column metadata

public static createDefault(array<string, array<string, mixed>> $columnMetadata) : array<string, mixed>
Parameters
$columnMetadata : array<string, array<string, mixed>>

Column definitions

Return values
array<string, mixed> —

Default config

extractColumnConfiguration()

Extract all columns from config with their order and visibility

public static extractColumnConfiguration(array<string, mixed> $config) : array<string, array{visible: bool, order: int}>
Parameters
$config : array<string, mixed>

Grid view config

Return values
array<string, array{visible: bool, order: int}> —

Column configuration map

extractExpression()

Extract nested OR/AND expression tree from config

public static extractExpression(array<string, mixed> $config, QueryExpression $queryExpression[, string $tableName = '' ][, array<string|int, string> $skipColumns = [] ][, array<string, array<string, mixed>> $columnsMetadata = [] ]) : QueryExpression|null

Builds a CakePHP QueryExpression from a nested expression tree. Supports:

  • Simple field conditions: {"field": "status", "operator": "eq", "value": "active"}
  • OR groups: {"type": "OR", "conditions": [...]}
  • AND groups: {"type": "AND", "conditions": [...]}
  • Nested combinations: Mix OR/AND at any depth

Expression format:

{
  "type": "OR|AND",
  "conditions": [
    {"field": "status", "operator": "eq", "value": "active"},
    {
      "type": "AND",
      "conditions": [...]
    }
  ]
}
Parameters
$config : array<string, mixed>

Grid view config

$queryExpression : QueryExpression

Base expression object from query

$tableName : string = ''

Table name for field qualification (e.g., 'Warrants')

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

Column keys to skip (for custom-filtered columns)

$columnsMetadata : array<string, array<string, mixed>> = []

Column metadata for queryField lookups

Return values
QueryExpression|null —

Built expression tree or null if no expression

extractFilters()

Extract ORM-compatible filter conditions from config

public static extractFilters(array<string, mixed> $config) : array<string, mixed>
Parameters
$config : array<string, mixed>

Grid view config

Return values
array<string, mixed> —

ORM conditions

extractPageSize()

Extract page size from config

public static extractPageSize(array<string, mixed> $config) : int
Parameters
$config : array<string, mixed>

Grid view config

Return values
int —

Page size

extractSort()

Extract sort order from config

public static extractSort(array<string, mixed> $config) : array<string, string>
Parameters
$config : array<string, mixed>

Grid view config

Return values
array<string, string> —

Sort order for ORM

extractVisibleColumns()

Extract visible columns from config in display order

public static extractVisibleColumns(array<string, mixed> $config[, array<string, array<string, mixed>> $availableColumns = [] ]) : array<string|int, string>
Parameters
$config : array<string, mixed>

Grid view config

$availableColumns : array<string, array<string, mixed>> = []

Available column metadata

Return values
array<string|int, string> —

Array of visible column keys in order

normalize()

Normalize a config array to ensure consistent structure

public static normalize(array<string, mixed> $config[, array<string, array<string, mixed>> $availableColumns = [] ]) : array<string, mixed>
Parameters
$config : array<string, mixed>

Raw config array

$availableColumns : array<string, array<string, mixed>> = []

Available column metadata

Return values
array<string, mixed> —

Normalized config

validate()

Validate a config array

public static validate(array<string, mixed> $config[, array<string, array<string, mixed>> $availableColumns = [] ]) : array<string|int, string>
Parameters
$config : array<string, mixed>

Config to validate

$availableColumns : array<string, array<string, mixed>> = []

Available column metadata

Return values
array<string|int, string> —

Array of error messages (empty if valid)

buildExpression()

Recursively build QueryExpression from expression tree

protected static buildExpression(array<string, mixed> $expression, QueryExpression $queryExpression, string $tableName[, array<string|int, string> $skipColumns = [] ][, array<string, array<string, mixed>> $columnsMetadata = [] ]) : QueryExpression
Parameters
$expression : array<string, mixed>

Expression node (group or condition)

$queryExpression : QueryExpression

Base expression from query

$tableName : string

Table name for field qualification

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

Column keys to skip (for custom-filtered columns)

$columnsMetadata : array<string, array<string, mixed>> = []

Column metadata for queryField lookups

Return values
QueryExpression —

Built expression

buildLeafCondition()

Build CakePHP condition array from a leaf condition

protected static buildLeafCondition(array<string, mixed> $condition, string $tableName[, array<string|int, string> $skipColumns = [] ][, array<string, array<string, mixed>> $columnsMetadata = [] ]) : array<string, mixed>

Converts expression condition format to CakePHP ORM condition format:

  • {"field": "status", "operator": "eq", "value": "active"}
  • Becomes: ["Table.status" => "active"]

Uses queryField from column metadata when available to correctly qualify fields that map to different table columns (e.g., branch_type -> AwardBranch.type).

Parameters
$condition : array<string, mixed>

Condition definition

$tableName : string

Table name for field qualification

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

Column keys to skip (for custom-filtered columns)

$columnsMetadata : array<string, array<string, mixed>> = []

Column metadata for queryField lookups

Return values
array<string, mixed> —

CakePHP condition array

isValidFilter()

Check if a filter definition is valid

protected static isValidFilter(mixed $filter, array<string, array<string, mixed>> $availableColumns) : bool
Parameters
$filter : mixed

Filter definition

$availableColumns : array<string, array<string, mixed>>

Available columns

Return values
bool

isValidSort()

Check if a sort definition is valid

protected static isValidSort(mixed $sort, array<string, array<string, mixed>> $availableColumns) : bool
Parameters
$sort : mixed

Sort definition

$availableColumns : array<string, array<string, mixed>>

Available columns

Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results