1. class
  2. Civi
  3. API
  4. SelectQuery

SelectQuery

class SelectQuery

Query builder for civicrm_api_basic_get.

Fetches an entity based on specified params for the "where" clause, return properties for the "select" clause, as well as limit and order.

Automatically joins on custom fields to return or filter by them.

Supports an additional sql fragment which the calling api can provide.

Constants

MAX_JOINS

MAIN_TABLE_ALIAS

Properties

protected string $entity
$select
$where
$orderBy
$limit
$offset
protected array $selectFields
bool $isFillUniqueFields
protected CRM_Utils_SQL_Select $query
protected array $joins
protected array $apiFieldSpec
protected array $entityFieldNames
protected array $aclFields
protected string|bool $checkPermissions
protected $apiVersion

Methods

__construct(string $entity, bool $checkPermissions)

No description

array|int
run()

Build & execute the query and return results array

SelectQuery
merge(CRM_Utils_SQL_Select $sqlFragment)

No description

array|null
addFkField($fkFieldName, $side)

Joins onto an fk field

getJoinInfo($fkField, $stack)

Get join info for dynamically-joined fields (e.g. "entity_id", "option_group")

array
addCustomField(array $customField, string $side, string $baseTable = self::MAIN_TABLE_ALIAS)

Joins onto a custom field

array|null
getField(string $fieldName)

Fetch a field from the getFields list

validateNestedInput($fieldName, $value)

Perform input validation on params that use the join syntax

bool
checkPermissionToJoin(string $entity, array $fieldStack)

Check permission to join onto another api entity

array
getAclClause(string $tableAlias, string $baoName, array $stack = array())

Get acl clause for an entity

buildOrderBy()

Orders the query by one or more fields

join(string $side, string $tableName, string $tableAlias, array $conditions)

No description

buildWhereClause()

Populate where clauses

buildSelectFields()

Populate $this->selectFields

array
getFields()

Load entity fields

Details

at line 97
__construct(string $entity, bool $checkPermissions)

Parameters

string $entity
bool $checkPermissions

at line 122
array|int run()

Build & execute the query and return results array

Return Value

array|int

Exceptions

API_Exception
CRM_Core_Exception
Exception

at line 176
SelectQuery merge(CRM_Utils_SQL_Select $sqlFragment)

Parameters

CRM_Utils_SQL_Select $sqlFragment

Return Value

SelectQuery

at line 196
protected array|null addFkField($fkFieldName, $side)

Joins onto an fk field

Adds one or more joins to the query to make this field available for use in a clause.

Enforces permissions at the api level and by appending the acl clause for that entity to the join.

Parameters

$fkFieldName
$side

Return Value

array|null Returns the table and field name for adding this field to a SELECT or WHERE clause

Exceptions

API_Exception
UnauthorizedException

at line 271
protected getJoinInfo($fkField, $stack)

Get join info for dynamically-joined fields (e.g. "entity_id", "option_group")

Parameters

$fkField
$stack

at line 299
protected array addCustomField(array $customField, string $side, string $baseTable = self::MAIN_TABLE_ALIAS)

Joins onto a custom field

Adds a join to the query to make this field available for use in a clause.

Parameters

array $customField
string $side
string $baseTable

Return Value

array Returns the table and field name for adding this field to a SELECT or WHERE clause

at line 313
abstract protected array|null getField(string $fieldName)

Fetch a field from the getFields list

Parameters

string $fieldName

Return Value

array|null

at line 325
protected validateNestedInput($fieldName, $value)

Perform input validation on params that use the join syntax

Arguably this should be done at the api wrapper level, but doing it here provides a bit more consistency in that api permissions to perform the join are checked first.

Parameters

$fieldName
$value

Exceptions

Exception

at line 346
protected bool checkPermissionToJoin(string $entity, array $fieldStack)

Check permission to join onto another api entity

Parameters

string $entity
array $fieldStack The stack of fields leading up to this join

Return Value

bool

at line 380
protected array getAclClause(string $tableAlias, string $baoName, array $stack = array())

Get acl clause for an entity

Parameters

string $tableAlias
string $baoName
array $stack

Return Value

array

at line 404
protected buildOrderBy()

Orders the query by one or more fields

Exceptions

API_Exception
UnauthorizedException

at line 438
join(string $side, string $tableName, string $tableAlias, array $conditions)

Parameters

string $side
string $tableName
string $tableAlias
array $conditions

at line 452
abstract protected buildWhereClause()

Populate where clauses

Exceptions

UnauthorizedException
Exception

at line 459
protected buildSelectFields()

Populate $this->selectFields

Exceptions

UnauthorizedException

at line 508
abstract protected array getFields()

Load entity fields

Return Value

array