Documentation

DAOGetFieldsAction extends BasicGetFieldsAction
in package

Lists information about fields for the $ENTITY entity.

Tags
inheritDoc

Table of Contents

Properties

$_debugOutput  : mixed
$_actionName  : string
$_entityName  : string
$action  : string
Fields will be returned appropriate to the specified action (get, create, delete, etc.)
$chain  : array<string|int, mixed>
Additional api requests - will be called once per result.
$checkPermissions  : bool
Whether to enforce acl permissions based on the current user.
$debug  : bool
Add debugging info to the api result.
$includeCustom  : bool
$language  : string
Preferred language (optional)
$limit  : int
Maximum number of $ENTITIES to return.
$loadOptions  : bool|array<string|int, mixed>
Fetch option lists for fields?
$offset  : int
Zero-based index of first $ENTITY to return.
$orderBy  : array<string|int, mixed>
Array of field(s) to use in ordering the results.
$select  : array<string|int, mixed>
Fields to return for each $ENTITY. Defaults to all fields `[*]`.
$values  : array<string|int, mixed>
Fields will be returned appropriate to the specified values (e.g. ['contact_type' => 'Individual'])
$version  : int
Api version number; cannot be changed.
$where  : array<string|int, mixed>
Criteria for selecting $ENTITIES.
$_arrayStorage  : array<string|int, mixed>
$_entityFields  : array<string|int, mixed>
$_id  : int
$_paramInfo  : array<string|int, mixed>
$_reflection  : ReflectionClass
$getter  : callable

Methods

__call()  : static|mixed
Magic function to provide automatic getter/setter for params.
__construct()  : mixed
Basic Get constructor.
__set()  : mixed
Strictly enforce api parameters
_run()  : mixed
To implement getFields for your own entity:
addChain()  : $this
addClause()  : $this
Adds one or more AND/OR/NOT clause groups
addOrderBy()  : $this
Adds to the orderBy clause
addSelect()  : $this
Add one or more fields to be selected (wildcard * allowed)
addValue()  : $this
Add an item to the values array.
addWhere()  : $this
compareValues()  : bool
entityFields()  : array<string|int, mixed>
Returns schema fields for this entity & action.
evaluateCondition()  : bool
This function is used internally for evaluating field annotations.
execute()  : Result
Invoke api call.
expandSelectClauseWildcards()  : mixed
Adds all standard fields matched by the * wildcard
fields()  : mixed
filterCompare()  : bool
getAction()  : string
getActionName()  : string
getChain()  : array<string|int, mixed>
getCheckPermissions()  : bool
getDebug()  : bool
getEntityName()  : string
getIncludeCustom()  : bool
getLanguage()  : string|null
getLimit()  : int
getLoadOptions()  : bool|array<string|int, mixed>
getOffset()  : int
getOrderBy()  : array<string|int, mixed>
getParamInfo()  : array<string|int, mixed>
Get documentation for one or all params
getParams()  : array<string|int, mixed>
Serialize this object's params into an array
getPermissions()  : array<string|int, mixed>
getValue()  : mixed|null
Retrieve a single value, transforming pseudoconstants as necessary
getValues()  : array<string|int, mixed>
getValues()  : array<string|int, mixed>
getWhere()  : array<string|int, mixed>
offsetExists()  : bool
offsetGet()  : mixed
offsetSet()  : void
offsetUnset()  : void
paramExists()  : bool
pseudoconstantOptions()  : mixed
Helper function to retrieve options from an option group (for non-DAO entities).
reflect()  : ReflectionClass
selectRowCount()  : $this
Only return the number of found items.
setAction()  : $this
setChain()  : $this
setCheckPermissions()  : $this
setDebug()  : $this
setDefaultWhereClause()  : mixed
Adds field defaults to the where clause.
setLanguage()  : $this
setLimit()  : $this
setLoadOptions()  : $this
setOffset()  : $this
setOrderBy()  : $this
setValues()  : $this
Overwrite all values
setValues()  : $this
setVersion()  : $this
setWhere()  : $this
_isFieldSelected()  : bool
Helper to see if field(s) should be selected by the getRecords function.
_itemsToGet()  : array<string|int, mixed>|null
Helper to parse the WHERE param for getRecords to perform simple pre-filtering.
_whereContains()  : bool
Walk through the where clause and check if field(s) are in use.
addCallbackToDebugOutput()  : mixed
When in debug mode, this logs the callback function being used by a Basic*Action class.
checkRequiredFields()  : array<string|int, mixed>
Validates required fields for actions which create a new object.
filterArray()  : array<string|int, mixed>
formatRawValues()  : mixed
Evaluate :pseudoconstant suffix expressions and replace raw values with option values
formatResults()  : mixed
Ensure every result contains, at minimum, the array keys as defined in $this->fields.
formatWriteValues()  : mixed
Replaces pseudoconstants in input values
getLanguageOptions()  : array<string|int, mixed>
Get available preferred languages.
getMagicProperties()  : array<string|int, mixed>
Get a list of class properties for which magic methods are supported.
getParamDefaults()  : array<string|int, mixed>
getRecords()  : array<string|int, mixed>
Get fields for a DAO-based entity.
limitArray()  : array<string|int, mixed>
loadFieldOptions()  : mixed
queryArray()  : mixed
selectArray()  : array<string|int, mixed>
sortArray()  : array<string|int, mixed>
whereClauseToString()  : string
Produces a human-readable where clause, for the reading enjoyment of you humans.
evaluateFilters()  : bool
formatOptionList()  : mixed
Sets `options` and `suffixes` based on pseudoconstant if given.
formatValues()  : mixed
Special handling for pseudoconstant replacements.
getFkFieldSpec()  : array<string|int, mixed>|null
setFieldSuffixes()  : mixed
Set supported field suffixes based on available option keys
sortCompare()  : mixed
walkFilters()  : bool

Properties

$action

Fields will be returned appropriate to the specified action (get, create, delete, etc.)

protected string $action = 'get'

$chain

Additional api requests - will be called once per result.

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

Keys can be any string - this will be the name given to the output.

You can reference other values in the api results in this call by prefixing them with $.

For example, you could create a contact and place them in a group by chaining the GroupContact api to the Contact api:

Contact::create()
  ->setValue('first_name', 'Hello')
  ->addChain('add_a_group', GroupContact::create()
    ->setValue('contact_id', '$id')
    ->setValue('group_id', 123)
  )

This will substitute the id of the newly created contact with $id.

$checkPermissions

Whether to enforce acl permissions based on the current user.

protected bool $checkPermissions = TRUE

Setting to FALSE will disable permission checks and override ACLs. In REST/javascript this cannot be disabled.

$debug

Add debugging info to the api result.

protected bool $debug = FALSE

When enabled, $result->debug will be populated with information about the api call, including sql queries executed.

Note: with checkPermissions enabled, debug info will only be returned if the user has "view debug output" permission.

$language

Preferred language (optional)

protected string $language

This option will notify major localization subsystems (ts(), multilingual, etc) about which locale should be used for composing/formatting messaging.

This indicates the preferred language. The effective language is determined by Civi\Core\Locale::negotiate($preferredLanguage).

Tags
optionsCallback

getLanguageOptions

$limit

Maximum number of $ENTITIES to return.

protected int $limit = 0

Defaults to 0 - unlimited.

Note: the Api Explorer sets this to 25 by default to avoid timeouts. Change or remove this default for your application code.

$loadOptions

Fetch option lists for fields?

protected bool|array<string|int, mixed> $loadOptions = FALSE

This parameter can be either a boolean or an array of attributes to return from the option list:

  • If FALSE, each field's options property will be a boolean indicating whether the field has an option list
  • If TRUE, options will be returned as a flat array of the option list's [id => label]
  • If an array, options will be a non-associative array of requested properties: id, name, label, abbr, description, color, icon e.g. loadOptions: ['id', 'name', 'label'] will return an array like [[id: 1, name: 'Meeting', label: 'Meeting'], ...] (note that names and labels are generally ONLY the same when the site's language is set to English).

$offset

Zero-based index of first $ENTITY to return.

protected int $offset = 0

Defaults to 0 - first $ENTITY found.

$orderBy

Array of field(s) to use in ordering the results.

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

Defaults to id ASC

$example->addOrderBy('sort_name', 'ASC')

$select

Fields to return for each $ENTITY. Defaults to all fields `[*]`.

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

Use the * wildcard by itself to select all available fields, or use it to match similarly-named fields. E.g. is_* will match fields named is_primary, is_active, etc.

Set to ["row_count"] to return only the number of $ENTITIES found.

$values

Fields will be returned appropriate to the specified values (e.g. ['contact_type' => 'Individual'])

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

$version

Api version number; cannot be changed.

protected int $version = 4

$where

Criteria for selecting $ENTITIES.

protected array<string|int, mixed> $where = []
$example->addWhere('contact_type', 'IN', ['Individual', 'Household'])

$_arrayStorage

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

$getter

private callable $getter

Function(BasicGetAction $thisAction): array[]

Methods

__call()

Magic function to provide automatic getter/setter for params.

public __call(mixed $name, mixed $arguments) : static|mixed
Parameters
$name : mixed
$arguments : mixed
Tags
throws
CRM_Core_Exception
Return values
static|mixed

__construct()

Basic Get constructor.

public __construct(string $entityName, string $actionName[, callable $getter = NULL ]) : mixed
Parameters
$entityName : string
$actionName : string
$getter : callable = NULL

__set()

Strictly enforce api parameters

public __set(mixed $name, mixed $value) : mixed
Parameters
$name : mixed
$value : mixed
Tags
throws
Exception

_run()

To implement getFields for your own entity:

public _run(Result $result) : mixed
  1. From your entity class add a static getFields method.
  2. That method should construct and return this class.
  3. The 3rd argument passed to this constructor should be a function that returns an array of fields for your entity's CRUD actions.
  4. For non-crud actions that need a different set of fields, you can override the list from step 3 on a per-action basis by defining a fields() method in that action. See for example BasicGetFieldsAction::fields() or GetActions::fields().
Parameters
$result : Result
Tags
throws
NotImplementedException

addChain()

public addChain(string $name, AbstractAction $apiRequest[, string|int|array<string|int, mixed> $index = NULL ]) : $this
Parameters
$name : string

Unique name for this chained request

$apiRequest : AbstractAction
$index : string|int|array<string|int, mixed> = NULL

See civicrm_api4() for documentation of $index param

Return values
$this

addClause()

Adds one or more AND/OR/NOT clause groups

public addClause(string $operator, mixed $condition1) : $this
Parameters
$operator : string
$condition1 : mixed

... $conditionN Either a nested array of arguments, or a variable number of arguments passed to this function.

Tags
throws
CRM_Core_Exception
Return values
$this

addOrderBy()

Adds to the orderBy clause

public addOrderBy(string $fieldName[, string $direction = 'ASC' ]) : $this
Parameters
$fieldName : string
$direction : string = 'ASC'
Return values
$this

addSelect()

Add one or more fields to be selected (wildcard * allowed)

public addSelect(string ...$fieldNames) : $this
Parameters
$fieldNames : string
Return values
$this

addValue()

Add an item to the values array.

public addValue(string $fieldName, mixed $value) : $this
Parameters
$fieldName : string
$value : mixed
Return values
$this

addWhere()

public addWhere(string $fieldName, string $op[, mixed $value = NULL ]) : $this
Parameters
$fieldName : string
$op : string
$value : mixed = NULL
Tags
throws
CRM_Core_Exception
Return values
$this

compareValues()

public static compareValues(mixed $value, string $operator, mixed $expected) : bool
Parameters
$value : mixed
$operator : string
$expected : mixed
Return values
bool

entityFields()

Returns schema fields for this entity & action.

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

Here we bypass the api wrapper and run the getFields action directly. This is because we DON'T want the wrapper to check permissions as this is an internal op.

Tags
see
GetFields
throws
CRM_Core_Exception
Return values
array<string|int, mixed>

evaluateCondition()

This function is used internally for evaluating field annotations.

public static evaluateCondition(string $expr, array<string|int, mixed> $vars) : bool

It should never be passed raw user input.

Parameters
$expr : string

Conditional in php format e.g. $foo > $bar

$vars : array<string|int, mixed>

Variable name => value

Tags
throws
CRM_Core_Exception
throws
Exception
Return values
bool

expandSelectClauseWildcards()

Adds all standard fields matched by the * wildcard

public expandSelectClauseWildcards() : mixed

Note: this function only deals with simple wildcard expressions. It ignores those containing special characters like dots or parentheses, they are handled separately in Api4SelectQuery.

Tags
throws
CRM_Core_Exception

filterCompare()

public static filterCompare(array<string|int, mixed> $row, array<string|int, mixed> $condition[, int|null $index = NULL ]) : bool
Parameters
$row : array<string|int, mixed>
$condition : array<string|int, mixed>
$index : int|null = NULL
Tags
throws
NotImplementedException
Return values
bool

getActionName()

public getActionName() : string
Return values
string

getChain()

public getChain() : array<string|int, mixed>
Return values
array<string|int, mixed>

getCheckPermissions()

public getCheckPermissions() : bool
Return values
bool

getEntityName()

public getEntityName() : string
Return values
string

getLanguage()

public getLanguage() : string|null
Return values
string|null

getLoadOptions()

public getLoadOptions() : bool|array<string|int, mixed>
Return values
bool|array<string|int, mixed>

getOrderBy()

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

getParamInfo()

Get documentation for one or all params

public getParamInfo([string $param = NULL ]) : array<string|int, mixed>
Parameters
$param : string = NULL
Return values
array<string|int, mixed>

of arrays [description, type, default, (comment)]

getParams()

Serialize this object's params into an array

public getParams() : array<string|int, mixed>
Return values
array<string|int, mixed>

getPermissions()

public getPermissions() : array<string|int, mixed>
Return values
array<string|int, mixed>

getValue()

Retrieve a single value, transforming pseudoconstants as necessary

public getValue(string $fieldExpr) : mixed|null
Parameters
$fieldExpr : string
Return values
mixed|null

getValues()

public getValues() : array<string|int, mixed>
Return values
array<string|int, mixed>

getValues()

public getValues() : array<string|int, mixed>
Return values
array<string|int, mixed>

getWhere()

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

offsetExists()

public offsetExists(mixed $offset) : bool
Parameters
$offset : mixed
Tags
inheritDoc
Return values
bool

offsetGet()

public & offsetGet(mixed $offset) : mixed
Parameters
$offset : mixed
Tags
inheritDoc
Attributes
#[ReturnTypeWillChange]

offsetSet()

public offsetSet(mixed $offset, mixed $value) : void
Parameters
$offset : mixed
$value : mixed
Tags
inheritDoc

offsetUnset()

public offsetUnset(mixed $offset) : void
Parameters
$offset : mixed
Tags
inheritDoc

paramExists()

public paramExists(string $param) : bool
Parameters
$param : string
Return values
bool

pseudoconstantOptions()

Helper function to retrieve options from an option group (for non-DAO entities).

public pseudoconstantOptions(string $optionGroupName) : mixed
Parameters
$optionGroupName : string

reflect()

public reflect() : ReflectionClass
Return values
ReflectionClass

selectRowCount()

Only return the number of found items.

public selectRowCount() : $this
Return values
$this

setAction()

public setAction([string $value = ]) : $this
Parameters
$value : string =
Return values
$this

setChain()

public setChain([array<string|int, mixed> $chain = ]) : $this
Parameters
$chain : array<string|int, mixed> =
Return values
$this

setCheckPermissions()

public setCheckPermissions(bool $checkPermissions) : $this
Parameters
$checkPermissions : bool
Return values
$this

setDebug()

public setDebug([bool $debug = ]) : $this

Enable/disable debug output

Parameters
$debug : bool =
Return values
$this

setDefaultWhereClause()

Adds field defaults to the where clause.

public setDefaultWhereClause() : mixed

Note: it will skip adding field defaults when fetching records by id, or if that field has already been added to the where clause.

Tags
throws
CRM_Core_Exception

setLanguage()

public setLanguage([string|null $language = ]) : $this
Parameters
$language : string|null =
Return values
$this

setLimit()

public setLimit([int $limit = ]) : $this
Parameters
$limit : int =
Return values
$this

setLoadOptions()

public setLoadOptions([bool|array<string|int, mixed> $value = ]) : $this
Parameters
$value : bool|array<string|int, mixed> =
Return values
$this

setOffset()

public setOffset([int $offset = ]) : $this
Parameters
$offset : int =
Return values
$this

setOrderBy()

public setOrderBy([array<string|int, mixed> $order = ]) : $this
Parameters
$order : array<string|int, mixed> =
Return values
$this

setValues()

Overwrite all values

public setValues(array<string|int, mixed> $values) : $this
Parameters
$values : array<string|int, mixed>
Return values
$this

setValues()

public setValues([array<string|int, mixed> $values = ]) : $this
Parameters
$values : array<string|int, mixed> =
Return values
$this

setWhere()

public setWhere([array<string|int, mixed> $wheres = ]) : $this
Parameters
$wheres : array<string|int, mixed> =
Return values
$this

_isFieldSelected()

Helper to see if field(s) should be selected by the getRecords function.

protected _isFieldSelected(string ...$fieldNames) : bool

Checks the SELECT, WHERE and ORDER BY params to see what fields are needed.

Note that if no SELECT clause has been set then all fields should be selected and this function will return TRUE for field expressions that don't contain a :pseudoconstant suffix.

Parameters
$fieldNames : string

One or more field names to check (uses OR if multiple)

Return values
bool

Returns true if any given fields are in use.

_itemsToGet()

Helper to parse the WHERE param for getRecords to perform simple pre-filtering.

protected _itemsToGet(string $field) : array<string|int, mixed>|null

This is intended to optimize some common use-cases e.g. calling the api to get one or more records by name or id.

Ex: If getRecords fetches a long list of items each with a unique name, but the user has specified a single record to retrieve, you can optimize the call by checking $this->_itemsToGet('name') and only fetching the item(s) with that name.

Parameters
$field : string
Return values
array<string|int, mixed>|null

_whereContains()

Walk through the where clause and check if field(s) are in use.

protected _whereContains(string|array<string|int, mixed> $fieldName[, array<string|int, mixed> $clauses = NULL ]) : bool
Parameters
$fieldName : string|array<string|int, mixed>

A single fieldName or an array of names (uses OR if multiple)

$clauses : array<string|int, mixed> = NULL
Return values
bool

Returns true if any given fields are found in the where clause.

addCallbackToDebugOutput()

When in debug mode, this logs the callback function being used by a Basic*Action class.

protected addCallbackToDebugOutput(callable $callable) : mixed
Parameters
$callable : callable

checkRequiredFields()

Validates required fields for actions which create a new object.

protected checkRequiredFields(mixed $values) : array<string|int, mixed>
Parameters
$values : mixed
Tags
throws
CRM_Core_Exception
Return values
array<string|int, mixed>

filterArray()

protected filterArray(array<string|int, mixed> $values) : array<string|int, mixed>
Parameters
$values : array<string|int, mixed>
Return values
array<string|int, mixed>

formatRawValues()

Evaluate :pseudoconstant suffix expressions and replace raw values with option values

protected formatRawValues(mixed &$records) : mixed
Parameters
$records : mixed
Tags
throws
CRM_Core_Exception

formatResults()

Ensure every result contains, at minimum, the array keys as defined in $this->fields.

protected formatResults(array<string|int, mixed> &$values, bool $isInternal) : mixed

Attempt to set some sensible defaults for some fields.

Format option lists.

In most cases it's not necessary to override this function, even if your entity is really weird. Instead just override $this->fields and this function will respect that.

Parameters
$values : array<string|int, mixed>
$isInternal : bool

formatWriteValues()

Replaces pseudoconstants in input values

protected formatWriteValues(array<string|int, mixed> &$record) : mixed
Parameters
$record : array<string|int, mixed>
Tags
throws
CRM_Core_Exception

getLanguageOptions()

Get available preferred languages.

protected getLanguageOptions() : array<string|int, mixed>
Return values
array<string|int, mixed>

getMagicProperties()

Get a list of class properties for which magic methods are supported.

protected static getMagicProperties() : array<string|int, mixed>
Return values
array<string|int, mixed>

List of supported properties, keyed by property name. Array(string $propertyName => bool $true).

getParamDefaults()

protected getParamDefaults() : array<string|int, mixed>
Return values
array<string|int, mixed>

getRecords()

Get fields for a DAO-based entity.

protected getRecords() : array<string|int, mixed>
Return values
array<string|int, mixed>

limitArray()

protected limitArray(mixed $values) : array<string|int, mixed>
Parameters
$values : mixed
Return values
array<string|int, mixed>

loadFieldOptions()

protected loadFieldOptions(array<string|int, mixed> &$fields, array<string|int, mixed> $fieldsToGet) : mixed
Parameters
$fields : array<string|int, mixed>
$fieldsToGet : array<string|int, mixed>

queryArray()

protected queryArray(array<string|int, mixed> $values, Result $result) : mixed
Parameters
$values : array<string|int, mixed>

List of all rows to be filtered

$result : Result

Object to store result

selectArray()

protected selectArray(mixed $values) : array<string|int, mixed>
Parameters
$values : mixed
Return values
array<string|int, mixed>

sortArray()

protected sortArray(mixed $values) : array<string|int, mixed>
Parameters
$values : mixed
Return values
array<string|int, mixed>

whereClauseToString()

Produces a human-readable where clause, for the reading enjoyment of you humans.

protected whereClauseToString([array<string|int, mixed> $whereClause = NULL ][, string $op = 'AND' ]) : string
Parameters
$whereClause : array<string|int, mixed> = NULL
$op : string = 'AND'
Return values
string

evaluateFilters()

private evaluateFilters(array<string|int, mixed> $row) : bool
Parameters
$row : array<string|int, mixed>
Return values
bool

formatOptionList()

Sets `options` and `suffixes` based on pseudoconstant if given.

private formatOptionList(array<string|int, mixed> &$field) : mixed

Transforms option list into the format specified in $this->loadOptions.

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

formatValues()

Special handling for pseudoconstant replacements.

private formatValues() : mixed

Normally this would involve calling getFields... but this IS getFields.

Tags
throws
CRM_Core_Exception

getFkFieldSpec()

private getFkFieldSpec(string $fieldName, array<string|int, mixed> $fields) : array<string|int, mixed>|null
Parameters
$fieldName : string
$fields : array<string|int, mixed>
Tags
throws
CRM_Core_Exception
Return values
array<string|int, mixed>|null

setFieldSuffixes()

Set supported field suffixes based on available option keys

private setFieldSuffixes(array<string|int, mixed> &$field) : mixed
Parameters
$field : array<string|int, mixed>

sortCompare()

private sortCompare(mixed $a, mixed $b) : mixed
Parameters
$a : mixed
$b : mixed

walkFilters()

private walkFilters(array<string|int, mixed> $row, array<string|int, mixed> $filters) : bool
Parameters
$row : array<string|int, mixed>
$filters : array<string|int, mixed>
Tags
throws
NotImplementedException
Return values
bool

        
On this page

Search results