GetFields
extends BasicGetFieldsAction
in package
Get information about CiviCRM settings.
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.
- $domainId : int
- Domain id of settings. Leave NULL for default domain.
- $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
- getDomainId() : int
- getEntityName() : string
- 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.
- setDomainId() : $this
- 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>
- BasicGet is a general-purpose get action for non-DAO-based entities.
- limitArray() : array<string|int, 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.
- setFieldSuffixes() : mixed
- Set supported field suffixes based on available option keys
- sortCompare() : mixed
- walkFilters() : bool
Properties
$_debugOutput
public
mixed
$_debugOutput
= []
$_actionName
protected
string
$_actionName
$_entityName
protected
string
$_entityName
$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.
$domainId
Domain id of settings. Leave NULL for default domain.
protected
int
$domainId
$includeCustom
protected
bool
$includeCustom
$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
$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'soptions
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
= []
$_entityFields
private
array<string|int, mixed>
$_entityFields
$_id
private
int
$_id
Used to identify api calls for transactions
Tags
$_paramInfo
private
array<string|int, mixed>
$_paramInfo
$_reflection
private
ReflectionClass
$_reflection
$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
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
_run()
To implement getFields for your own entity:
public
_run(Result $result) : mixed
- From your entity class add a static getFields method.
- That method should construct and return this class.
- The 3rd argument passed to this constructor should be a function that returns an array of fields for your entity's CRUD actions.
- 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
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
$thisaddClause()
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
Return values
$thisaddOrderBy()
Adds to the orderBy clause
public
addOrderBy(string $fieldName[, string $direction = 'ASC' ]) : $this
Parameters
- $fieldName : string
- $direction : string = 'ASC'
Return values
$thisaddSelect()
Add one or more fields to be selected (wildcard * allowed)
public
addSelect(string ...$fieldNames) : $this
Parameters
- $fieldNames : string
Return values
$thisaddValue()
Add an item to the values array.
public
addValue(string $fieldName, mixed $value) : $this
Parameters
- $fieldName : string
- $value : mixed
Return values
$thisaddWhere()
public
addWhere(string $fieldName, string $op[, mixed $value = NULL ]) : $this
Parameters
- $fieldName : string
- $op : string
- $value : mixed = NULL
Tags
Return values
$thiscompareValues()
public
static compareValues(mixed $value, string $operator, mixed $expected) : bool
Parameters
- $value : mixed
- $operator : string
- $expected : mixed
Return values
boolentityFields()
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
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
Return values
boolexecute()
Invoke api call.
public
execute() : Result
At this point all the params have been sent in and we initiate the api call & return the result. This is basically the outer wrapper for api v4.
Tags
Return values
ResultexpandSelectClauseWildcards()
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
fields()
public
fields() : mixed
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
Return values
boolgetAction()
public
getAction() : string
Return values
stringgetActionName()
public
getActionName() : string
Return values
stringgetChain()
public
getChain() : array<string|int, mixed>
Return values
array<string|int, mixed>getCheckPermissions()
public
getCheckPermissions() : bool
Return values
boolgetDebug()
public
getDebug() : bool
Return values
boolgetDomainId()
public
getDomainId() : int
Return values
intgetEntityName()
public
getEntityName() : string
Return values
stringgetLanguage()
public
getLanguage() : string|null
Return values
string|nullgetLimit()
public
getLimit() : int
Return values
intgetLoadOptions()
public
getLoadOptions() : bool|array<string|int, mixed>
Return values
bool|array<string|int, mixed>getOffset()
public
getOffset() : int
Return values
intgetOrderBy()
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|nullgetValues()
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
Return values
booloffsetGet()
public
& offsetGet(mixed $offset) : mixed
Parameters
- $offset : mixed
Tags
Attributes
- #[ReturnTypeWillChange]
offsetSet()
public
offsetSet(mixed $offset, mixed $value) : void
Parameters
- $offset : mixed
- $value : mixed
Tags
offsetUnset()
public
offsetUnset(mixed $offset) : void
Parameters
- $offset : mixed
Tags
paramExists()
public
paramExists(string $param) : bool
Parameters
- $param : string
Return values
boolpseudoconstantOptions()
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
ReflectionClassselectRowCount()
Only return the number of found items.
public
selectRowCount() : $this
Return values
$thissetAction()
public
setAction([string $value = ]) : $this
Parameters
- $value : string =
Return values
$thissetChain()
public
setChain([array<string|int, mixed> $chain = ]) : $this
Parameters
- $chain : array<string|int, mixed> =
Return values
$thissetCheckPermissions()
public
setCheckPermissions(bool $checkPermissions) : $this
Parameters
- $checkPermissions : bool
Return values
$thissetDebug()
public
setDebug([bool $debug = ]) : $this
Enable/disable debug output
Parameters
- $debug : bool =
Return values
$thissetDefaultWhereClause()
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
setDomainId()
public
setDomainId([int $domainId = ]) : $this
Parameters
- $domainId : int =
Return values
$thissetLanguage()
public
setLanguage([string|null $language = ]) : $this
Parameters
- $language : string|null =
Return values
$thissetLimit()
public
setLimit([int $limit = ]) : $this
Parameters
- $limit : int =
Return values
$thissetLoadOptions()
public
setLoadOptions([bool|array<string|int, mixed> $value = ]) : $this
Parameters
- $value : bool|array<string|int, mixed> =
Return values
$thissetOffset()
public
setOffset([int $offset = ]) : $this
Parameters
- $offset : int =
Return values
$thissetOrderBy()
public
setOrderBy([array<string|int, mixed> $order = ]) : $this
Parameters
- $order : array<string|int, mixed> =
Return values
$thissetValues()
Overwrite all values
public
setValues(array<string|int, mixed> $values) : $this
Parameters
- $values : array<string|int, mixed>
Return values
$thissetValues()
public
setValues([array<string|int, mixed> $values = ]) : $this
Parameters
- $values : array<string|int, mixed> =
Return values
$thissetVersion()
public
setVersion(int $val) : $this
Parameters
- $val : int
Tags
Return values
$thissetWhere()
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
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
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
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()
BasicGet is a general-purpose get action for non-DAO-based entities.
protected
getRecords() : array<string|int, mixed>
Useful for fetching records from files or other places. Specify any php function to retrieve the records, and this class will automatically filter, sort, select & limit the raw data from the callback.
This action is implemented in one of two ways:
- Invoke this class directly by passing a callable ($getter) to the constructor. BasicEntity does this by default. The function is passed a copy of $this action as it's first argument.
- Extend this class and override this function.
Either way, this function should return an array of arrays, each representing one retrieved object.
The simplest thing for your getter function to do is return every full record and allow this class to automatically do the sorting and filtering.
Sometimes however that may not be practical for performance reasons. To optimize your getter, it can use the following helpers from $this:
Use this->_itemsToGet() to match records to field values in the WHERE clause. Note the WHERE clause can potentially be very complex and it is not recommended to parse $this->where yourself.
Use $this->_isFieldSelected() to check if a field value is called for - useful if loading the field involves expensive calculations.
Be careful not to make assumptions, e.g. if LIMIT 100 is specified and your getter "helpfully" truncates the list at 100 without accounting for WHERE, ORDER BY and LIMIT clauses, the final filtered result may be very incorrect.
Return values
array<string|int, mixed>limitArray()
protected
limitArray(mixed $values) : array<string|int, mixed>
Parameters
- $values : mixed
Return values
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
stringevaluateFilters()
private
evaluateFilters(array<string|int, mixed> $row) : bool
Parameters
- $row : array<string|int, mixed>
Return values
boolformatOptionList()
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>
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>