Documentation

Api4SelectQuery extends Api4Query
in package

Application

Constructs SELECT FROM queries for API4 GET actions.

Constants

MAIN_TABLE_ALIAS = 'a'
UNLIMITED = '18446744073709551615'

Properties

$apiFieldSpec : array<string|int, array<string|int, mixed>>
$forceSelectId : bool
$selectAliases : array<string|int, mixed>
$aclFields : array<string|int, mixed>
$api : AbstractQueryAction
$autoJoinSuffix : int: Used to create a unique table alias for each implicit join
$entityValues : array<string|int, mixed>
$joinTree : array<string|int, mixed>: Used to keep track of implicit join table aliases
$query : CRM_Utils_SQL_Select
$entityAccess : array<string|int, mixed>
$explicitJoins : array<string|int, array{entity: string, alias: string, table: string, on: array, bridge: string|null}>
$openJoin : array<string|int, mixed>: Explicit join currently being processed

Methods

__construct() : mixed
addSpecField() : mixed
checkEntityAccess() : bool: Check the "gatekeeper" permissions for performing "get" on a given entity.
composeClause() : string: Validate and transform a leaf clause array to SQL.
debug() : mixed: Add something to the api's debug output if debugging is enabled
getAclClause() : array<string|int, mixed>: Get acl clause for an entity
getApiParam() : mixed
getCheckPermissions() : bool|string
getCount() : int
getEntity() : string
getExplicitJoin() : array{entity: string, alias: string, table: string, on: array, bridge: string|null}|null
getExplicitJoins() : array<string|int, array{entity: string, alias: string, table: string, on: array, bridge: string|null}>
getField() : array<string|int, mixed>|bool|null: Fetch a field from the getFields list
getFieldSibling() : mixed
getFrom() : false|string
getGroupBy() : array<string|int, mixed>
getHaving() : array<string|int, mixed>
getJoin() : array<string|int, mixed>
getJoinParent() : string|null: If a join is based on another join, return the name of the other.
getLimit() : mixed
getOffset() : mixed
getOrderBy() : array<string|int, mixed>
getQuery() : CRM_Utils_SQL_Select
getResults() : array<string|int, mixed>
getSelect() : array<string|int, mixed>
getSql() : string: Builds main final sql statement after initialization.
getWhere() : array<string|int, mixed>
renderSerializedJoin() : string: Performs a virtual join with a serialized field using FIND_IN_SET
run() : array<string|int, mixed>: Why walk when you can
treeWalkClauses() : string: Recursively validate and transform a branch or leaf clause array to SQL.
addBridgeJoin() : mixed: Join via a Bridge table using a join within a join
autoJoinFK() : mixed: Joins a path and adds all fields in the joined entity to apiFieldSpec
buildGroupBy() : mixed: Add GROUP BY clause to query
buildHavingClause() : mixed: Add HAVING clause to query
buildLimit() : mixed: Add LIMIT to query
buildOrderBy() : mixed: Add ORDER BY to query
buildSelectClause() : mixed
buildWhereClause() : mixed: Add WHERE clause to query
createSQLClause() : array<string|int, mixed>|string|null
getExpression() : SqlExpression
isAggregateQuery() : mixed
renderExpr() : mixed|string: Returns rendered expression or alias if it is already aliased in the SELECT clause.
addExplicitJoins() : mixed: Join onto other entities as specified by the api call.
addJoin() : void
fillEntityValues() : mixed: This takes all the where clauses that use `=` to build an array of known values which every record must have.
finishJoin() : void
getBridgeJoinConditions() : array<string|int, string>: Extract bridge join conditions from the joinTree if any, else supply default conditions for join to base entity
getBridgeLinkConditions() : array<string|int, mixed>: Get the clause to link bridge entity with join entity
getBridgeRefs() : array<string|int, mixed>: Get the table name and 2 reference columns from a bridge entity
getJoinConditions() : array<string|int, mixed>: Supply conditions for an explicit join.
registerBridgeJoinFields() : void: Register fields (other than bridge FK fields) from the bridge entity as if they belong to the join entity
selectMatchingFields() : array<string|int, mixed>: Get all fields for SELECT clause matching a wildcard pattern
startNewJoin() : void: Begins a new join; as long as it's "open" then additional joins will nest inside it.

MAIN_TABLE_ALIAS


    public
        mixed
    MAIN_TABLE_ALIAS
    = 'a'

UNLIMITED


    public
        mixed
    UNLIMITED
    = '18446744073709551615'

$apiFieldSpec


    public
        array<string|int, array<string|int, mixed>>
    $apiFieldSpec
     = []

$forceSelectId


    public
        bool
    $forceSelectId
     = TRUE

$selectAliases


    public
        array<string|int, mixed>
    $selectAliases
     = []

[alias => expr][]

$aclFields


    protected
        array<string|int, mixed>
    $aclFields
     = []

$api


    protected
        AbstractQueryAction
    $api

$autoJoinSuffix

Used to create a unique table alias for each implicit join


    protected
        int
    $autoJoinSuffix
     = 0

$entityValues


    protected
        array<string|int, mixed>
    $entityValues
     = []

$joinTree

Used to keep track of implicit join table aliases


    protected
        array<string|int, mixed>
    $joinTree
     = []

$query


    protected
        CRM_Utils_SQL_Select
    $query

$entityAccess


    private
        array<string|int, mixed>
    $entityAccess
     = []

$explicitJoins


    private
        array<string|int, array{entity: string, alias: string, table: string, on: array, bridge: string|null}>
    $explicitJoins
     = []

$openJoin

Explicit join currently being processed


    private
        array<string|int, mixed>
    $openJoin

__construct()


    public
                    __construct(DAOGetAction $api) : mixed

Parameters

$api : DAOGetAction

addSpecField()


    public
                    addSpecField(string $path, array<string|int, mixed> $field) : mixed

Parameters

$path : string
$field : array<string|int, mixed>

checkEntityAccess()

Check the "gatekeeper" permissions for performing "get" on a given entity.


    public
                    checkEntityAccess(mixed $entity) : bool

Parameters

$entity : mixed

Return values

bool

composeClause()

Validate and transform a leaf clause array to SQL.


    public
                    composeClause(array<string|int, mixed> $clause, string $type, int $depth) : string

Parameters

$clause : array<string|int, mixed>: [$fieldName, $operator, $criteria, $isExpression]
$type : string: WHERE|HAVING|ON
$depth : int

Return values

string —

SQL

debug()

Add something to the api's debug output if debugging is enabled


    public
                    debug(mixed $key, mixed $item) : mixed

Parameters

$key : mixed
$item : mixed

getAclClause()

Get acl clause for an entity


    public
                    getAclClause(string $tableAlias, string $entityName[, array<string|int, mixed> $stack = [] ][, array<string|int, array<string|int, mixed>> $conditions = [] ]) : array<string|int, mixed>

Parameters

$tableAlias : string
$entityName : string
$stack : array<string|int, mixed> = []
$conditions : array<string|int, array<string|int, mixed>> = []

Return values

array<string|int, mixed>

getApiParam()


    public
                    getApiParam(mixed $param) : mixed

Parameters

$param : mixed

getCheckPermissions()


    public
                    getCheckPermissions() : bool|string

Return values

bool|string

getCount()


    public
                    getCount() : int

Return values

int

getEntity()


    public
                    getEntity() : string

Return values

string

getExplicitJoin()


    public
                    getExplicitJoin(string $alias) : array{entity: string, alias: string, table: string, on: array, bridge: string|null}|null

Parameters

$alias : string

Return values

array{entity: string, alias: string, table: string, on: array, bridge: string|null}|null

getExplicitJoins()


    public
                    getExplicitJoins() : array<string|int, array{entity: string, alias: string, table: string, on: array, bridge: string|null}>

Return values

array<string|int, array{entity: string, alias: string, table: string, on: array, bridge: string|null}>

getField()

Fetch a field from the getFields list


    public
                    getField(string $expr[, bool $strict = FALSE ]) : array<string|int, mixed>|bool|null

Parameters

$expr : string
$strict : bool = FALSE: In strict mode, this will throw an exception if the field doesn't exist

Return values

array<string|int, mixed>|bool|null

getFieldSibling()


    public
                    getFieldSibling(array<string|int, mixed> $field, string $siblingFieldName) : mixed

Parameters

$field : array<string|int, mixed>
$siblingFieldName : string

getFrom()


    public
                    getFrom() : false|string

Return values

false|string

getGroupBy()


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

Return values

array<string|int, mixed>

getHaving()


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

Return values

array<string|int, mixed>

getJoin()


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

Return values

array<string|int, mixed>

getJoinParent()

If a join is based on another join, return the name of the other.


    public
                    getJoinParent(string $joinAlias) : string|null

Parameters

$joinAlias : string

Return values

string|null

getLimit()


    public
                    getLimit() : mixed

getOffset()


    public
                    getOffset() : mixed

getOrderBy()


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

Return values

array<string|int, mixed>

getQuery()


    public
                    getQuery() : CRM_Utils_SQL_Select

Return values

CRM_Utils_SQL_Select

getResults()


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

Return values

array<string|int, mixed>

getSelect()


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

Return values

array<string|int, mixed>

getSql()

Builds main final sql statement after initialization.


    public
                    getSql() : string

Return values

string

getWhere()


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

Return values

array<string|int, mixed>

renderSerializedJoin()

Performs a virtual join with a serialized field using FIND_IN_SET


    public
            static        renderSerializedJoin(array<string|int, mixed> $field) : string

Parameters

$field : array<string|int, mixed>

Return values

string

run()

Why walk when you can


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

Return values

array<string|int, mixed>

treeWalkClauses()

Recursively validate and transform a branch or leaf clause array to SQL.


    public
                    treeWalkClauses(array<string|int, mixed> $clause, string $type[, int $depth = 0 ]) : string

Parameters

$clause : array<string|int, mixed>
$type : string: WHERE|HAVING|ON
$depth : int = 0

Return values

string —

SQL where clause

addBridgeJoin()

Join via a Bridge table using a join within a join


    protected
                    addBridgeJoin(array<string|int, mixed> $joinTree, string $joinEntity, string $alias) : mixed

This creates a double-join in sql that appears to the API user like a single join.

Parameters

$joinTree : array<string|int, mixed>
$joinEntity : string
$alias : string

autoJoinFK()

Joins a path and adds all fields in the joined entity to apiFieldSpec


    protected
                    autoJoinFK(mixed $key) : mixed

Parameters

$key : mixed

buildGroupBy()

Add GROUP BY clause to query


    protected
                    buildGroupBy() : mixed

buildHavingClause()

Add HAVING clause to query


    protected
                    buildHavingClause() : mixed

Every expression referenced must also be in the SELECT clause.

buildLimit()

Add LIMIT to query


    protected
                    buildLimit() : mixed

buildOrderBy()

Add ORDER BY to query


    protected
                    buildOrderBy() : mixed

buildSelectClause()


    protected
                    buildSelectClause([array<string|int, mixed> $select = NULL ]) : mixed

Parameters

$select : array<string|int, mixed> = NULL: Array of select expressions; defaults to $this->getSelect

buildWhereClause()

Add WHERE clause to query


    protected
                    buildWhereClause() : mixed

createSQLClause()


    protected
                    createSQLClause(string $fieldAlias, string $operator, mixed $value, array<string|int, mixed>|null $field, int $depth) : array<string|int, mixed>|string|null

Parameters

$fieldAlias : string
$operator : string
$value : mixed
$field : array<string|int, mixed>|null
$depth : int

Return values

array<string|int, mixed>|string|null

getExpression()


    protected
                    getExpression(string $expr[, array<string|int, mixed> $allowedTypes = NULL ]) : SqlExpression

Parameters

$expr : string
$allowedTypes : array<string|int, mixed> = NULL

Return values

SqlExpression

isAggregateQuery()


    protected
                    isAggregateQuery() : mixed

renderExpr()

Returns rendered expression or alias if it is already aliased in the SELECT clause.


    protected
                    renderExpr(mixed $expr) : mixed|string

Parameters

$expr : mixed

Return values

mixed|string

addExplicitJoins()

Join onto other entities as specified by the api call.


    private
                    addExplicitJoins() : mixed

addJoin()


    private
                    addJoin(string $side, string $tableName, string $tableAlias, string $baseTableAlias, array<string|int, mixed> $conditions) : void

Parameters

$side : string
$tableName : string
$tableAlias : string
$baseTableAlias : string
$conditions : array<string|int, mixed>

fillEntityValues()

This takes all the where clauses that use `=` to build an array of known values which every record must have.


    private
                    fillEntityValues() : mixed

This gets passed to FormattingUtil::getPseudoconstantList to evaluate conditional pseudoconstants.

finishJoin()


    private
                    finishJoin(string $side, mixed $conditions) : void

Parameters

$side : string
$conditions : mixed

getBridgeJoinConditions()

Extract bridge join conditions from the joinTree if any, else supply default conditions for join to base entity


    private
                    getBridgeJoinConditions(array<string|int, mixed> &$joinTree, CRM_Core_Reference_Basic $baseRef, string $alias, string $bridgeAlias, string $bridgeEntity, array<string|int, mixed> &$aclStack) : array<string|int, string>

Parameters

$joinTree : array<string|int, mixed>
$baseRef : CRM_Core_Reference_Basic
$alias : string
$bridgeAlias : string
$bridgeEntity : string
$aclStack : array<string|int, mixed>

Return values

array<string|int, string>

getBridgeLinkConditions()

Get the clause to link bridge entity with join entity


    private
                    getBridgeLinkConditions(string $bridgeAlias, string $joinAlias, string $joinEntity, CRM_Core_Reference_Basic $joinRef) : array<string|int, mixed>

Parameters

$bridgeAlias : string
$joinAlias : string
$joinEntity : string
$joinRef : CRM_Core_Reference_Basic

Return values

array<string|int, mixed>

getBridgeRefs()

Get the table name and 2 reference columns from a bridge entity


    private
                    getBridgeRefs(string $bridgeEntity, string $joinEntity) : array<string|int, mixed>

Parameters

$bridgeEntity : string
$joinEntity : string

Return values

array<string|int, mixed>

getJoinConditions()

Supply conditions for an explicit join.


    private
                    getJoinConditions(array<string|int, mixed> $joinTree, string $joinEntity, string $alias, array<string|int, mixed> $joinEntityFields) : array<string|int, mixed>

Parameters

$joinTree : array<string|int, mixed>
$joinEntity : string
$alias : string
$joinEntityFields : array<string|int, mixed>

Return values

array<string|int, mixed>

registerBridgeJoinFields()


    private
                    registerBridgeJoinFields(mixed $bridgeEntity, mixed $joinRef, mixed $baseRef, string $alias, string $bridgeAlias) : void

Parameters

$bridgeEntity : mixed
$joinRef : mixed
$baseRef : mixed
$alias : string
$bridgeAlias : string

selectMatchingFields()

Get all fields for SELECT clause matching a wildcard pattern


    private
                    selectMatchingFields(mixed $pattern) : array<string|int, mixed>

Parameters

$pattern : mixed

Return values

array<string|int, mixed>

startNewJoin()

Begins a new join; as long as it's "open" then additional joins will nest inside it.


    private
                    startNewJoin(string $tableName, string $joinAlias) : void

Parameters

$tableName : string
$joinAlias : string

Api4SelectQuery extends Api4Query in package Application

Table of Contents

Constants

Properties

Methods

Constants

MAIN_TABLE_ALIAS

UNLIMITED

Properties

$apiFieldSpec

$forceSelectId

$selectAliases

$aclFields

$api

$autoJoinSuffix

$entityValues

$joinTree

$query

$entityAccess

$explicitJoins

$openJoin

Methods

__construct()

Parameters

addSpecField()

Parameters

checkEntityAccess()

Parameters

Return values

composeClause()

Parameters

Tags

Return values

debug()

Parameters

getAclClause()

Parameters

Return values

getApiParam()

Parameters

getCheckPermissions()

Return values

getCount()

Tags

Return values

getEntity()

Return values

getExplicitJoin()

Parameters

Return values

getExplicitJoins()

Return values

getField()

Parameters

Tags

Return values

getFieldSibling()

Parameters

getFrom()

Return values

getGroupBy()

Return values

getHaving()

Return values

getJoin()

Return values

getJoinParent()

Parameters

Return values

getLimit()

getOffset()

getOrderBy()

Return values

getQuery()

Return values

getResults()

Return values

getSelect()

Return values

getSql()

Api4SelectQuery extends Api4Query
in package

Application